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.