omniplug

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-key ou Authorization: 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-token junto 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

EtapaOndeGuia
Configurar a chave de API no painelpainel, sem rotaAutenticação
Criar a sessão de conexãoPOST /v1/connect/sessionsConectar número
Trocar o code pelo token do clientePOST /v1/connect/exchangeConectar número
Enviar a primeira mensagemPOST /v1/messagesEnviar mensagens
Receber as respostas do clientePOST /v1/webhook-endpointsReceber mensagens
Ver as mensagens chegarem em tempo realGET /v1/eventsReceber 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.