Como criar uma caixa de entrada de canal de API?

Última atualização em 10 de Abr, 2024

Para criar e configurar uma caixa de entrada de canal de API nas instalações do Yuzap, siga os passos descritos abaixo.

Configure o canal de API

Passo 1. Vá para Configurações → Caixas de Entrada → "Adicionar Caixa de Entrada".

[Placeholder para Imagem: Navegação para Adicionar Caixa de Entrada no Yuzap]

Passo 2. Clique no ícone "API".

[Placeholder para Imagem: Seleção do canal API no Yuzap]

Passo 3. Forneça um nome para o canal e uma URL de callback. Aqui está um exemplo:

[Placeholder para Imagem: Configuração do nome e URL de callback do canal API no Yuzap]

Passo 4. "Adicione agentes" à sua caixa de entrada de API.

[Placeholder para Imagem: Adição de agentes à caixa de entrada API no Yuzap]

A configuração da caixa de entrada está completa.

Envie mensagens para o canal de API

Para enviar mensagens para o canal de API, certifique-se de entender os seguintes modelos e nomenclatura usados no Yuzap (Nota: Link para nomenclatura precisa ser atualizado).

1. Canal: Canal define o tipo de fonte das conversas. Ex., Facebook, Twitter, API, etc.

2. Caixa de Entrada: Você pode criar múltiplas fontes de conversas do mesmo tipo de canal. Ex., Você pode ter mais de uma página do Facebook conectada a uma conta Yuzap. Cada página é chamada de caixa de entrada no Yuzap.

3. Conversa: Uma Conversa é uma coleção de mensagens.

4. Contato: Cada conversa tem uma pessoa real associada a ela, chamada de contato.

5. Caixas de Entrada do Contato: Esta é a sessão para cada contato em uma caixa de entrada. Um contato pode ter múltiplas sessões e múltiplas conversas na mesma caixa de entrada.

Como enviar uma mensagem em um Canal de API?

Para enviar uma mensagem em um canal de API, crie um contato, inicie uma conversa e, finalmente, envie a mensagem.

As APIs requerem api_access_token no cabeçalho da requisição. Você pode obter este token visitando suas Configurações de Perfil → Token de Acesso.

1. Crie um contato

Ref: Documentação da API Yuzap (Nota: Link precisa ser atualizado)

Passe o ID da caixa de entrada (inbox_id) do canal de API junto com outros parâmetros especificados. Isso criaria uma sessão para você automaticamente. Uma resposta de exemplo seria parecida com esta abaixo.

{
  "email": "string",
  "name": "string",
  "phone_number": "string",
  "thumbnail": "string",
  "additional_attributes": {},
  "contact_inboxes": [
    {
      "source_id": "string",
      "inbox": {
        "id": 0,
        "name": "string",
        "website_url": "string",
        "channel_type": "string",
        "avatar_url": "string",
        "widget_color": "string",
        "website_token": "string",
        "enable_auto_assignment": true,
        "web_widget_script": "string",
        "welcome_title": "string",
        "welcome_tagline": "string",
        "greeting_enabled": true,
        "greeting_message": "string"
      }
    }
  ],
  "id": 0,
  "availability_status": "string"
}

Como você pode ver no payload, você poderá ver as contact_inboxes e cada contact_inbox terá um source_id. O ID da Fonte pode ser visto como o identificador da sessão. Você usará este source_id para criar uma nova conversa conforme definido abaixo.

2. Crie uma conversa

Ref: Documentação da API Yuzap (Nota: Link precisa ser atualizado)

Use o source_id recebido na chamada de API anterior. Você receberá um ID de conversa que pode ser usado para criar uma mensagem.

{
  "id": 0
}

3. Crie uma nova mensagem

Ref: Documentação da API Yuzap (Nota: Link precisa ser atualizado)

Existem 2 tipos de mensagens.

1. Entrada (Incoming): Mensagens enviadas pelo usuário final são classificadas como mensagem de entrada.

2. Saída (Outgoing): Mensagens enviadas pelo agente são classificadas como mensagem de saída.

Se você chamar a API com o conteúdo correto, receberá um payload semelhante a este:

{
  "id": 0,
  "content": "Esta é uma mensagem de entrada do Canal API",
  "inbox_id": 0,
  "conversation_id": 0,
  "message_type": 0,
  "content_type": null,
  "content_attributes": {},
  "created_at": 0,
  "private": false,
  "sender": {
    "id": 0,
    "name": "Pranav",
    "type": "contact"
  }
}

Se tudo for bem-sucedido, você verá a conversa no painel da seguinte forma.

[Placeholder para Imagem: Exemplo de conversa no painel Yuzap via API]

Você será notificado quando uma nova mensagem for criada na URL especificada ao criar o canal de API. Você pode ler sobre o payload da mensagem aqui (Nota: Link precisa ser atualizado).

Receba mensagens usando a URL de callback

Quando uma nova mensagem é criada no canal de API, você receberá uma requisição POST para a URL de Callback especificada ao criar o canal de API. O payload será parecido com este.

Encontre a lista completa de eventos suportados pelo webhook aqui (Nota: Link precisa ser atualizado).

Tipo de evento: message_created

{
  "id": 0,
  "content": "Esta é uma mensagem de entrada do Canal API",
  "created_at": "2020-08-30T15:43:04.000Z",
  "message_type": "incoming",
  "content_type": null,
  "content_attributes": {},
  "source_id": null,
  "sender": {
    "id": 0,
    "name": "contact-name",
    "avatar": "",
    "type": "contact"
  },
  "inbox": {
    "id": 0,
    "name": "Canal API"
  },
  "conversation": {
    "additional_attributes": null,
    "channel": "Channel::Api",
    "id": 0,
    "inbox_id": 0,
    "status": "open",
    "agent_last_seen_at": 0,
    "contact_last_seen_at": 0,
    "timestamp": 0
  },
  "account": {
    "id": 1,
    "name": "Teste API"
  },
  "event": "message_created"
}

Crie Interfaces usando APIs do cliente

As APIs do Cliente disponíveis para o canal de API ajudarão você a construir interfaces voltadas para o cliente para o Yuzap.

Essas APIs são úteis para casos como os listados abaixo.

1. Use uma interface de chat personalizada em vez do widget de chat do Yuzap.

2. Construa interfaces de conversação em seus aplicativos móveis.

3. Adicione o Yuzap a outras plataformas para as quais o Yuzap não possui um SDK oficial.

Criando objetos de cliente

Você pode criar e recuperar objetos de dados do cliente usando o inbox_identifier e customer_identifier.

Identificador da Caixa de Entrada

Você pode obter o inbox_identifier do seu canal de API -> Configurações -> Configuração.

Identificador do Cliente

O customer_identifier ou o source_id podem ser obtidos ao criar o cliente usando a API de criação (Nota: Link precisa ser atualizado). Você precisará armazenar este identificador no lado do cliente para fazer futuras requisições em nome do cliente. Isso pode ser feito em cookies, armazenamento local etc.

APIs Disponíveis

As APIs do Cliente disponíveis estão documentadas aqui (Nota: Link precisa ser atualizado). Algumas das coisas que você pode fazer com as APIs são:

• Criar, Visualizar e Atualizar Contato

• Criar e Listar Conversas

• Criar, Listar e Atualizar Mensagens

Autenticação HMAC

As APIs do Cliente também suportam Autenticação HMAC (Nota: Link precisa ser atualizado). O token HMAC para o Canal pode ser obtido executando o seguinte no seu console rails (se aplicável ao Yuzap).

# substitua api_inbox_id pelo id da sua caixa de entrada
Inbox.find(api_inbox_id).channel.hmac_token

Conectando aos WebSockets do Yuzap

Para obter atualizações em tempo real do painel do agente, conecte-se aos WebSockets do Yuzap usando a seguinte URL.

<sua_url_instalacao_yuzap>/cable

Autenticando sua conexão WebSocket

Após se inscrever usando o pubsub_token do cliente, você receberá eventos direcionados ao seu objeto de cliente. O pubsub_token é fornecido durante a chamada da API de criação do cliente.

Exemplo

const connection = new WebSocket('ws://localhost:3000/cable'); // Adapte a URL para Yuzap
connection.send(JSON.stringify({ command:"subscribe", identifier: "{\"channel\":\"RoomChannel\",\"pubsub_token\":\"YOUR_TOKEN\"}" }));

Encontre a lista completa de eventos suportados por WebSockets aqui (Nota: Link precisa ser atualizado).

Implementação

Aqui está um exemplo (Nota: Link precisa ser atualizado) de interface de chat construída sobre as APIs do Cliente.