Documentação da API
Enviar mensagens
Uma rota só para todo envio: POST/v1/messages, com a chave de API do seu app (escopo messages:send) e o x-customer-token do cliente dono do número. A rota responde 202 porque o envio entra em fila: a entrega na Meta acontece logo depois, com até 5 tentativas.
Mensagem de texto
channelAccountId é o id da conta conectada (response de /v1/connect/exchange) e to é o telefone com DDI, só dígitos:
curl -X POST https://api.omniplug.com.br/v1/messages \
-H "x-api-key: omp_..." \
-H "x-customer-token: ..." \
-H "content-type: application/json" \
-d '{
"channelAccountId": "b7e1...",
"to": "5511999999999",
"type": "text",
"text": { "body": "Ola, Maria! Seu pedido saiu para entrega." }
}'
O corpo pode levar previewUrl: true para gerar a prévia de links. O texto aceita até 4096 caracteres.
Template
Para a primeira conversa com um cliente, o WhatsApp exige um template aprovado pela Meta. Informe o nome e o idioma, e a API confere antes de mandar: falhas apareceriam no push, evitando o erro de template na conta.
curl -X POST https://api.omniplug.com.br/v1/messages \
-H "x-api-key: omp_..." \
-H "x-customer-token: ..." \
-H "content-type: application/json" \
-d '{
"channelAccountId": "b7e1...",
"to": "5511999999999",
"type": "template",
"template": {
"name": "lembrete",
"language": "pt_BR",
"parameters": {
"body": ["Maria", "15h"]
}
}
}'
Os parameters seguem o formato do template: uma lista quando os marcadores são posicionais ({{1}}, {{2}}...) e um objeto quando eles têm nome:
"parameters": { "body": { "nome": "Maria", "horario": "15h" } }
Para mídia no cabeçalho ou botões de link variável, envie components no formato da Meta. A cópia dos templates fica em GET /v1/templates (filtros channelAccountId, status e search); POST /v1/channel-accounts/:id/templates/sync busca de novo na WABA.
Chamada repetida e idempotência
Repetir um envio por erro de rede pode mandar a mesma mensagem duas vezes. Por isso, mande o header Idempotency-Key com um valor único por mensagem: se a chamada se repetir com a mesma chave, o envio não sai de novo.
curl -X POST https://api.omniplug.com.br/v1/messages \
-H "x-api-key: omp_..." \
-H "x-customer-token: ..." \
-H "Idempotency-Key: pedido-3321-primeira-tentativa" \
-H "content-type: application/json" \
-d '{ ... }'
Responder dentro de uma conversa
Com a guarda de dados ligada, conversas e mensagens ficam guardadas e a rota de conversa facilita a resposta: POST/v1/conversations/:id/messages manda para o contato daquela conversa, com o mesmo corpo de texto ou template, sem channelAccountId nem to.
Andamento do envio
GET/v1/messages/:id (escopo messages:read) mostra onde a mensagem está:
| Status | Situação |
|---|---|
QUEUED | Na fila da Omniplug, antes de ir para a Meta |
SENT | Aceito pela Meta |
DELIVERED | Chegou no aparelho do contato |
READ | O contato leu a mensagem |
FAILED | Não entregue: erro definitivo da Meta ou fila esgotada |
O status também chega no seu servidor como webhook message.status, com o mesmo dado atualizado a cada mudança (os detalhes estão na página de receber mensagens).
Ordem e novas tentativas
- Em falhas temporárias da Meta ou da rede, a Omniplug faz até 5 tentativas automáticas, com intervalo que cresce a cada tentativa e uma pequena variação aleatória. Se a Meta pedir um tempo com o header
Retry-After, a próxima tentativa espera esse tempo. - Mensagens enviadas em sequência para o mesmo número (
to) saem na ordem em que chegaram na API, sem travar o envio para outros contatos. - Se uma mensagem for recusada de vez pela Meta ou esgotar as tentativas, ela fica
FAILEDe libera a fila para as próximas daquele número.
Primeira mensagem a caminho? Agora é o lado de cá: cadastre o endpoint em receber mensagens para saber quando o contato responde (message.received) e quando a entrega avança (message.status).