Como criar uma caixa de entrada de canal API?

Para criar e configurar uma caixa de entrada de canal API no Chatwoot, siga os passos descritos abaixo. O canal API é um canal genérico: em vez de se conectar a uma rede pronta (como o WhatsApp Web ou o chat no site), ele expõe uma API para enviar e receber mensagens. Por isso, é o ponto de conexão ideal para bots e integrações externas.

Disponibilidade: o canal API está incluído a partir do plano Profissional. A Eva nativa não precisa deste canal; use-o somente para uma integração que você mesmo desenvolve ou opera.

Configure o canal API

Passo 1. Vá para Configurações → Caixas de Entrada → Adicionar caixa de entrada.

Passo 2. Clique no ícone API.

Passo 3. Informe um nome para o canal e uma URL de retorno de chamada (callback). É para essa URL que o Chatwoot enviará os eventos (por exemplo, cada nova mensagem).

Passo 4. Adicione os agentes que vão atender essa caixa de entrada e conclua.

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

Conecte bots e integrações externas

O canal API é um ponto de conexão para bots e integrações externas: por expor uma API genérica de entrada e saída, ele permite plugar qualquer sistema que envie e receba mensagens pela conta. O restante deste guia explica esse fluxo.

Envie mensagens para o canal API

Para enviar mensagens ao canal API, é importante entender os seguintes conceitos e a nomenclatura usada no Chatwoot:

1. Canal: define o tipo de origem das conversas. Por exemplo, WhatsApp Web, chat no site, API, etc.
2. Caixa de entrada: você pode criar várias fontes de conversas do mesmo tipo de canal. Por exemplo, é possível ter mais de uma caixa de entrada de API na mesma conta. Cada uma é uma 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 contato (contact inboxes): é a sessão de cada contato dentro de 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 API?

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

As chamadas exigem o api_access_token no cabeçalho da requisição. Você obtém esse token nas configurações do seu perfil → Token de acesso.

1. Crie um contato

Passe o ID da caixa de entrada do canal API junto com os demais parâmetros. Isso cria uma sessão automaticamente. Um exemplo de resposta:

{
  "email": "string",
  "name": "string",
  "phone_number": "string",
  "thumbnail": "string",
  "additional_attributes": {},
  "contact_inboxes": [
    {
      "source_id": "string",
      "inbox": {
        "id": 0,
        "name": "string",
        "channel_type": "string",
        "enable_auto_assignment": true,
        "greeting_enabled": true,
        "greeting_message": "string"
      }
    }
  ],
  "id": 0,
  "pubsub_token": "string",
  "availability_status": "string"
}

No corpo da resposta você verá contact_inboxes, e cada contact_inbox traz um source_id. O source_id funciona como identificador da sessão — você o usará para criar uma nova conversa.

2. Crie uma conversa

Use o source_id recebido na chamada anterior. Você receberá o ID da conversa, que servirá para criar mensagens.

{
  "id": 0
}

3. Crie uma nova mensagem

Existem 2 tipos de mensagem:

1. Recebida (incoming): mensagens enviadas pelo usuário final.
2. Enviada (outgoing): mensagens enviadas pelo agente.

Ao chamar a API com o conteúdo correto, você recebe uma resposta parecida com esta:

{
    "id": 0,
    "content": "This is a incoming message from API Channel",
    "inbox_id": 0,
    "conversation_id": 0,
    "message_type": 0,
    "content_type": null,
    "content_attributes": {},
    "created_at": 0,
    "private": false,
    "sender": {
        "id": 0,
        "name": "Contato",
        "type": "contact"
    }
}

Se tudo correr bem, a conversa aparecerá no painel.

Receba mensagens usando a URL de retorno de chamada

Quando uma nova mensagem é criada no canal API, o Chatwoot envia uma requisição POST para a URL de retorno de chamada informada na criação do canal. O tipo de evento é message_created e o corpo tem este formato:

{
  "id": 0,
  "content": "This is a incoming message from API Channel",
  "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": "API Channel"
  },
  "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": "API testing"
  },
  "event": "message_created"
}

Esse é o mecanismo que um bot ou integração externa usa para "ouvir" a conta: cada evento chega na URL de retorno de chamada, e a integração responde pela API.

Crie interfaces usando as APIs de cliente

As APIs de cliente disponíveis para o canal API ajudam você a construir interfaces voltadas ao cliente sobre o Chatwoot. Elas são úteis em casos como:

1. Usar uma interface de chat personalizada no lugar do widget do Chatwoot.
2. Criar interfaces de conversa em aplicativos móveis.
3. Integrar o Chatwoot a plataformas para as quais não há um SDK oficial.

Criando objetos de cliente

Você pode criar e recuperar os objetos do cliente usando o inbox_identifier da caixa e o source_id retornado ao criar o contato.

Identificador da caixa de entrada — obtenha o inbox_identifier na sua caixa de entrada de canal API, na aba Configuração das configurações da caixa de entrada.

Identificador do cliente — o source_id é retornado ao criar o contato. Guarde-o de forma segura no cliente para fazer as próximas requisições dessa identidade.

Com essas APIs você pode, entre outras coisas:

• Criar, visualizar e atualizar contatos
• Criar e listar conversas
• Criar, listar e atualizar mensagens

Autenticação HMAC

As APIs de cliente também oferecem autenticação HMAC. Copie o token HMAC na aba Configuração da caixa de entrada do canal API. Mantenha esse token apenas no seu servidor e use-o para assinar os identificadores dos clientes; não o exponha no aplicativo ou no navegador.

Conectando-se ao Chatwoot em tempo real

Para receber atualizações em tempo real, conecte-se aos WebSockets do Chatwoot usando a URL:

<url da sua instalação>/cable

Autenticando sua conexão WebSocket

Ao se inscrever usando o pubsub_token do cliente, você passa a receber os eventos direcionados ao seu objeto de cliente. O pubsub_token é retornado na chamada de criação do contato.

Exemplo:

const customerPubsubToken = '<pubsub_token retornado ao criar o contato>';
const connection = new WebSocket('wss://sua-empresa.hub.chatwoot.app.br/cable');

connection.addEventListener('open', () => {
  connection.send(JSON.stringify({
    command: 'subscribe',
    identifier: JSON.stringify({
      channel: 'RoomChannel',
      pubsub_token: customerPubsubToken,
    }),
  }));
});