API de mensagens: token e uso#
Você tem outro sistema que precisa mandar mensagem pelo WhatsApp — o segundo fator do seu portal, um aviso automático, uma notificação de sistema. A API de mensagens existe para isso: envio máquina a máquina, sem ninguém logado no painel.
Antes de começar#
Você precisa criar uma chave de API no Doot, e ter um canal conectado.
Como fazer#
- Vá em Configurações → API de mensagens.
- Crie uma chave. Guarde-a no momento em que ela aparece.
- Restrinja a chave por IP de origem, se o sistema que vai usá-la tem endereço fixo.
- Faça uma chamada de teste.
O envio aceita os dois métodos:
GET /api/message-api/send?to=&text=&channel_id=&api_key=&record=
POST /api/message-api/sendNo POST, o corpo leva to, text, channel_id e record.
| Parâmetro | O que é |
|---|---|
to | Destinatário |
text | O texto da mensagem |
channel_id | Por qual canal enviar |
api_key | A chave de API |
record | Se a mensagem vira atendimento no painel |
A opção record, e por que ela existe#
Por padrão, cada mensagem enviada pela API cria um atendimento no painel — o registro fica, e alguém pode ver o que foi mandado.
Passando record como false, 0 ou no, a mensagem é entregue sem criar esse registro.
Isso é o certo para dois casos: o código de segundo fator, que é um segredo de curta duração e não deveria ficar guardado numa conversa; e notificações de alto volume, que encheriam a fila sem nunca virar conversa de verdade.
E há uma decisão de segurança embutida: a chave pode ser criada com o registro permanentemente desligado. Quando a chave desliga o registro, nenhuma requisição pode religá-lo — o que impede que um sistema mal configurado, ou alguém com a chave, comece a gravar códigos de segundo fator em conversas.
A chave é uma credencial de envio#
Quem tiver a chave pode mandar mensagem em nome da sua empresa, para quem quiser, pelo seu canal. Trate-a como senha:
- Uma chave por sistema. Assim dá para revogar uma sem derrubar as outras, e dá para saber quem mandou o quê.
- Restrinja por IP sempre que o sistema de origem tiver endereço fixo.
- Não a coloque em código versionado nem em captura de tela.
- Revogue ao trocar de fornecedor ou quando alguém que a conhecia sair da empresa.
No WhatsApp oficial, as regras continuam valendo#
A API de mensagens não contorna a Meta. Fora da janela de 24 horas, texto livre não sai — só modelo aprovado. Um sistema que manda notificação por essa API para clientes que não escreveram antes vai falhar com 131047 até usar modelo. Veja A janela de 24 horas.
Se algo der errado#
Erro de autenticação. Chave errada, revogada, ou requisição vindo de um IP fora do permitido para aquela chave.
A mensagem sai mas não aparece no painel. É o esperado quando record está desligado — na requisição ou na própria chave.
A mensagem não é enviada, com erro 131047. Janela de 24 horas fechada. Use modelo aprovado.
O texto chega com caracteres estranhos. Acentuação enviada sem codificação correta na URL. Prefira o POST com corpo JSON para texto com acento.
Você não sabe qual sistema mandou uma mensagem. Se todos usam a mesma chave, não há como saber. É a razão da regra de uma chave por sistema.