Para criar e configurar uma caixa de entrada de canal de API em instalações do RockZap®, 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.rockzap.com.br/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBM2FrRFE9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--80d8a86f49edfcf4a71c5a4c2a41598c5925dee3/adding-20an-20inbox-20in-20chatwoot.png) **Passo 2.** Clique no ícone "API". ![](https://app.rockzap.com.br/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBM21rRFE9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--0a86850ada984452b5b65868d274488cf4fec7e0/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.rockzap.com.br/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBM3FrRFE9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--01f4d3d584d26a0fd50f90d5c187321742ca8880/api-20channel-20settings.png) **Passo 4**. "Adicionar agentes" à sua caixa de entrada API. ![](https://app.rockzap.com.br/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBM2lrRFE9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--3e1f7e61f3fe000c3f20e67a4eec133c86932337/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** usada no RockZap®. 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 RockZap®. Cada página é chamada de caixa de entrada no RockZap®. 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** 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** 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** 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.rockzap.com.br/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBM2VrRFE9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--d7ed055510ebd6fcc79acb9649b8a47dd23b2393/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. ## **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. **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 RockZap®. 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 RockZap®. 2. Construir interfaces conversacionais em seus aplicativos móveis. 3. Adicionar o RockZap® a outras plataformas para as quais o RockZap® 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**. 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. 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**. 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 RockZap®** Para obter atualizações em tempo real do painel do agente, conecte-se aos WebSockets do RockZap® 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. ### **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.