omniplug

Documentação da API

Conectar o número do seu cliente

O fluxo é o mesmo de um checkout: o seu sistema abre a sessão, manda o cliente para uma página que já tem a sua marca, e ele volta com um código que vira o token dele. Ninguém cria conta na Omniplug.

1. Crie a sessão de conexão

POST/v1/connect/sessions, com a chave de API do seu app (escopos customers:write e channel_accounts:write). Se o cliente ainda não existe, ele nasce aqui:

curl -X POST https://api.omniplug.com.br/v1/connect/sessions \
  -H "x-api-key: omp_..." \
  -H "content-type: application/json" \
  -d '{
    "customer": {
      "externalId": "cliente-123",
      "name": "Loja Aurora"
    },
    "redirectUrl": "https://seusistema.com/configuracoes/whatsapp",
    "state": "sessao-do-seu-sistema"
  }'

A resposta traz a URL da página de conexão, válida por 30 minutos:

{
  "id": "39b1...",
  "url": "https://app.omniplug.com.br/connect/ocs_...",
  "expiresAt": "2026-11-03T13:30:00.000Z",
  "customer": { "id": "c4a2...", "externalId": "cliente-123", "name": "Loja Aurora" }
}
  • externalId: como o seu sistema identifica esse cliente. É a sua chave, usada para achar o cliente depois.
  • redirectUrl: precisa estar entre as URLs de retorno cadastradas no app, no painel. Se omitir, a página só avisa que a conexão terminou.
  • state: opcional e opaco. Devolvemos do jeito que você mandou.

2. Mande o cliente para a página

Redirecione o navegador do cliente para a url da sessão. A página mostra o seu logo, a sua cor e os links de privacidade e termos que você cadastrou no app. Lá, o cliente entra com a conta do Facebook da empresa e escolhe o número, ou preenche o formulário manual se você liberou esse método no app.

Você não cria tela de conexão nem lida com a Meta. Mas se quiser montar a sua própria página, a API também responde os campos do formulário manual em /v1/connect/pages/:token.

3. Troque o code pelo token do cliente

Quando ele termina, volta para a redirectUrl com ?code=... e ?state=.... O código vale por 10 minutos e só funciona uma vez. Troque no seu servidor, nunca no navegador do cliente:

curl -X POST https://api.omniplug.com.br/v1/connect/exchange \
  -H "x-api-key: omp_..." \
  -H "content-type: application/json" \
  -d '{ "code": "..." }'

A resposta traz o token do cliente e os dados da conta de canal que ele conectou:

{
  "customer": { "id": "c4a2...", "externalId": "cliente-123", "name": "Loja Aurora" },
  "token": "...",
  "channelAccount": { "id": "b7e1...", "status": "CONNECTED" }
}

Guarde o token; ele vai no header x-customer-token de toda chamada que falar daquele cliente. Cada troca gera um token novo e o anterior para de funcionar na hora, então repita o fluxo se precisar renovar.

4. Dia a dia do token

Se um token vazar ou você quiser trocá-lo por precaução, POST /v1/customers/:id/token gera outro e derruba o antigo; DELETE /v1/customers/:id/token remove o acesso do cliente pela API do seu app.

Quando o número fica pronto

A conta nasce e é conferida na Meta na hora: se o provedor recusar, a conexão falha e o cliente pode tentar de novo na mesma página. Chegando a CONNECTED, o número já entra no envio e começa a receber. Para reconferir as credenciais quando quiser: POST /v1/channel-accounts/:id/verify.

Token guardado com segurança? Mande a primeira mensagem com a API de envio e cadastre um webhook em receber mensagens, para o seu sistema saber quando o cliente do seu cliente responder.