![Partes do canal API: configuração com URL de retorno de chamada, envio de mensagens pela API, recebimento de eventos via callback e APIs de cliente para interfaces e tempo real.](/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBbW9RIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--fe011c727b5cf15580905b92081e6f8a4196ce53/1715708628-como-criar-uma-caixa-de-entrada-de-canal-api.png)

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:**

```js
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,
    }),
  }));
});
```