Para criar e configurar uma caixa de entrada de canal de API em instalações do Chatwoot, siga o passo descrito abaixo. ## Configurar o canal de API **Passo 1**. Vá em Configurações → Caixas de entrada → “Adicionar Caixa de entrada”. ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMGFsVHc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--32734baff90933097fa9e1d5d2cb9c0a824de9ed/adding%20an%20inbox%20in%20chatwoot.png) **Passo 2.** Clique no ícone "API". ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMWlsVHc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--cf2f9535e7e9e5feb146122da5bd42ce5e5e151b/api%20channel%20inbox%20in%20chatwoot.png) **Passo 3.** Forneça um nome para o canal e uma URL de callback. Veja um exemplo: ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMXFsVHc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--4d27a3aa27c07d14a098f148fdf5fb15d6ff06b6/api%20channel%20settings.png) **Passo 4**. "Adicionar agentes" à sua caixa de entrada API. ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMDJsVHc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--d7190cf613e5630ab61790dbaf922bf1005e7c6a/adding%20agents%20to%20a%20chatwoot%20inbox.png) A configuração da caixa de entrada está concluída. ## Envie mensagens para o canal de API Para enviar mensagens para o canal de API, certifique-se de entender os seguintes modelos e a [nomenclatura](https://app.chatwoot.com/hc/chatwoot-user-guide-cloud-version/en/chatwoot-101/454) usada no Chatwoot. 1. **Canal**: Canal define o tipo de origem das conversas. Ex: Facebook, Twitter, API, etc. 2. **Caixa de entrada**: Você pode criar várias origens 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 é uma coleção de mensagens. 4. **Contato**: Cada conversa tem uma pessoa real associada a ela, chamada de contato. 5. **Contato nas caixas de entrada**: Esta é a sessão de cada contato em uma caixa de entrada. Um contato pode ter várias 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, por fim, envie a mensagem. As APIs exigem o `api_access_token` no cabeçalho da requisição. Você pode obter este token visitando suas configurações de Perfil → Token de Acesso. **1. Criar um contato** **Ref**: [Documentação da API](https://www.chatwoot.com/developers/api/#operation/contactCreate) Informe o ID da caixa de entrada do canal API junto com outros parâmetros especificados. Isso criará uma sessão para você automaticamente. Uma resposta de exemplo seria semelhante à apresentada 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, será possível visualizar `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](https://www.chatwoot.com/developers/api/#operation/newConversation) 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](https://www.chatwoot.com/developers/api/#operation/create-a-new-message-in-a-conversation) Existem 2 tipos de mensagens. 1. **Recebida**: Mensagens enviadas pelo usuário final são classificadas como mensagens recebidas. 2. **Enviada**: Mensagens enviadas pelo agente são classificadas como mensagens enviadas. 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 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 ocorrer com sucesso, você verá a conversa no painel da seguinte forma. ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMktsVHc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--110186260cba7057ce9b0cbb48ec5b45c12e8875/api%20inbox.png) Você será notificado quando uma nova mensagem for criada na URL informada durante a criação do canal de API. Você pode ler sobre o payload da mensagem [aqui](https://www.chatwoot.com/docs/product/channels/api/receive-messages). ## Receber 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 informada durante a criação do canal de API. O payload será semelhante a este. Encontre a lista completa de eventos suportados pelo webhook [aqui](https://www.chatwoot.com/docs/product/others/webhook-events). **Tipo de evento**: `message_created` ``` { "id": 0, "content": "Esta é uma mensagem recebida 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": "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" } ``` ## Criar interfaces usando Client APIs As APIs de cliente disponíveis para o canal de API vão ajudar você a construir interfaces voltadas para o cliente do Chatwoot. Essas APIs são úteis para situações como as listadas abaixo. 1. Usar uma interface de chat personalizada ao invés do widget padrão do Chatwoot. 2. Construir interfaces conversacionais em seus aplicativos móveis. 3. Adicionar o Chatwoot a outras plataformas para as quais o Chatwoot não possui um SDK oficial. ### Criando objetos de cliente 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` em seu canal de API -> Configurações -> Configuração. **Identificador do Cliente** O `customer_identifier` ou o `source_id` pode ser obtido ao criar o cliente usando a [API de criação](https://www.chatwoot.com/developers/api#operation/create-a-contact). Você precisará armazenar este identificador no lado do cliente para fazer futuras solicitações em nome do cliente. Isso pode ser feito em cookies, local storage, etc. **APIs Disponíveis** As Client APIs disponíveis estão documentadas [aqui](https://www.chatwoot.com/developers/api#tag/Contacts-API). Algumas das ações que você pode executar com as APIs: * Criar, Visualizar e Atualizar Contato * Criar e Listar Conversas * Criar, Listar e Atualizar Mensagens ### Autenticação HMAC As Client APIs também suportam [Autenticação HMAC](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/identity-validation). O token HMAC para o Canal pode ser obtido executando o seguinte no seu console rails. ``` # substitua api_inbox_id pelo id da sua caixa de entrada Inbox.find(api_inbox_id).channel.hmac_token ``` ### Conectando aos WebSockets do Chatwoot Para obter atualizações em tempo real do painel do agente, conecte-se aos WebSockets do Chatwoot utilizando a seguinte URL. ``` /cable ``` ### Autenticando sua conexão WebSocket Após assinar utilizando 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](https://www.chatwoot.com/docs/product/others/websocket-events). ### Verificação de Webhook Assim que você cria um canal de API, é gerado automaticamente um segredo que você pode usar para verificar o payload que sua aplicação recebe. Saiba mais sobre verificação de webhook [aqui](https://www.chatwoot.com/hc/user-guide/articles/1677693021-how-to-use-webhooks#verifying-webhooks). ### Implementação [Aqui está um exemplo](https://github.com/chatwoot/client-api-demo) de interface de chat construída sobre as Client APIs.