API externa

Envia eventos dos teus sistemas para a caixa

Um pedido HTTP deixa uma mensagem de texto no seu próprio fio, ao lado dos chats de WhatsApp. Não é enviada no WhatsApp e não se mistura na conversa de um cliente.

Começar teste grátis Ver preços

Depois de iniciares sessão, cria um token em Definições. O segredo é mostrado uma só vez.

O que a API faz

Entrada, não saída

Envia uma mensagem de texto para uma sessão de WhatsApp que já ligaste. O Chato guarda-a e mostra-a ao vivo no painel. Não envia uma mensagem de WhatsApp e não há canal de resposta para o teu sistema.

Um fio por origem

O sourceId shopify cai sempre no mesmo chat, ext:shopify@external. Uma segunda origem, como website, é outro fio nessa mesma sessão.

Fora dos chats de clientes

O fio fica marcado como externo e o compositor é só de leitura. Alertas de encomendas e formulários ficam ao lado da caixa, não dentro do histórico de um cliente.

Onde as equipas a usam

Tudo o que deve ficar junto do WhatsApp, sem se tornar uma mensagem de WhatsApp.

Encomendas e pagamentos

Encomenda nova, paga, reembolsada. A sessão dessa loja mostra um fio da Shopify em vez de um chat de cliente falso.

Formulários do site

Um formulário de contacto ou de reserva publica o envio. A equipa lê-o no mesmo painel do WhatsApp.

CRM e suporte

Mudanças de negócio, escalamentos de tickets ou notas de atribuição. Dá a cada ferramenta o seu source id para os fios não se misturarem.

Ferramentas internas

Inventário, monitorização ou um script de operações. Um token da conta pode publicar em qualquer sessão dessa conta.

Como enviar a primeira mensagem

01
Cria um token
Abre Definições e depois API externa. Dá-lhe o nome da integração, por exemplo Shopify. Copia o segredo de imediato. O Chato guarda só um hash e o token completo não volta a aparecer. Revoga-o aí quando rodas ou paras uma integração.
02
Copia o id da sessão
No painel, abre o menu do número de WhatsApp que deve receber o fio e escolhe Copiar ID da sessão. Essa sessão tem de pertencer à mesma conta do token.
03
Envia a mensagem
Manda JSON para POST /api/external/messages com Authorization: Bearer e o teu token. sourceId escolhe o fio. externalMessageId permite repetir sem criar um duplicado.
04
Abre o fio
A origem aparece na lista de chats dessa sessão com o nome da origem. Enviar outra vez o mesmo externalMessageId devolve a mensagem original e não acrescenta uma segunda bolha.

Endpoints

As chamadas de mensagens usam o token da API. Criar, listar e revogar tokens usa a sessão iniciada no Chato, tal como as Definições.

Método	Caminho	Auth	O que faz
POST	/api/external/messages	Token da API	Guarda uma mensagem de texto numa sessão. 201 se for nova, 200 se esse externalMessageId já existia.
GET	/api/external/me	Token da API	Confirma que o token é válido. Devolve authenticated e o id da conta. Não lista sessões.
GET	/api/external/tokens	Sessão iniciada	Lista os tokens ativos: nome, prefixo, data de criação e última utilização. Não inclui segredos.
POST	/api/external/tokens	Sessão iniciada	Cria um token. O corpo é { "name": "Shopify" }. O segredo vem na resposta uma só vez.
DELETE	/api/external/tokens?id=TOKEN_ID	Sessão iniciada	Revoga um token. Chamadas seguintes com esse segredo devolvem 401.

URL base: https://chato.pro. Se não entras em chato.pro, usa o host com que inicias sessão.

Campos da mensagem

Corpo JSON de POST /api/external/messages.

Campo	Obrigatório	O que faz
sessionId	Obrigatório	A sessão de WhatsApp que deve mostrar o fio. Copia-a no painel. 404 se não estiver nesta conta.
sourceId	Obrigatório	Chave do fio. 2 a 64 caracteres: letras, números, hífenes e underscores. Os espaços passam a hífenes e o valor fica em minúsculas. O id do chat é ext:<sourceId>@external.
message	Obrigatório	O texto mostrado no fio. Não pode estar vazio e tem no máximo 4096 caracteres.
sourceName	Opcional	Nome visível, por exemplo Encomendas Shopify. Se for omitido, o source id fica em maiúsculas de título.
externalMessageId	Opcional	O teu id para este evento. Enviá-lo outra vez para a mesma sessão e origem devolve a mensagem original e não emite outra atualização ao vivo.
metadata	Opcional	Objeto JSON extra guardado com a mensagem. Não é mostrado como texto do chat.

Exemplo de pedido

Substitui YOUR_TOKEN e o id da sessão. Uma mensagem nova responde com created: true e o chat ext:shopify@external.

Exemplo de resposta

created é false, com HTTP 200, quando externalMessageId já estava guardado.

curl -X POST https://chato.pro/api/external/messages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "your-session-id",
    "sourceId": "shopify",
    "sourceName": "Shopify Orders",
    "message": "New order #1234",
    "externalMessageId": "order-1234"
  }'

{
  "success": true,
  "created": true,
  "messageId": "ext_shopify_order-1234",
  "chatId": "ext:shopify@external",
  "sourceId": "shopify",
  "timestamp": 1710000000
}

Autenticação

Envia o token em cada chamada de mensagem. Prefere o cabeçalho Authorization para o segredo não ficar numa URL ou no registo de um proxy.

Authorization: Bearer <token>
X-Api-Key: <token>
?key=<token>

Um token é uma credencial da conta. Qualquer token ativo pode publicar em qualquer sessão dessa conta. Revogá-lo nas Definições para-o de imediato. Cada chamada correta atualiza a última utilização. O segredo tem a forma chato_ seguido de 48 caracteres hexadecimais. As Definições depois mostram só o início do token.

Depois de uma chamada correta

A mensagem fica guardada com origem external. O WhatsApp não é contactado.
Um painel aberto dessa sessão recebe a mensagem nova ao vivo.
O id do fio é ext:<sourceId>@external.
Repetir externalMessageId devolve HTTP 200 e created: false.
O não lido é local do Chato. Abrir o fio não envia um recibo de leitura do WhatsApp.
Apagar uma mensagem externa remove-a só do Chato.

O que não faz

Não envia mensagens, ficheiros nem modelos de WhatsApp.
Não podes responder a partir do fio para o sistema externo.
Não é a API na nuvem da Meta nem a API oficial do WhatsApp Business.
Só aceita texto. Este endpoint não envia ficheiros.
Um token não pode escrever em sessões de outra conta.
O Chato não chama o teu servidor quando alguém lê o fio.

Respostas

201 — Mensagem guardada.
200 — Esse externalMessageId já existia. A mensagem existente é devolvida.
400 — Falta sessionId, sourceId inválido, ou mensagem vazia ou demasiado longa.
401 — Token em falta, desconhecido ou revogado.
404 — sessionId não pertence a esta conta.
405 — Método HTTP errado.

Gera um token, aponta um sistema a uma sessão e deixa esses eventos no seu próprio fio.

Começar teste grátis