Conectar canais

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.

CanalComo conecta
WhatsApp oficialCadastro incorporado da Meta, numa página servida pela API.
Instagram, Facebook, TikTok, Mercado Livre, GoogleAutorização OAuth no site do provedor.
WhatsApp não oficialQR code ou código de pareamento lido no celular.
TelegramToken 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:

  1. A pessoa clica no botão da página e conclui o cadastro na janela da Meta.
  2. 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.
  3. Concluído o cadastro, a página avisa a janela que a abriu com postMessage, só para a origem de redirect_url, com { source: "wa-embedded", status: "success", phone_id, waba_id }, e se fecha. Aberta fora de um pop-up, ela redireciona para redirect_url com 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:

CampoO que é
codeO 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_tokenAlternativa a code: um token de acesso já trocado.
phone_number_id, waba_id, business_idOs 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.

RecusaQuando
400Sem code nem access_token, ou sem workspace_id.
403 phone_limit_reachedO workspace não tem mais vagas de número.
409 phone_held_by_another_workspaceO número já está conectado a outro workspace.
422 no_phone_numberA conta autorizada não tem nenhum número.
500 onboarding_failedO número não pôde ser salvo; nada foi gravado.
502A Meta recusou a troca do código, ou o repasse ao 360dialog falhou.
503 onboarding_unavailableA 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:

  1. POST /whatsapp/business-phones/{id}/request-verification com method (SMS, o padrão, ou VOICE) e language (por exemplo pt_BR). A Meta envia o código para o número.
  2. POST /whatsapp/business-phones/{id}/verify-code com o code recebido. code vazio responde 400.

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:

  1. Chame a rota de início. Ela devolve, em authorizeUrl, o endereço de autorização do provedor, com um state assinado que liga o pedido ao workspace e a quem pediu. O state vale 15 minutos e uma única vez.
  2. Abra authorizeUrl para a pessoa aprovar o acesso, num pop-up (com popup=1 na rota de início) ou na própria janela.
  3. 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ícioEfeito
returnPathO caminho do painel para onde voltar no fim, começando com /. Um caminho inválido vira o padrão do canal.
popup=1O 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=1A rota de início responde 302 direto para o provedor, em vez do JSON.
CanalRota de inícioPermissãosource no pop-upParâmetro no retorno sem pop-up
InstagramGET /oauth/instagram/startinstagram_accounts:createig-business-logininstagram
FacebookGET /oauth/facebook/startfacebook_pages:createfb-business-loginfacebook
TikTokGET /oauth/tiktok/starttiktok_accounts:createtiktok-logintiktok
Mercado LivreGET /oauth/mercadolivre/startmercadolivre_accounts:createmercadolivre-loginmercadolivre
Google AgendaGET /oauth/google/calendar/startcalendar:creategoogle-logingoogle
Google PlanilhasGET /oauth/google/sheets/startgoogle_sheets:creategoogle-logingoogle

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, pages traz 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.

  1. Confira a cota com GET /unofficial-whatsapp/instances/allowance: canConnect diz se um novo número pode ser criado agora.
  2. Crie o número com POST /unofficial-whatsapp/instances, com displayName, departmentId e importHistory (importa o histórico de conversas ao conectar). Sem cota, 402; sem capacidade nos servidores, 503.
  3. Inicie a vinculação com POST /unofficial-whatsapp/instances/{id}/connect:
modeCorpoResposta
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.

  1. Consulte GET /unofficial-whatsapp/instances/{id}/link-status em intervalos curtos. A resposta traz o número em instance e, enquanto ainda aguarda a leitura, o QR code ou o código vigente. A vinculação terminou quando instance.status vira CONNECTED.
statusSignificado
PROVISIONING, AWAITING_SCANCriado, aguardando a vinculação.
CONNECTEDConectado.
HIBERNATEDSessão em espera.
DISCONNECTEDA sessão deixou de valer; conecte de novo.
BANNEDNúmero banido pelo WhatsApp. connect responde 409.
PROVISION_FAILEDA 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

  1. Crie o bot no BotFather do Telegram e copie o token.
  2. POST /telegram/accounts com botToken e, se quiser, departmentId. O token é conferido no Telegram, o webhook do bot é registrado para a API e a conta volta com status ACTIVE (201).
{ "botToken": "123456789:AA...", "departmentId": "5b0c1d2e-3f4a-4b5c-8d6e-7f8091a2b3c4" }
RespostaQuando
400Token ausente ou recusado pelo Telegram.
409O bot já está conectado a outro workspace.
500O 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.