omniplug

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á:

StatusSituação
QUEUEDNa fila da Omniplug, antes de ir para a Meta
SENTAceito pela Meta
DELIVEREDChegou no aparelho do contato
READO contato leu a mensagem
FAILEDNã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 FAILED e 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).