Documentação da API
Visão geral
A Omniplug é uma plataforma de mensageria multiempresa, feita para reduzir o atrito e a burocracia de integrar direto com APIs oficiais, como a do WhatsApp Business da Meta. CRMs, plataformas de atendimento, helpdesks, ERPs e software houses falam um único contrato REST, em https://api.omniplug.com.br/v1, em vez de lidar com as particularidades de cada canal.
A plataforma é multicanal e admite mais de uma conexão por canal: cada cliente final do seu sistema conecta o(s) próprio(s) número(s), e os canais por trás do contrato são abstraídos. Hoje entram o WhatsApp Business (API oficial da Meta) e o Instagram, e um canal novo aparece pela mesma porta, sem reescrever a integração. O seu código fala com a Omniplug, nunca com o canal.
Por que a Omniplug existe
Falar com a API oficial diretamente é atravessar um funil de business verification, templates e webhooks por cada sistema. A Omniplug atravessa isso por você e ainda resolve o que a API oficial não entrega para um SaaS:
- Multiempresa de verdade: um token por cliente final, e a chamada só enxerga os dados dele: contatos, números e conversas.
- Multicanal desacoplado: WhatsApp e Instagram à disposição, e o próximo canal entra pela mesma porta, sem mudar a sua integração.
- Várias conexões por canal: cada cliente conecta o número dele em uma ponte de conexão segura com a sua marca, e a parte chata da Meta fica do nosso lado.
- Recebimento que você realmente usa: webhooks assinados e stream em tempo real já saindo da caixa.
Guarda de dados opcional
Você escolhe se as mensagens ficam guardadas na Omniplug:
- Sem guarda: as mensagens apenas passam a caminho do seu sistema. O que chega é entregue no webhook
message.received, completo, e fica um rastro técnico por 7 dias. Criar contato pela API responde 409, porque não existe guarda de nada. - Com guarda: as mensagens viram contato, conversa e mensagem, e todas as rotas de leitura ficam disponíveis.
Como a autenticação funciona
São duas camadas de credencial, uma autoriza o seu sistema e a outra isola o cliente da chamada:
- Chave de API do app: o seu sistema usa em todas as chamadas, no header
x-api-keyouAuthorization: Bearer omp_.... Ela pertence a um app criado no painel e tem escopos, cada chave só faz o que você liberou. - Token do cliente: cada cliente recebe um token próprio. Enviado no header
x-customer-tokenjunto da chave de API, ele limita a chamada aos dados daquele cliente. Sem misturar nada.
Um exemplo de chamada listando as conversas de um cliente:
curl https://api.omniplug.com.br/v1/conversations \
-H "x-api-key: omp_..." \
-H "x-customer-token: <token do cliente>"
O mapa da integração
| Etapa | Onde | Guia |
|---|---|---|
| Configurar a chave de API no painel | painel, sem rota | Autenticação |
| Criar a sessão de conexão | POST /v1/connect/sessions | Conectar número |
| Trocar o code pelo token do cliente | POST /v1/connect/exchange | Conectar número |
| Enviar a primeira mensagem | POST /v1/messages | Enviar mensagens |
| Receber as respostas do cliente | POST /v1/webhook-endpoints | Receber mensagens |
| Ver as mensagens chegarem em tempo real | GET /v1/events | Receber mensagens |
Chave de API em mãos? O primeiro cliente conecta o número dele em conectar número; com o token dele guardado, a primeira mensagem sai em enviar mensagens.