Principal Caixas de Entrada Como criar uma caixa de entrada de canal API?

Como criar uma caixa de entrada de canal API?

Última atualização em Aug 27, 2024

Para criar e configurar uma caixa de entrada de canal API nas instalações do Chatwoot, siga o passo descrito abaixo.

Configure o canal API

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

Passo 2. Clique no ícone “API”.

Etapa 3. Forneça um nome para o canal e uma URL de retorno de chamada. Aqui está um exemplo:

Passo 4 . "Adicionar agentes" à sua caixa de entrada da API.

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

Envie mensagens para o canal API

Para enviar mensagens para o canal API, certifique-se de compreender os seguintes modelos e nomenclatura usados ​​no Chatwoot.

  1. Canal : Canal define o tipo de origem das conversas. Por exemplo, Facebook, Twitter, API, etc.

  2. Caixa de entrada : você pode criar múltiplas fontes de conversas do mesmo tipo de canal. Por exemplo, você pode ter mais de uma página do Facebook conectada a uma conta 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 da vida real associada a ela, chamada de contato.

  5. Caixas de entrada de contato : esta é a sessão para cada contato em uma caixa de entrada. Um contato pode ter diversas sessões e diversas 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 APIs exigem  api_access_token no cabeçalho da solicitação. Você pode obter esse token visitando as configurações do seu perfil → Token de acesso.

1. Crie um contato

Ref .: Documentação da API

Passe o ID da caixa de entrada do canal API junto com outros parâmetros especificados. Isso criaria uma sessão para você automaticamente. Um exemplo de resposta seria semelhante ao mostrado 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 na carga útil, você poderá ver o  contact_inboxes e cada um  contact_inbox terá um arquivo  source_id. O ID de origem pode ser visto como o identificador da sessão. Você usará isso **source_id**para criar uma nova conversa conforme definido abaixo.

2. Crie 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. Crie uma nova mensagem

Ref: documentação da API

Existem 2 tipos de mensagens.

  1. Recebida : as mensagens enviadas pelo usuário final são classificadas como mensagens recebidas.

  2. Saída : As mensagens enviadas pelo agente são classificadas como mensagens de saída.

Se você chamar a API com o conteúdo correto, receberá uma carga semelhante a 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": "Pranav",
        "type": "contact"
    }
}

Se tudo der certo, você verá a conversa no painel da seguinte forma.

Você será notificado quando uma nova mensagem for criada no URL especificado durante a criação do canal API. Você pode ler sobre a carga útil da mensagem  aqui .

Receba mensagens usando URL de retorno de chamada

Quando uma nova mensagem é criada no canal API, você receberá uma solicitação POST para o URL de retorno de chamada especificado durante a criação do canal API. A carga ficaria assim.

Encontre a lista completa de eventos suportados pelo webhook  aqui .

Tipo de evento : message_created

{
  "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"
}

Crie interfaces usando APIs de cliente

As APIs de cliente disponíveis para o canal API ajudarão você a construir interfaces voltadas para o cliente para Chatwoot.

Essas APIs são úteis para casos como os listados abaixo.

  1. Use uma interface de bate-papo personalizada em vez do widget de bate-papo Chatwoot.

  2. Crie interfaces de conversação em seus aplicativos móveis.

  3. Adicione Chatwoot a outras plataformas para as quais Chatwoot não possui um SDK oficial.

Criando objetos de cliente

Você pode criar e recuperar objetos de dados do cliente usando os  inbox_identifier métodos e  customer_identifier.

Identificador da caixa de entrada

Você pode obter  inbox_identifier em seu canal 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 esse identificador no lado do cliente para fazer solicitações adicionais 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 coisas que você pode fazer com as APIs são:

  • Criar, visualizar e atualizar contato

  • Criar e listar conversas

  • Criar, listar e atualizar mensagens

Autenticação HMAC

As APIs do cliente também oferecem suporte  à autenticação HMAC . O token HMAC para o canal pode ser obtido executando o seguinte em seu console Rails.

# replace api_inbox_id with your inbox id
Inbox.find(api_inbox_id).channel.hmac_token

Conectando-se ao Chatwoot

Para obter atualizações em tempo real do painel do agente, conecte-se ao Chatwoot WebSockets usando o seguinte URL.

<your installation url>/cable

Autenticando sua conexão WebSocket

Depois de se inscrever usando o cliente pubsub_token, você receberá eventos direcionados ao seu objeto 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 bate-papo construída sobre as APIs do cliente.