Como cada canal é conectado ao workspace, com o cadastro incorporado do WhatsApp, autorização OAuth do Instagram, Facebook, TikTok, Mercado Livre e Google, WhatsApp não oficial por QR code ou código, bots do Telegram e verificação de número.
Cada canal se conecta de um jeito, porque cada provedor exige uma autorização diferente. Esta página mostra o caminho que a API segue em cada um. Todas as rotas usam o token de login e o workspace do cabeçalho X-Workspace-ID.
| Canal | Como conecta |
|---|---|
| WhatsApp oficial | Cadastro incorporado da Meta, numa página servida pela API. |
| Instagram, Facebook, TikTok, Mercado Livre, Google | Autorização OAuth no site do provedor. |
| WhatsApp não oficial | QR code ou código de pareamento lido no celular. |
| Telegram | Token do bot criado no BotFather. |
As rotas estão nos grupos WhatsApp: cadastro, WhatsApp: números, WhatsApp não oficial: instâncias, Instagram, Facebook, TikTok, Mercado Livre, Google e Telegram da Referência da API.
WhatsApp oficial
O número do WhatsApp Business entra pelo cadastro incorporado (Embedded Signup) da Meta: a pessoa entra com a conta do Facebook, escolhe ou cria a conta do WhatsApp Business e o número, e a Meta devolve um código que a API troca pelo acesso à conta.
GET /whatsapp/onboarding-config diz qual provedor recebe o número: meta (a conexão é direta com a Meta) ou dialog360 (o número é repassado ao 360dialog). requiresSlot diz se a conexão consome uma vaga de número do workspace.
A página de cadastro
GET /oauth/meta/embedded?workspace_id=WORKSPACE_ID&redirect_url=URL_DE_RETORNO devolve a página que roda o cadastro da Meta. Abra-a num pop-up, no navegador em que a pessoa entrou no aplicativo:
- A pessoa clica no botão da página e conclui o cadastro na janela da Meta.
- A página envia o resultado para
POST /oauth/meta/embedded. Esse envio não leva o token no cabeçalho nem na URL: ele usa o cookie de sessão que o login grava no navegador. - Concluído o cadastro, a página avisa a janela que a abriu com
postMessage, só para a origem deredirect_url, com{ source: "wa-embedded", status: "success", phone_id, waba_id }, e se fecha. Aberta fora de um pop-up, ela redireciona pararedirect_urlcom os mesmos dados na URL.
workspace_id é obrigatório e precisa ser o workspace da chamada; outro workspace responde 403 forbidden. redirect_url só é usado quando a origem é uma das origens confiáveis do painel; senão, é ignorado.
O envio do resultado
POST /oauth/meta/embedded?workspace_id=WORKSPACE_ID recebe o que o cadastro da Meta devolveu:
| Campo | O que é |
|---|---|
code | O código devolvido pelo login da Meta. A API o troca pelo acesso usando o aplicativo da Meta da plataforma, então o código precisa vir do cadastro rodado com esse aplicativo, como faz a página acima. |
access_token | Alternativa a code: um token de acesso já trocado. |
phone_number_id, waba_id, business_id | Os ids do número, da conta e da empresa, que a Meta envia ao fim do cadastro. Sem eles, a API procura o número na conta autorizada. |
Com o provedor meta, a resposta traz status: "success", os ids e, em db_save, o número salvo (phone_id, is_new e status). Com o provedor dialog360, traz provisioning: true, phone_id, phone_number_id e waba_id; se o repasse falhar, o número fica visível como falho e pode ser repetido com POST /onboard/360dialog/retry?workspace_id=WORKSPACE_ID&phone_id=PHONE_ID.
| Recusa | Quando |
|---|---|
400 | Sem code nem access_token, ou sem workspace_id. |
403 phone_limit_reached | O workspace não tem mais vagas de número. |
409 phone_held_by_another_workspace | O número já está conectado a outro workspace. |
422 no_phone_number | A conta autorizada não tem nenhum número. |
500 onboarding_failed | O número não pôde ser salvo; nada foi gravado. |
502 | A Meta recusou a troca do código, ou o repasse ao 360dialog falhou. |
503 onboarding_unavailable | A conexão de números está indisponível. |
Verificar o número
Um número que ainda precisa ser verificado recebe um código da Meta:
POST /whatsapp/business-phones/{id}/request-verificationcommethod(SMS, o padrão, ouVOICE) elanguage(por exemplopt_BR). A Meta envia o código para o número.POST /whatsapp/business-phones/{id}/verify-codecom ocoderecebido.codevazio responde400.
As duas rotas exigem a permissão business_phones:update e somam um limite de 5 chamadas a cada 24 horas; acima dele, 429.
{ "method": "SMS", "language": "pt_BR" }Instagram, Facebook, TikTok, Mercado Livre e Google
Esses canais usam a autorização OAuth do provedor. O fluxo é o mesmo em todos:
- Chame a rota de início. Ela devolve, em
authorizeUrl, o endereço de autorização do provedor, com umstateassinado que liga o pedido ao workspace e a quem pediu. Ostatevale 15 minutos e uma única vez. - Abra
authorizeUrlpara a pessoa aprovar o acesso, num pop-up (compopup=1na rota de início) ou na própria janela. - O provedor volta para o retorno OAuth da API, que conecta a conta e devolve o resultado ao painel.
| Parâmetro da rota de início | Efeito |
|---|---|
returnPath | O caminho do painel para onde voltar no fim, começando com /. Um caminho inválido vira o padrão do canal. |
popup=1 | O retorno responde com uma página que envia o resultado por postMessage à janela que abriu o pop-up, só para a origem do painel, e se fecha. |
redirect=1 | A rota de início responde 302 direto para o provedor, em vez do JSON. |
| Canal | Rota de início | Permissão | source no pop-up | Parâmetro no retorno sem pop-up |
|---|---|---|---|---|
GET /oauth/instagram/start | instagram_accounts:create | ig-business-login | instagram | |
GET /oauth/facebook/start | facebook_pages:create | fb-business-login | facebook | |
| TikTok | GET /oauth/tiktok/start | tiktok_accounts:create | tiktok-login | tiktok |
| Mercado Livre | GET /oauth/mercadolivre/start | mercadolivre_accounts:create | mercadolivre-login | mercadolivre |
| Google Agenda | GET /oauth/google/calendar/start | calendar:create | google-login | google |
| Google Planilhas | GET /oauth/google/sheets/start | google_sheets:create | google-login | google |
O resultado traz status: connected ou error em todos; reconnected no Instagram, no TikTok e no Mercado Livre quando a conta já existia; cancelled no Facebook e no TikTok quando a pessoa recusou; e partial no Facebook quando só parte das páginas conectou. Num erro, reason traz o motivo. Um state vencido dá expired_state; um state inválido ou já usado, invalid_state.
O resultado sempre volta ao painel, não ao seu sistema. Depois da autorização, confira as contas conectadas pela API: GET /instagram/accounts, GET /facebook/pages, GET /tiktok/accounts, GET /mercadolivre/accounts, GET /google/accounts/calendar e GET /google/accounts/sheets.
curl "https://api.vozkoia.com/oauth/instagram/start?popup=1&returnPath=/dashboard/instagram-accounts" \
-H "Authorization: Bearer SEU_TOKEN" \
-H "X-Workspace-ID: SEU_WORKSPACE"{ "authorizeUrl": "URL_DE_AUTORIZACAO_DO_INSTAGRAM" }Particularidades:
- Facebook: conecta as páginas concedidas e assina os webhooks de cada uma. No pop-up,
pagestraz o resultado de cada página. - Mercado Livre: a autorização usa PKCE, e só o administrador da conta do Mercado Livre consegue autorizar.
- Google: a mesma conta Google pode servir ao Google Agenda e ao Google Planilhas. O Google Planilhas pede acesso só aos arquivos criados pela plataforma.
WhatsApp não oficial
Um número do WhatsApp não oficial é ligado ao aplicativo do WhatsApp no celular, como um aparelho conectado.
- Confira a cota com
GET /unofficial-whatsapp/instances/allowance:canConnectdiz se um novo número pode ser criado agora. - Crie o número com
POST /unofficial-whatsapp/instances, comdisplayName,departmentIdeimportHistory(importa o histórico de conversas ao conectar). Sem cota,402; sem capacidade nos servidores,503. - Inicie a vinculação com
POST /unofficial-whatsapp/instances/{id}/connect:
mode | Corpo | Resposta |
|---|---|---|
qr (padrão) | { "mode": "qr" } | qrCode, para ler no celular em Aparelhos conectados. |
pairing | { "mode": "pairing", "phone": "5511987654321" } | pairCode, o código que se digita no celular. phone leva DDI e DDD. |
systemName define o nome do aparelho mostrado no celular. expiresAt diz até quando o código vale.
- Consulte
GET /unofficial-whatsapp/instances/{id}/link-statusem intervalos curtos. A resposta traz o número eminstancee, enquanto ainda aguarda a leitura, o QR code ou o código vigente. A vinculação terminou quandoinstance.statusviraCONNECTED.
status | Significado |
|---|---|
PROVISIONING, AWAITING_SCAN | Criado, aguardando a vinculação. |
CONNECTED | Conectado. |
HIBERNATED | Sessão em espera. |
DISCONNECTED | A sessão deixou de valer; conecte de novo. |
BANNED | Número banido pelo WhatsApp. connect responde 409. |
PROVISION_FAILED | A criação falhou. connect responde 409. |
Falhas do servidor do WhatsApp não oficial voltam como 409 (número restrito ou sessão que precisa ser reconectada), 503 (sem capacidade) ou 502. POST /unofficial-whatsapp/instances/{id}/disconnect encerra a sessão e mantém o número; POST /unofficial-whatsapp/instances/{id}/reset reinicia a sessão sem desvincular o aparelho.
Telegram
- Crie o bot no BotFather do Telegram e copie o token.
POST /telegram/accountscombotTokene, se quiser,departmentId. O token é conferido no Telegram, o webhook do bot é registrado para a API e a conta volta com statusACTIVE(201).
{ "botToken": "123456789:AA...", "departmentId": "5b0c1d2e-3f4a-4b5c-8d6e-7f8091a2b3c4" }| Resposta | Quando |
|---|---|
400 | Token ausente ou recusado pelo Telegram. |
409 | O bot já está conectado a outro workspace. |
500 | O webhook não pôde ser registrado. A conta fica salva com status WEBHOOK_FAILING; tente de novo com POST /telegram/accounts/{id}/webhook. |
Conectar de novo o mesmo bot no mesmo workspace atualiza o token e o departamento e reativa a conta. POST /telegram/accounts/{id}/deep-links cria um link https://t.me/<bot>?start=<token> que abre a conversa com o bot já associada a um lead, campanha, agente ou departamento.