A Inbox de API permite conectar sistemas externos ao Wootdesk usando APIs, Webhooks e WebSockets.

Com ela, você pode:

• criar chats personalizados

• integrar aplicativos mobile

• conectar plataformas próprias

• construir interfaces de atendimento customizadas

• integrar canais não suportados nativamente

Criando uma Inbox de API

Passo 1. Acesse as Inboxes

Vá em:

Settings → Inboxes → Add Inbox

Passo 2. Escolha API

Clique no ícone API.

Passo 3. Configure a Inbox

Preencha:

• nome da inbox

• callback URL (webhook)

Exemplo:

• Nome: API Channel

• Callback URL:
  https://app.seusistema.com/webhooks/wootdesk

Passo 4. Adicione agentes

Selecione os agentes que terão acesso à inbox.

Pronto. Sua inbox de API foi criada.

Conceitos importantes

Channel

Define o tipo do canal:

• WhatsApp

• Email

• API

• Telegram

• etc

Inbox

Uma instância específica de um canal.

Exemplo:

• “WhatsApp Brasil”

• “App Mobile”

• “Site Principal”

Você pode ter várias inboxes do mesmo tipo.

Conversation

Uma conversa contendo mensagens.

Contact

O cliente/usuário da conversa.

Contact Inbox

A sessão do contato dentro de uma inbox.

Um contato pode possuir:

• múltiplas sessões

• múltiplas conversas

Como enviar mensagens pela API

O fluxo correto é:

1. Criar contato

2. Criar conversa

3. Enviar mensagem

Autenticação da API

As APIs exigem:

api_access_token

Você encontra em:

Profile Settings → Access Token

O token deve ser enviado no header das requisições.

1. Criar contato

Ao criar um contato:

• o sistema cria automaticamente uma sessão (contact_inbox)

• retorna um source_id

Exemplo:

{
  "id": 15,
  "name": "João",
  "contact_inboxes": [
    {
      "source_id": "abc123xyz"
    }
  ]
}

O que é source_id?

O source_id representa a sessão do usuário dentro da inbox.

Ele será utilizado para:

• criar conversas

• identificar usuários

• autenticar sessões

• consumir Client APIs

2. Criar conversa

Agora utilize o source_id para criar uma conversa.

Exemplo de resposta:

{
  "id": 77
}

O ID retornado será usado para enviar mensagens.

3. Criar mensagem

Existem dois tipos de mensagens:

Exemplo:

{
  "content": "Olá, preciso de ajuda",
  "message_type": "incoming"
}

Após o envio:

• a conversa aparecerá no painel

• os agentes poderão responder normalmente

Callback URL (Webhook)

Sempre que uma nova mensagem for criada, o Wootdesk enviará um POST para sua Callback URL.

Evento:

{
  "event": "message_created"
}

O payload inclui:

• mensagem

• contato

• inbox

• conversa

• conta

• timestamps

Client APIs

As Client APIs permitem construir interfaces próprias para clientes.

Exemplos:

• chat customizado

• app mobile

• integração white-label

• widget próprio

• canais personalizados

Inbox Identifier

Você encontra em:

API Inbox → Settings → Configuration

Customer Identifier

O customer identifier (source_id) é retornado ao criar o contato.

Você deve armazenar esse valor:

• cookies

• localStorage

• banco de dados

• sessão

APIs disponíveis

As Client APIs permitem:

• criar contatos

• atualizar contatos

• listar conversas

• criar conversas

• criar mensagens

• atualizar mensagens

Autenticação HMAC

As Client APIs suportam autenticação HMAC.

O token HMAC da inbox pode ser utilizado para:

• validar usuários

• impedir impersonação

• aumentar segurança

Exemplo:

Inbox.find(api_inbox_id).channel.hmac_token

WebSockets

Para atualizações em tempo real, conecte no WebSocket:

<installation_url>/cable

Autenticando WebSocket

Utilize o pubsub_token retornado durante a criação do cliente.

Exemplo:

const connection = new WebSocket('ws://localhost:3000/cable');

connection.send(JSON.stringify({
  command: "subscribe",
  identifier:
  "{\"channel\":\"RoomChannel\",\"pubsub_token\":\"TOKEN\"}"
}));

Webhook Verification

Ao criar uma inbox API:

• um secret é gerado automaticamente

• ele pode ser usado para validar webhooks recebidos

Isso ajuda a:

• evitar spoofing

• validar origem das requisições

• aumentar segurança da integração