Como criar uma Inbox de API no Wootdesk
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 é:
Criar contato
Criar conversa
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:
Tipo
Descrição
Incoming
Mensagem enviada pelo cliente
Outgoing
Mensagem enviada pelo agente
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