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

Conexão e contas

Mostra se o WhatsApp da loja está conectado, lista e desconecta contas e checa se a loja atende ligações.

Consultar a situação da conexão

Devolve um retrato da conexão: se a plataforma tem as credenciais da Meta, se existe um número ativo, os dados do número principal e a lista de contas. É a chamada que um painel faz ao abrir a tela de WhatsApp para decidir se mostra o assistente de cadastro ou a caixa de entrada.

GET/api/v1/admin/whatsapp-confluence/onboarding/statusAdmin

Situação da conexão do WhatsApp

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/whatsapp-confluence/onboarding/status" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Conexão consultada
json
{
  "platform_configured": true,
  "connected": true,
  "status": "connected",
  "phone_number": "5511987654321",
  "phone_number_id": "109876543210987",
  "waba_id": "208765432109876",
  "verified_name": "Loja Exemplo",
  "platform_type": "CLOUD_API",
  "app_active": true,
  "webhooks_subscribed": true,
  "accounts": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "phone_number_id": "109876543210987",
      "business_phone": "5511987654321",
      "display_name": "Loja Exemplo",
      "waba_id": "208765432109876",
      "status": "A",
      "onboarding_state": "C",
      "step": "complete",
      "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"
    }
  ],
  "capabilities": {
    "enable_inbox": true,
    "enable_bot": true,
    "enable_campaigns": true,
    "enable_web_preview": true,
    "enable_meta_flows": false
  }
}

Campos da resposta

platform_configuredboolean
A plataforma tem meta_app_id, segredo do aplicativo e token de verificação. Se for false, o cadastro do número não funciona e o suporte da plataforma precisa configurar.
connectedboolean
Existe ao menos uma conta ativa com número (ou, na falta dela, uma conta em cadastro que já tem número).
statusstring
connectednot_connected
connected ou not_connected.
phone_numberstring
Telefone do número principal. Ausente se não houver.
phone_number_idstring
Id do número principal na Meta. Ausente se não houver.
waba_idstring
Id da WABA do número principal.
verified_namestring
Nome verificado do número principal.
platform_typestring
Tipo de plataforma do número principal.
app_activeboolean
O número principal também está no aplicativo WhatsApp Business.
webhooks_subscribedboolean
O webhook do número principal está assinado.
via_storeboolean
Só para seller: o número é o da loja.
accountsarray
Todas as contas visíveis. Cada item tem os campos descritos em Listar contas.
capabilitiesobject
Mapa de recursos (enable_*, allow_*, show_* e outros) com o valor efetivo para esta loja. Veja Configurações do canal.

Erros

StatusQuandoCorpo de exemplo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem papel de administrador.{"error":"insufficient permissions"}
Campos opcionais somem

Os campos phone_number, phone_number_id, waba_id, verified_name, platform_type, app_active, webhooks_subscribed e via_store só aparecem quando valem algo (texto não vazio ou true). Trate a ausência como vazio ou false.

Listar as contas

Lista todas as contas (números) da loja, inclusive as desconectadas (status D). Use para montar a tela de gestão de números ou para achar o id que as rotas de cadastro pedem.

GET/api/v1/admin/whatsapp-confluence/accountsAdmin

Lista as contas de WhatsApp

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/whatsapp-confluence/accounts" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Contas retornadas
json
{
  "accounts": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "phone_number_id": "109876543210987",
      "business_phone": "5511987654321",
      "display_name": "Loja Exemplo",
      "waba_id": "208765432109876",
      "status": "A",
      "onboarding_state": "C",
      "step": "complete",
      "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

accountsarray
Contas da loja. Lista vazia se nenhum número foi cadastrado.
accounts[].iduuid
Identificador da conta (uma linha por número conectado). Use-o nas rotas que recebem account_id.
accounts[].phone_number_idstring
Id do número na Meta (não é o telefone). Vazio em conta ainda sem número.
accounts[].business_phonestring
Telefone de exibição, só dígitos com DDI (5511987654321).
accounts[].display_namestring
Nome verificado da empresa no WhatsApp.
accounts[].waba_idstring
Id da conta WhatsApp Business (WABA) na Meta.
accounts[].statusstring
PAED
Estado da conta.
accounts[].onboarding_statestring
QXSHCE
Etapa do cadastro, em uma letra.
accounts[].stepstring
queuedconnectedsubscribedsync_requestedcompleteerrorunknown
O mesmo estado de onboarding_state, em texto.
accounts[].is_on_biz_appboolean
O número também está no aplicativo WhatsApp Business do celular.
accounts[].platform_typestring
Tipo de plataforma informado pela Meta (por exemplo CLOUD_API).
accounts[].webhook_subscribedboolean
O aplicativo já recebe os eventos deste número.
accounts[].sync_deadline_atstring
Fim da janela de 24 horas para importar histórico e contatos (RFC 3339). Ausente se não houver janela.
accounts[].sync_window_openboolean
A janela de importação ainda está aberta agora.
accounts[].history_sync_requestedboolean
A importação de histórico já foi pedida (só pode ser pedida uma vez).
accounts[].history_sync_statusstring
PRDE
Situação da importação de histórico.
accounts[].contacts_sync_requestedboolean
A importação de contatos já foi pedida (uma vez só).
accounts[].contacts_sync_statusstring
PRDE
Situação da importação de contatos.
accounts[].via_storeboolean
Só aparece (como true) para um seller: o número é o da loja, mostrado sem os ids da Meta.

Erros

StatusQuandoCorpo de exemplo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem papel de administrador.{"error":"insufficient permissions"}
Significado dos códigos

Valores de status: P pendente, A ativa, E com erro, D desconectada. Valores de onboarding_state: Q na fila, X código trocado, S webhook assinado, H importação pedida, C completo, E erro. Valores de *_sync_status: P ainda não pedida, R pedida e aguardando, D concluída, E falhou.

Desconectar uma conta

Cancela a assinatura de eventos da Meta (sem garantia: se a Meta recusar, a plataforma segue em frente) e marca a conta como desconectada (status D). A conta não é apagada: histórico e trilha de auditoria continuam. Reconectar o mesmo número é refazer o cadastro com Trocar o código.

DELETE/api/v1/admin/whatsapp-confluence/accounts/{id}Admin

Desconecta uma conta de WhatsApp

Parâmetros de caminho

iduuidobrigatório
Id da conta (campo id de Listar contas).

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/admin/whatsapp-confluence/accounts/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Conta desconectada
json
{
  "success": true
}

Campos da resposta

successboolean
Sempre true quando a conta foi marcada como desconectada.

Erros

StatusQuandoCorpo de exemplo
404Não existe conta com esse id.{"error":"conta não encontrada","kind":"not_found"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem papel de administrador.{"error":"insufficient permissions"}
A loja deixa de receber mensagens

Depois de desconectar o único número ativo, a caixa de entrada para de receber mensagens novas e o assistente deixa de responder naquele número. Mensagens antigas continuam consultáveis.

Ler os dados do Embedded Signup

Devolve o que o navegador precisa para abrir a janela de cadastro da Meta. Só traz dados públicos; o segredo do aplicativo e o token de verificação nunca saem por aqui.

GET/api/v1/admin/whatsapp-confluence/onboarding/es-configAdmin

Dados para abrir o Embedded Signup

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/whatsapp-confluence/onboarding/es-config" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Configuração lida
json
{
  "meta_app_id": "1234567890123456",
  "embedded_signup_config_id": "9876543210987654",
  "configured": true
}

Campos da resposta

meta_app_idstring
Id do aplicativo da plataforma na Meta. Vazio se não configurado.
embedded_signup_config_idstring
Id da configuração do Embedded Signup. Vazio se não configurado.
configuredboolean
true só quando os dois ids existem.

Erros

StatusQuandoCorpo de exemplo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem papel de administrador.{"error":"insufficient permissions"}
Como usar

Passe os dois ids ao SDK JavaScript da Meta (FB.login com config_id). Quando o usuário termina, a Meta devolve um code: envie-o a Trocar o código logo, pois ele expira em poucos minutos.

Diagnosticar ligações

Responde à pergunta do lojista: "por que o telefone toca e ninguém atende?". Roda duas verificações (atendente virtual de voz ligado no servidor e número de WhatsApp conectado com credencial válida) e diz se a loja consegue atender ligações nativas do WhatsApp, com a correção sugerida quando algo falha.

GET/api/v1/admin/whatsapp-confluence/diagnosticoAdmin

Diagnóstico de ligações do WhatsApp

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/whatsapp-confluence/diagnostico" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Diagnóstico
json
{
  "can_answer": true,
  "summary": "A loja consegue atender ligação no WhatsApp.",
  "checks": [
    {
      "id": "vi",
      "label": "Atendente virtual",
      "status": "ok",
      "detail": "A VI de voz está configurada neste servidor."
    },
    {
      "id": "conta",
      "label": "Número do WhatsApp",
      "status": "ok",
      "detail": "Número conectado e com credencial válida."
    }
  ],
  "phone_number_id": "109876543210987"
}

Campos da resposta

can_answerboolean
true quando as duas verificações passam.
summarystring
Resumo legível, em português.
checksarray
Uma entrada por verificação.
checks[].idstring
viconta
Identificador da verificação.
checks[].labelstring
Nome da verificação.
checks[].statusstring
okerroaviso
Resultado.
checks[].detailstring
Explicação do resultado.
checks[].fixstring
O que fazer para corrigir. Ausente quando está tudo certo.
phone_number_idstring
Número verificado. Vazio se não houver conta.

Erros

StatusQuandoCorpo de exemplo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem papel de administrador.{"error":"insufficient permissions"}
Textos em português

summary, label, detail e fix são devolvidos em português pelo servidor, qualquer que seja o idioma da sua interface.

Veja também

  • Cadastro do número
  • Configurações do canal
Anterior
WhatsApp: conexão e configuração
Próxima
Cadastro do número
Nesta página
  • Consultar a situação da conexão
  • Exemplo de requisição
  • Resposta
  • Erros
  • Listar as contas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Desconectar uma conta
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ler os dados do Embedded Signup
  • Exemplo de requisição
  • Resposta
  • Erros
  • Diagnosticar ligações
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também