VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/WhatsApp: conexão e configuração

Cadastro do número

Troca o código do Embedded Signup, assina o webhook e pede a importação única de histórico e contatos.

Trocar o código do Embedded Signup

Última etapa do cadastro no navegador: troca o code da Meta por um token de acesso, descobre a WABA concedida e cria uma conta para cada número dela. Devolve a conta principal (a primeira). Só administrador pode chamar, porque a conta criada é a da loja inteira.

POST/api/v1/admin/whatsapp-confluence/onboarding/exchange-codeAdmin

Troca o código do Embedded Signup

Corpo da requisição

codestringobrigatório
Código de autorização devolvido pelo Embedded Signup. Curta duração.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp-confluence/onboarding/exchange-code" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "AQD3x...codigo-da-meta"}'

Resposta

200Conta criada
json
{
  "id": "11111111-1111-4111-8111-111111111111",
  "phone_number_id": "109876543210987",
  "business_phone": "5511987654321",
  "display_name": "Loja Exemplo",
  "waba_id": "208765432109876",
  "status": "P",
  "onboarding_state": "X",
  "step": "connected",
  "is_on_biz_app": true,
  "platform_type": "CLOUD_API",
  "webhook_subscribed": false,
  "sync_window_open": true,
  "history_sync_requested": false,
  "history_sync_status": "P",
  "contacts_sync_requested": false,
  "contacts_sync_status": "P",
  "sync_deadline_at": "2026-10-12T14:30:00Z"
}

Campos da resposta

(corpo)object
A conta principal, com os campos listados em Listar contas.

Erros

StatusQuandoCorpo de exemplo
400JSON inválido.{"error":"invalid JSON body"}
400Código vazio.{"error":"código de autorização ausente","kind":""}
400A Meta não devolveu token, a conta WABA ou número algum.{"error":"Nenhum número encontrado na conta WhatsApp Business concedida.","kind":""}
403Chamador não é administrador.{"error":"acesso negado","kind":"forbidden"}
409A plataforma não tem as credenciais do aplicativo da Meta.{"error":"Credenciais da plataforma (app_id/app_secret) não configuradas no painel IO.","kind":"config_missing"}
500Falha ao falar com a Meta.{"error":"..."}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem papel de administrador.{"error":"insufficient permissions"}
200 não quer dizer pronto

Se o número não for compatível (não está no aplicativo WhatsApp Business, ou o tipo de plataforma não é o esperado), a conta é criada com status E e step error, e a resposta ainda é 200. Confira status antes de seguir. Ao final do cadastro, sync_deadline_at marca 24 horas para importar histórico e contatos.

Assinar o webhook

Registra a plataforma na Meta para receber as mensagens e os status deste número, apontando para um endereço exclusivo da loja. Marca a conta como webhook_subscribed e avança o cadastro para subscribed. Se você não chamar, uma rotina em segundo plano tenta por conta própria.

POST/api/v1/admin/whatsapp-confluence/onboarding/subscribe-webhookAdmin

Assina os eventos de um número

Corpo da requisição

account_iduuidobrigatório
Id da conta. Se faltar no corpo, a API usa o parâmetro id da URL, que nestas rotas não existe: então é obrigatório na prática.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp-confluence/onboarding/subscribe-webhook" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "11111111-1111-4111-8111-111111111111"}'

Resposta

200Conta atualizada
json
{
  "id": "11111111-1111-4111-8111-111111111111",
  "phone_number_id": "109876543210987",
  "business_phone": "5511987654321",
  "display_name": "Loja Exemplo",
  "waba_id": "208765432109876",
  "status": "P",
  "onboarding_state": "S",
  "step": "subscribed",
  "is_on_biz_app": true,
  "platform_type": "CLOUD_API",
  "webhook_subscribed": true,
  "sync_window_open": false,
  "history_sync_requested": false,
  "history_sync_status": "P",
  "contacts_sync_requested": false,
  "contacts_sync_status": "P"
}

Campos da resposta

(corpo)object
A conta atualizada.

Erros

StatusQuandoCorpo de exemplo
400account_id ausente.{"error":"account_id required"}
403Seller tentando mexer em conta que não é dele.{"error":"acesso negado","kind":"forbidden"}
404Conta inexistente.{"error":"conta não encontrada","kind":"not_found"}
409Faltam o token de verificação ou a URL pública na plataforma.{"error":"verify_token da plataforma não configurado no painel IO.","kind":"config_missing"}
500A Meta recusou a assinatura.{"error":"..."}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem papel de administrador.{"error":"insufficient permissions"}
Corpo opcional?

Um corpo vazio ou inválido não gera erro de JSON: ele só deixa account_id em branco e a resposta é 400 account_id required.

Importar o histórico

Pede à Meta que envie as conversas dos últimos meses do aplicativo WhatsApp Business para dentro da caixa de entrada. A resposta é imediata, mas a importação chega depois, pelo webhook; acompanhe history_sync_status. Só uma vez, e só nas 24 horas depois do cadastro.

POST/api/v1/admin/whatsapp-confluence/onboarding/sync-historyAdmin

Pede a importação do histórico

Corpo da requisição

account_iduuidobrigatório
Id da conta. Se faltar no corpo, a API usa o parâmetro id da URL, que nestas rotas não existe: então é obrigatório na prática.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp-confluence/onboarding/sync-history" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "11111111-1111-4111-8111-111111111111"}'

Resposta

200Pedido aceito
json
{
  "id": "11111111-1111-4111-8111-111111111111",
  "phone_number_id": "109876543210987",
  "business_phone": "5511987654321",
  "display_name": "Loja Exemplo",
  "waba_id": "208765432109876",
  "status": "A",
  "onboarding_state": "H",
  "step": "sync_requested",
  "is_on_biz_app": true,
  "platform_type": "CLOUD_API",
  "webhook_subscribed": true,
  "sync_window_open": true,
  "history_sync_requested": true,
  "history_sync_status": "R",
  "contacts_sync_requested": false,
  "contacts_sync_status": "P"
}

Campos da resposta

(corpo)object
A conta atualizada, com history_sync_requested true e history_sync_status R.

Erros

StatusQuandoCorpo de exemplo
400account_id ausente.{"error":"account_id required"}
403Seller tentando mexer em conta que não é dele.{"error":"acesso negado","kind":"forbidden"}
404Conta inexistente.{"error":"conta não encontrada","kind":"not_found"}
409Janela de 24 horas encerrada.{"error":"A janela de 24h para importar histórico/contatos já encerrou.","kind":"window_closed"}
409Já foi pedido antes.{"error":"A importação já foi solicitada uma vez (operação one-shot).","kind":"already_requested"}
500A Meta recusou o pedido.{"error":"..."}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem papel de administrador.{"error":"insufficient permissions"}
Não há segunda chance

A plataforma grava que o pedido foi feito antes de falar com a Meta, para ninguém reabrir a janela por acidente. Se a Meta recusar (resposta 500), history_sync_status vira E e o direito de pedir continua gasto.

Importar os contatos

Igual a importar o histórico, mas para a agenda do aplicativo WhatsApp Business. Os contatos chegam pelo webhook e podem ser consultados em Contatos importados. Mesmas regras: uma vez só, dentro de 24 horas.

POST/api/v1/admin/whatsapp-confluence/onboarding/sync-contactsAdmin

Pede a importação dos contatos

Corpo da requisição

account_iduuidobrigatório
Id da conta. Se faltar no corpo, a API usa o parâmetro id da URL, que nestas rotas não existe: então é obrigatório na prática.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp-confluence/onboarding/sync-contacts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "11111111-1111-4111-8111-111111111111"}'

Resposta

200Pedido aceito
json
{
  "id": "11111111-1111-4111-8111-111111111111",
  "phone_number_id": "109876543210987",
  "business_phone": "5511987654321",
  "display_name": "Loja Exemplo",
  "waba_id": "208765432109876",
  "status": "A",
  "onboarding_state": "H",
  "step": "sync_requested",
  "is_on_biz_app": true,
  "platform_type": "CLOUD_API",
  "webhook_subscribed": true,
  "sync_window_open": true,
  "history_sync_requested": false,
  "history_sync_status": "P",
  "contacts_sync_requested": true,
  "contacts_sync_status": "R"
}

Campos da resposta

(corpo)object
A conta atualizada, com contacts_sync_requested true e contacts_sync_status R.

Erros

StatusQuandoCorpo de exemplo
400account_id ausente.{"error":"account_id required"}
403Seller tentando mexer em conta que não é dele.{"error":"acesso negado","kind":"forbidden"}
404Conta inexistente.{"error":"conta não encontrada","kind":"not_found"}
409Janela de 24 horas encerrada.{"error":"A janela de 24h para importar histórico/contatos já encerrou.","kind":"window_closed"}
409Já foi pedido antes.{"error":"A importação já foi solicitada uma vez (operação one-shot).","kind":"already_requested"}
500A Meta recusou o pedido.{"error":"..."}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem papel de administrador.{"error":"insufficient permissions"}
Peça os dois juntos

Como a janela é a mesma para histórico e contatos, faça as duas chamadas logo depois de assinar o webhook.

Veja também

  • Conexão e contas
  • Caixa de entrada
Anterior
Conexão e contas
Próxima
Configurações do canal
Nesta página
  • Trocar o código do Embedded Signup
  • Exemplo de requisição
  • Resposta
  • Erros
  • Assinar o webhook
  • Exemplo de requisição
  • Resposta
  • Erros
  • Importar o histórico
  • Exemplo de requisição
  • Resposta
  • Erros
  • Importar os contatos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também