API atual/Referência completa/WhatsApp Platform

Saúde, números e webhook

Mostra se a integração com a Meta está de pé, lista os números da conta compartilhada e gerencia a assinatura do app nos webhooks.

Depois de gravar as credenciais, estas quatro rotas respondem às perguntas do operador: a Meta aceita o nosso token? Quais números existem na conta e a qual loja cada um pertence? O nosso app está assinado para receber as mensagens?

Todas consultam a Meta (Graph API v23.0) com as credenciais da plataforma, então a resposta depende de a Meta estar acessível. Elas exigem root_admin com o privilégio manage_whatsapp_platform.

Saúde da integração

GET/api/v1/admin/whatsapp-platform/healthAdmin

Resumo de saúde da integração com a Meta

Faz uma única chamada à Meta e devolve se as credenciais estão preenchidas, se a Meta respondeu e quantos números há por qualidade. Uma falha da Meta não vira erro HTTP: a resposta é 200 com connection_ok: false e o texto do problema em error.

200Integração saudável

json

{
  "configured": true,
  "connection_ok": true,
  "waba_id": "104855559999999",
  "numbers_total": 3,
  "verified_count": 3,
  "quality_green": 2,
  "quality_yellow": 0,
  "quality_red": 0,
  "quality_other": 1
}

Campos da resposta

configuredboolean

true quando há token de acesso e id da WABA gravados.

connection_okboolean

true quando a Meta respondeu à listagem de números com as credenciais gravadas.

waba_idstring

Id da WABA gravada (vazio se não configurada).

numbers_totalinteger

Quantidade de números na conta.

verified_countinteger

Quantos têm code_verification_status igual a VERIFIED.

quality_greeninteger

Números com qualidade GREEN.

quality_yellowinteger

Números com qualidade YELLOW.

quality_redinteger

Números com qualidade RED.

quality_otherinteger

Números sem classificação (ainda não enviaram mensagens) ou com outro valor.

errorstring

Só aparece quando a chamada à Meta falhou: a mensagem do erro.

Números da conta

GET/api/v1/admin/whatsapp-platform/numbersAdmin

Listar os números da WABA compartilhada

Pede à Meta todos os números da WABA e, para cada um, procura qual loja o conectou. Para descobrir a loja, a plataforma percorre todas as lojas ativas, então a chamada pode ser lenta com muitas lojas. Um número que existe na conta mas ainda não foi ligado a nenhuma loja vem sem store_name e tenant_id.

200Números listados

json

{
  "data": [
    {
      "phone_number_id": "109876543210987",
      "display_phone_number": "+55 11 99999-8888",
      "verified_name": "Loja Exemplo",
      "code_verification_status": "VERIFIED",
      "quality_rating": "GREEN",
      "store_name": "Loja Exemplo",
      "tenant_id": "8d1f6a52-3b0e-4e57-9f31-2c4a7b9d0e11"
    }
  ]
}

Campos da resposta

dataarray

Números da conta, na ordem em que a Meta devolve.

data[].phone_number_idstring

Id do número na Meta (não é o telefone).

data[].display_phone_numberstring

Telefone como a Meta exibe.

data[].verified_namestring

Nome comercial aprovado pela Meta.

data[].code_verification_statusstring

Situação da verificação por código; VERIFIED quando aceito.

data[].quality_ratingstring

GREEN, YELLOW, RED ou vazio.

data[].store_namestring

Nome da loja dona do número. Ausente quando o número não está ligado a loja.

data[].tenant_idstring

UUID da loja dona do número. Ausente quando não há loja.

Estado do webhook

GET/api/v1/admin/whatsapp-platform/webhookAdmin

Ver o token de verificação e os apps assinados

Mostra o token que você deve colar na configuração de webhook do app da Meta, se o segredo do app está gravado e quais apps estão assinados na WABA. Se a Meta falhar, a resposta continua 200 com o motivo em error.

200Estado do webhook

json

{
  "configured": true,
  "verify_token": "venddor-verify-2026",
  "app_secret_set": true,
  "subscribed_apps": [
    { "name": "Venddor Commerce", "link": "https://example.com/app", "id": "1234567890" }
  ]
}

Campos da resposta

configuredboolean

true quando há token de acesso e WABA gravados. Quando false, subscribed_apps vem vazio e a Meta não é consultada.

verify_tokenstring

Token de verificação do webhook, em texto puro.

app_secret_setboolean

true quando o segredo do app está gravado.

subscribed_appsarray

Apps assinados na WABA, cada um com name, link e id.

errorstring

Só aparece quando a consulta à Meta falhou.

Assinar o app na WABA

POST/api/v1/admin/whatsapp-platform/webhook/subscribeAdmin

Assinar o app da plataforma nos webhooks da WABA

Assina o app dono do token (o app da plataforma) nos webhooks da WABA. Sem essa assinatura, a Meta não entrega as mensagens recebidas. Não tem corpo.

200App assinado

json

{ "success": true }

Exemplo de requisição

bash

# saúde
curl "$BASE_URL/api/v1/admin/whatsapp-platform/health" \
  -H "Authorization: Bearer $TOKEN"

# assinar o app
curl -X POST "$BASE_URL/api/v1/admin/whatsapp-platform/webhook/subscribe" \
  -H "Authorization: Bearer $TOKEN"

Erros

Status	Quando	Corpo de exemplo
401	Sem cabeçalho `Authorization`	`{"error":"missing authorization header"}`
403	Usuário que não é `root_admin`, ou sem o privilégio `manage_whatsapp_platform`	`{"error":"insufficient permissions"}`
503	`numbers` e `webhook/subscribe` quando falta token ou WABA	`{"error":"Configure o token de acesso e o WhatsApp Business Account ID (WABA) na página de credenciais da plataforma antes de listar os números.","kind":"config_missing"}`. Em `webhook/subscribe` a mensagem é `"Configure o token de acesso e o WABA na página de credenciais da plataforma primeiro."`
500	A Meta recusou a chamada em `numbers` ou `webhook/subscribe`, ou falha ao ler o banco	`{"error":"..."}` com a mensagem original da Meta

As mensagens de config_missing são devolvidas em português pelo servidor.

Veja também

API atual/Referência completa/WhatsApp Platform

Saúde, números e webhook

Mostra se a integração com a Meta está de pé, lista os números da conta compartilhada e gerencia a assinatura do app nos webhooks.

Todas consultam a Meta (Graph API v23.0) com as credenciais da plataforma, então a resposta depende de a Meta estar acessível. Elas exigem root_admin com o privilégio manage_whatsapp_platform.

Saúde da integração

GET/api/v1/admin/whatsapp-platform/healthAdmin

Resumo de saúde da integração com a Meta

200Integração saudável

json

{
  "configured": true,
  "connection_ok": true,
  "waba_id": "104855559999999",
  "numbers_total": 3,
  "verified_count": 3,
  "quality_green": 2,
  "quality_yellow": 0,
  "quality_red": 0,
  "quality_other": 1
}

Campos da resposta

configuredboolean

true quando há token de acesso e id da WABA gravados.

connection_okboolean

true quando a Meta respondeu à listagem de números com as credenciais gravadas.

waba_idstring

Id da WABA gravada (vazio se não configurada).

numbers_totalinteger

Quantidade de números na conta.

verified_countinteger

Quantos têm code_verification_status igual a VERIFIED.

quality_greeninteger

Números com qualidade GREEN.

quality_yellowinteger

Números com qualidade YELLOW.

quality_redinteger

Números com qualidade RED.

quality_otherinteger

Números sem classificação (ainda não enviaram mensagens) ou com outro valor.

errorstring

Só aparece quando a chamada à Meta falhou: a mensagem do erro.

Números da conta

GET/api/v1/admin/whatsapp-platform/numbersAdmin

Listar os números da WABA compartilhada

200Números listados

json

{
  "data": [
    {
      "phone_number_id": "109876543210987",
      "display_phone_number": "+55 11 99999-8888",
      "verified_name": "Loja Exemplo",
      "code_verification_status": "VERIFIED",
      "quality_rating": "GREEN",
      "store_name": "Loja Exemplo",
      "tenant_id": "8d1f6a52-3b0e-4e57-9f31-2c4a7b9d0e11"
    }
  ]
}

Campos da resposta

dataarray

Números da conta, na ordem em que a Meta devolve.

data[].phone_number_idstring

Id do número na Meta (não é o telefone).

data[].display_phone_numberstring

Telefone como a Meta exibe.

data[].verified_namestring

Nome comercial aprovado pela Meta.

data[].code_verification_statusstring

Situação da verificação por código; VERIFIED quando aceito.

data[].quality_ratingstring

GREEN, YELLOW, RED ou vazio.

data[].store_namestring

Nome da loja dona do número. Ausente quando o número não está ligado a loja.

data[].tenant_idstring

UUID da loja dona do número. Ausente quando não há loja.

Estado do webhook

GET/api/v1/admin/whatsapp-platform/webhookAdmin

Ver o token de verificação e os apps assinados

200Estado do webhook

json

{
  "configured": true,
  "verify_token": "venddor-verify-2026",
  "app_secret_set": true,
  "subscribed_apps": [
    { "name": "Venddor Commerce", "link": "https://example.com/app", "id": "1234567890" }
  ]
}

Campos da resposta

configuredboolean

true quando há token de acesso e WABA gravados. Quando false, subscribed_apps vem vazio e a Meta não é consultada.

verify_tokenstring

Token de verificação do webhook, em texto puro.

app_secret_setboolean

true quando o segredo do app está gravado.

subscribed_appsarray

Apps assinados na WABA, cada um com name, link e id.

errorstring

Só aparece quando a consulta à Meta falhou.

Assinar o app na WABA

POST/api/v1/admin/whatsapp-platform/webhook/subscribeAdmin

Assinar o app da plataforma nos webhooks da WABA

Assina o app dono do token (o app da plataforma) nos webhooks da WABA. Sem essa assinatura, a Meta não entrega as mensagens recebidas. Não tem corpo.

200App assinado

json

{ "success": true }

Exemplo de requisição

bash

# saúde
curl "$BASE_URL/api/v1/admin/whatsapp-platform/health" \
  -H "Authorization: Bearer $TOKEN"

# assinar o app
curl -X POST "$BASE_URL/api/v1/admin/whatsapp-platform/webhook/subscribe" \
  -H "Authorization: Bearer $TOKEN"

Erros

Status	Quando	Corpo de exemplo
401	Sem cabeçalho `Authorization`	`{"error":"missing authorization header"}`
403	Usuário que não é `root_admin`, ou sem o privilégio `manage_whatsapp_platform`	`{"error":"insufficient permissions"}`
503	`numbers` e `webhook/subscribe` quando falta token ou WABA	`{"error":"Configure o token de acesso e o WhatsApp Business Account ID (WABA) na página de credenciais da plataforma antes de listar os números.","kind":"config_missing"}`. Em `webhook/subscribe` a mensagem é `"Configure o token de acesso e o WABA na página de credenciais da plataforma primeiro."`
500	A Meta recusou a chamada em `numbers` ou `webhook/subscribe`, ou falha ao ler o banco	`{"error":"..."}` com a mensagem original da Meta

As mensagens de config_missing são devolvidas em português pelo servidor.