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:
| Evento | Quando sai |
|---|---|
message.received | O contato mandou uma mensagem pelo número conectado |
message.status | Um envio mudou de estado (SENT, DELIVERED, READ ou FAILED) |
conversation.updated | A conversa mudou, só com a guarda de dados ligada |
template.status | Um template mudou na Meta (aprovado, reprovado, pausado) |
ping | Você 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 mesmotypedo 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 quandotestiver 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
FAILEDe pode ser reenviada comPOST /v1/webhook-deliveries/:id/retry. - Se o seu servidor responder
429ou503com o headerRetry-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/deliveriespor 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.updatedeconversation.updatedcom a guarda ligada.message.receivedsem guarda, comchannelAccountId,frome 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.