Como criar uma caixa de entrada de canal de API
Para criar e configurar uma caixa de entrada de canal de API em instalações do Chatwoot, siga os passos descritos
abaixo.
Configurar o canal de API
Etapa 1. Acesse Configurações → Caixas de Entrada → “Adicionar Caixa de Entrada”.
Etapa 2. Clique no ícone "API".
Etapa 3. Forneça um nome para o canal e uma URL de retorno. Aqui está um exemplo:
Etapa 4. "Adicione agentes" à sua caixa de entrada de API.
A configuração da caixa de entrada foi concluída.
Enviar mensagens para o canal da API
Para enviar mensagens para o canal da API, certifique-se de entender os seguintes modelos e nomenclatura usados no
Chatwoot.
1. Canal: O canal define o tipo de fonte das conversas. Ex.: Facebook, Twitter, API, etc.
2. Caixa de entrada: Você pode criar várias fontes de conversas do mesmo tipo de canal. Ex.: Você pode ter mais de uma
página do Facebook conectada a uma conta do Chatwoot. Cada página é chamada de caixa de entrada no Chatwoot.
3. Conversa: Uma conversa é um conjunto de mensagens.
4. Contato: Cada conversa tem uma pessoa real associada a ela, chamada de contato.
5. Caixas de Entrada de Contatos: Esta é a sessão de cada contato em uma caixa de entrada. Um contato pode ter várias
sessões e várias 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, por fim, envie a mensagem.
APIs exigem api_access_token no cabeçalho da solicitação. Você pode obter esse token acessando as Configurações do seu
Perfil → Token de Acesso.
1. Criar um contato
Ref: Documentação da API
Passe o ID da caixa de entrada do canal da API, juntamente com outros parâmetros especificados. Isso criará uma sessão
para você automaticamente. Um exemplo de resposta seria semelhante ao mostrado abaixo.
{
"e-mail": "string",
"nome": "string",
"número_de_telefone": "string",
"miniatura": "string",
"atributos_adicionais": {},
"caixas_de_entrada_de_contato": [
{
"id_de_origem": "string",
"caixa_de_entrada": {
"id": 0,
"nome": "string",
"url_do_site": "string",
"tipo_de_canal": "string",
"url_do_avatar": "string",
"cor_do_widget": "string",
"token_do_site": "string",
"ativar_atribuição_automática": verdadeiro,
"script_do_widget_web": "string",
"título_de_boas-vindas": "string",
"slogan_de_boas-vindas": "string",
"saudação_ativada": verdadeiro,
"mensagem_de_saudação": "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 Source ID
pode ser visto como o identificador da sessão. Você usará este source_id para criar uma nova conversa, conforme definido
abaixo.
2. Criar uma conversa
Ref: Documentação da API
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. Criar uma nova mensagem
Ref: Documentação da API
Existem 2 tipos de mensagens.
1. Entrada: As mensagens enviadas pelo usuário final são classificadas como mensagens de entrada.
2. Enviada: As mensagens enviadas pelo agente são classificadas como mensagens 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 recebida do Canal da 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 correr bem, você verá a conversa no painel conforme a seguir.
Você será notificado quando uma nova mensagem for criada na URL especificada durante a criação do canal da API. Você
pode ler sobre o payload da mensagem aqui.
Receber mensagens usando URL de retorno de chamada
Quando uma nova mensagem é criada no canal da API, você receberá uma solicitação POST para a URL de retorno de chamada
especificada durante a criação do canal da API. O payload ficaria assim:
Encontre a lista completa de eventos suportados pelo webhook aqui.
Tipo de evento: message_created
{
"id": 0,
"content": "Esta é uma mensagem recebida do Canal da 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 da API"
},
"conversation": {
"additional_attributes": null,
"channel": "Canal::Api",
"id": 0,
"inbox_id": 0,
"status": "aberto",
"agent_last_seen_at": 0,
"contact_last_seen_at": 0,
"timestamp": 0
},
"account": {
"id": 1,
"name": "Teste de 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 criar interfaces voltadas para o cliente no Chatwoot.
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 Chatwoot.
2. Crie interfaces conversacionais em seus aplicativos móveis.
3. Adicione o Chatwoot a outras plataformas para as quais o Chatwoot não possui um SDK oficial.
Criando objetos de clientes
Você pode criar e recuperar objetos de dados de clientes usando o inbox_identifier e o customer_identifier.
Identificador da Caixa de Entrada
Você pode obter o inbox_identifier no 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 create. Você precisará armazenar
esse identificador no seu cliente para fazer outras solicitações em nome do cliente. Isso pode ser feito em cookies,
armazenamento local, etc.
APIs Disponíveis
As APIs de Cliente Disponíveis estão documentadas aqui. Algumas das ações que você pode realizar com as APIs são:
- Criar, Visualizar e Atualizar Contatos
- Criar e Listar Conversas
- Criar, Listar e Atualizar Mensagens
Autenticação HMAC
As APIs de Cliente também suportam Autenticação HMAC. O token HMAC para o Canal pode ser obtido executando o seguinte
comando no seu console Rails.
# substitua api_inbox_id pelo ID da sua caixa de entrada
Inbox.find(api_inbox_id).channel.hmac_token
Conectando-se aos WebSockets do Chatwoot
Para receber atualizações em tempo real do painel do agente, conecte-se aos WebSockets do Chatwoot usando a seguinte
URL.
<sua URL de instalação>/cable
Autenticando sua conexão WebSocket
Após assinar 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');
connection.send(JSON.stringify({ command:"subscribe", identifier: "{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\""+ customer_pubsub_token+"\\"}" }));
Encontre a lista completa de eventos suportados por WebSockets aqui.
Implementação
Aqui está um exemplo de interface de chat criada sobre as APIs do Cliente.