omniplug

Documentação da API

Receber mensagens

Duas formas de receber, uma para o seu servidor e outra para a tela do atendente: webhook POST para o fluxo assíncrono e Server-Sent Events para ver as mensagens chegarem na hora.

Endpoint de webhook

Cadastre a URL que vai receber os eventos: POST/v1/webhook-endpoints (escopo webhooks:write). Você escolhe os eventos que ela recebe e, na criação, a resposta traz o segredo de assinatura, mostrado uma única vez:

curl -X POST https://api.omniplug.com.br/v1/webhook-endpoints \
  -H "x-api-key: omp_..." \
  -H "content-type: application/json" \
  -d '{
    "url": "https://seusistema.com/webhooks/omniplug",
    "description": "Webhook de producao da Loja Aurora",
    "events": ["message.received", "message.status"]
  }'

Os eventos disponíveis:

EventoQuando sai
message.receivedO contato mandou uma mensagem pelo número conectado
message.statusUm envio mudou de estado (SENT, DELIVERED, READ ou FAILED)
conversation.updatedA conversa mudou, só com a guarda de dados ligada
template.statusUm template mudou na Meta (aprovado, reprovado, pausado)
pingVocê pediu para testar a entrega com POST /v1/webhook-endpoints/:id/ping

Formato da entrega

Cada entrega é um POST com o corpo:

{
  "id": "...",
  "type": "message.received",
  "companyId": "...",
  "appId": "...",
  "customer": { "id": "c4a2...", "externalId": "cliente-123" },
  "createdAt": "2026-11-03T12:00:00.000Z",
  "data": { ... }
}

O customer é o cliente dono do canal do evento, com o externalId que o seu sistema escolheu: o mesmo corpo já diz de quem é a mensagem (e vem null quando o canal não pertence a um cliente).

Nos headers, além do Content-Type:

  • X-Omniplug-Event: o mesmo type do corpo.
  • X-Omniplug-Event-Id: único na entrega e igual em todas as tentativas, para o seu sistema não processar duas vezes.
  • X-Omniplug-Delivery: número da tentativa.
  • X-Omniplug-Signature: t=<unix>,v1=<hex>: HMAC-SHA256 de <t>.<corpo> com o segredo do endpoint. Recuse quando t estiver a mais de 5 minutos do relógio do seu servidor.

Entrega e novas tentativas

  • Responda com um código 2xx em até 10 segundos; o corpo é ignorado.
  • Fora disso, seguem 8 tentativas ao longo de umas 2 horas e, ao fim, a entrega fica FAILED e pode ser reenviada com POST /v1/webhook-deliveries/:id/retry.
  • Se o seu servidor responder 429 ou 503 com o header Retry-After, a próxima tentativa espera o tempo pedido, até o limite de 15 minutos por tentativa.
  • O histórico de entregas fica em GET /v1/webhook-endpoints/:id/deliveries por 30 dias, com o corpo completo. Sem guarda, o conteúdo sai logo depois que a entrega dá certo e o registro fica 7 dias.

Tempo real na tela do atendente

GET/v1/events (escopo conversations:read) abre uma conexão SSE com os eventos do app, já com o dado completo:

  • message.created, message.updated e conversation.updated com a guarda ligada.
  • message.received sem guarda, com channelAccountId, from e o conteúdo.

No navegador:

new EventSource("https://api.omniplug.com.br/v1/events", { withCredentials: true })

Não há replay: quando a conexão cai, recarregue a lista de conversas e a que estiver aberta.

Webhook respondendo 200? Rode o ping, confira a assinatura de cada POST com o segredo de criação e use o histórico de entregas quando algo parar de chegar. É o message.status da página de envio que confirmará a mensagem no aparelho do contato.