API atual/Referência completa/WhatsApp: número e perfil

Conectar um número

Cadastro guiado em passos: cadastrar o telefone, pedir o código, confirmá-lo e consultar o status.

O cadastro guiado (self-setup) é para o seller que ainda não tem o número na Meta. Ele percorre quatro chamadas, nesta ordem: cadastrar, pedir o código, confirmar e (quando precisar) consultar o status. Os três primeiros passos agem sobre o seller dono do token; o vendor_id do corpo, se enviado, é ignorado.

Se o número já existe na Meta, use Salvar a credencial e pule este fluxo.

1. Cadastrar o número

Primeiro passo do cadastro guiado. A plataforma adiciona o telefone à conta empresarial (WABA) dela na Meta, envia o perfil inicial e cria a credencial do seller em estado pendente (P): ainda não entrega mensagens. A resposta traz o phone_number_id, que você usa nos passos seguintes. Se o número já estava na WABA de uma tentativa anterior, ele é reaproveitado (already_existed: true).

Por padrão cada seller tem um número. Para trocar o ativo, envie replace_existing: true.

POST/api/v1/vendor/whatsapp/self-setup/registerSeller

Adiciona o número ao cadastro e cria a credencial pendente

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (lojista). Veja Tokens.

Content-Typestringobrigatório

application/json.

Corpo da requisição

phone_numberstringobrigatório

Telefone sem o código do país. Qualquer formatação é aceita; só os dígitos são usados. Obrigatório.

country_codestringpadrão: 55

Código do país, só dígitos, sem +.

display_namestringobrigatório

Nome oficial do negócio que a Meta vai revisar (verified_name). Obrigatório.

display_name_2string

Nome alternativo, guardado para reenvio se a Meta recusar o principal.

display_name_3string

Segundo nome alternativo.

categorystring

Categoria (vertical) da Meta, como RETAIL.

descriptionstring

Descrição do negócio.

addressstring

Endereço.

emailstring

E-mail de contato.

websitestring

Site principal.

website_2string

Segundo site (a Meta aceita até dois).

usernamestring

Novo @usuário do WhatsApp, opcional e de melhor esforço.

profile_picture_urlstring

Endereço público (/uploads/...) da foto de perfil, opcional.

replace_existingbooleanpadrão: false

Autoriza trocar o número ativo do seller por este. Sem isso, quem já tem número ativo recebe 409 limit_reached.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/self-setup/register" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "55",
    "phone_number": "(41) 99999-0000",
    "display_name": "Casa do Pão Quente",
    "category": "RETAIL",
    "description": "Pães artesanais e café fresco todos os dias.",
    "email": "contato@casadopao.example.com",
    "website": "https://casadopao.example.com"
  }'

Resposta

200Número cadastrado

json

{
  "success": true,
  "data": {
    "phone_number_id": "109876543210987",
    "business_phone": "+5541999990000",
    "already_existed": false,
    "status": "pending_verification"
  }
}

Campos da resposta

successboolean

Sempre true neste formato.

dataobject

Resultado do cadastro.

phone_number_idstring

Id do número na Meta. Guarde: os próximos passos pedem.

business_phonestring

Telefone completo em formato internacional.

already_existedboolean

true se o número já estava na conta empresarial.

statusstring

Sempre pending_verification aqui.

route_pendingboolean

Só aparece, com true, se o número já entrega mensagens a outro destino e a rota não foi sobrescrita.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é um JSON válido.	`{"error":"Invalid request body"}`
500	`phone_number` ou `display_name` ausentes, ou erro devolvido pela Meta. Hoje essas validações também saem como `500`, com a mensagem em `error`.	`{"error":"whatsapp self-setup: phone number required"}`
409	O seller já tem um número ativo e `replace_existing` não foi enviado (`kind: limit_reached`).	`{"error":"Esta loja já tem um número de WhatsApp ativo. Remova o atual antes de adicionar outro.","kind":"limit_reached"}`
409	O número já tem uma conta de WhatsApp pessoal ativa (`whatsapp_exists`), foi removido da Meta (`phone_deleted`), é de outro seller da loja (`number_in_use`) ou de outra loja (`number_in_use_other_store`).	`{"error":"Este número já possui uma conta WhatsApp ativa. Exclua a conta do WhatsApp neste número antes de cadastrá-lo na plataforma.","kind":"whatsapp_exists"}`
409	A loja tem números de vários sellers e quem chama não é o seller dono (`kind: seller_required_for_number`). Entre com o usuário do seller.	`{"error":"Esta loja tem números de vários vendedores. Entre com o usuário do vendedor dono do número para cadastrá-lo, trocá-lo ou verificá-lo.","kind":"seller_required_for_number"}`
503	A plataforma não tem token da Meta válido configurado para cadastrar números (`kind: config_missing`).	`{"error":"Token de acesso da Meta inválido ou expirado. ...","kind":"config_missing"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O usuário não é um seller, o módulo de WhatsApp está desligado na loja (`module_disabled`) ou o cadastro do seller ainda está em análise (`vendor_pending_review`).	`{"error":"module_disabled","module":"whatsapp-commerce"}`
403	O usuário não tem o privilégio de seller `vendor_manage_whatsapp`.	`{"error":"insufficient vendor privileges","required":"vendor_manage_whatsapp"}`

2. Pedir o código

Segundo passo: a Meta envia um código de 6 dígitos ao telefone, por SMS ou por ligação de voz. O número precisa ter sido cadastrado pelo seller que chama (passo 1). Cada método (SMS e VOICE) tem a sua própria contagem: há um intervalo mínimo de 60 segundos entre pedidos do mesmo método e, quando a Meta bloqueia por excesso de tentativas, a espera cresce de 15 minutos até 24 horas. Se o número já estiver verificado, a chamada responde 200 sem enviar nada.

POST/api/v1/vendor/whatsapp/self-setup/request-codeSeller

Envia o código de verificação por SMS ou ligação

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (lojista). Veja Tokens.

Content-Typestringobrigatório

application/json.

Corpo da requisição

phone_number_idstringobrigatório

Id devolvido no passo 1. Precisa ser o número do próprio seller.

methodstringpadrão: SMS

SMSVOICE

Como receber o código.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/self-setup/request-code" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "109876543210987",
    "method": "SMS"
  }'

Resposta

200Código enviado

json

{
  "success": true
}

Campos da resposta

successboolean

Sempre true.

Erros

Status	Quando	Corpo de exemplo
403	`phone_number_id` ausente ou que não é o número deste seller.	`{"error":"Número não pertence a esta loja"}`
429	Intervalo mínimo ou bloqueio ativo (`kind: rate_limited`). `retry_after_seconds` diz quanto esperar e `method` qual método está limitado.	`{"error":"Aguarde 45 segundos para solicitar um novo código via SMS, ou tente outro método.","kind":"rate_limited","retry_after_seconds":45,"method":"SMS"}`
409	O número foi removido da Meta (`kind: phone_deleted`): refaça o passo 1.	`{"error":"Este número foi removido da Meta. Cadastre o número novamente em \"Adicionar número\".","kind":"phone_deleted"}`
503	Sem token da Meta configurado na plataforma (`kind: config_missing`).	`{"error":"...","kind":"config_missing"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O usuário não é um seller, o módulo de WhatsApp está desligado na loja (`module_disabled`) ou o cadastro do seller ainda está em análise (`vendor_pending_review`).	`{"error":"module_disabled","module":"whatsapp-commerce"}`
403	O usuário não tem o privilégio de seller `vendor_manage_whatsapp`.	`{"error":"insufficient vendor privileges","required":"vendor_manage_whatsapp"}`

3. Confirmar o código

Terceiro passo: o seller digita o código recebido. A plataforma o confirma na Meta, conclui o registro do número na Cloud API com um PIN de duas etapas aleatório de 6 dígitos (devolvido em two_step_pin), ativa a credencial e registra a rota de recebimento de mensagens. Em seguida prepara o atendimento: reaplica o perfil, cria a chave de criptografia dos fluxos nativos e garante que o seller tenha um fluxo de boas-vindas próprio.

POST/api/v1/vendor/whatsapp/self-setup/verifySeller

Valida o código e conclui o registro do número

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (lojista). Veja Tokens.

Content-Typestringobrigatório

application/json.

Corpo da requisição

phone_number_idstringobrigatório

Id do passo 1.

codestringobrigatório

Código de 6 dígitos recebido.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/self-setup/verify" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "109876543210987",
    "code": "123456"
  }'

Resposta

200Número ativo

json

{
  "success": true,
  "two_step_pin": "482913",
  "register_ok": true,
  "data": {
    "two_step_pin": "482913",
    "register_ok": true
  }
}

Campos da resposta

successboolean

Sempre true.

two_step_pinstring

PIN de duas etapas gerado. Fica guardado e volta em Ler a credencial.

register_okboolean

false se a Meta recusou o registro na Cloud API por um motivo que não é "já registrado". O número pode então não receber mensagens.

dataobject

Cópia de two_step_pin e register_ok.

route_pendingboolean

Só aparece, com true, se o número já entrega mensagens a outro destino.

Erros

Status	Quando	Corpo de exemplo
403	`code` ausente, `phone_number_id` ausente ou que não é do seller.	`{"error":"Número não pertence a esta loja ou código ausente"}`
500	Código errado ou expirado: o erro da Meta sai como `500` com a mensagem dela em `error`.	`{"error":"meta 400: ..."}`
503	Sem token da Meta configurado na plataforma (`kind: config_missing`).	`{"error":"...","kind":"config_missing"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O usuário não é um seller, o módulo de WhatsApp está desligado na loja (`module_disabled`) ou o cadastro do seller ainda está em análise (`vendor_pending_review`).	`{"error":"module_disabled","module":"whatsapp-commerce"}`
403	O usuário não tem o privilégio de seller `vendor_manage_whatsapp`.	`{"error":"insufficient vendor privileges","required":"vendor_manage_whatsapp"}`

Conferir o status

Consulta na Meta em que ponto está o número: o nome verificado, o telefone de exibição e a situação do código. Use para retomar o assistente depois de um recarregamento da página ou para saber se o passo 3 já foi concluído.

GET/api/v1/vendor/whatsapp/self-setup/statusSeller

Retorna o nome verificado e a situação do código do número

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (lojista). Veja Tokens.

Parâmetros de consulta

phone_number_idstringobrigatório

Id do número. Precisa ser o do próprio seller.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/whatsapp/self-setup/status?phone_number_id=109876543210987" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Estado do número

json

{
  "success": true,
  "data": {
    "phone_number_id": "109876543210987",
    "verified_name": "Casa do Pão Quente",
    "display_phone_number": "+55 41 99999-0000",
    "code_verification_status": "VERIFIED"
  }
}

Campos da resposta

successboolean

Sempre true.

dataobject

Estado lido na Meta.

phone_number_idstring

Id do número.

verified_namestring

Nome verificado pela Meta (vazio se ainda não aprovado).

display_phone_numberstring

Telefone como a Meta o mostra.

code_verification_statusstring

Situação do código, como VERIFIED ou NOT_VERIFIED, conforme a Meta.

Erros

Status	Quando	Corpo de exemplo
403	`phone_number_id` ausente ou que não é deste seller.	`{"error":"Número não pertence a esta loja"}`
503	Sem token da Meta configurado na plataforma (`kind: config_missing`).	`{"error":"...","kind":"config_missing"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O usuário não é um seller, o módulo de WhatsApp está desligado na loja (`module_disabled`) ou o cadastro do seller ainda está em análise (`vendor_pending_review`).	`{"error":"module_disabled","module":"whatsapp-commerce"}`
403	O usuário não tem o privilégio de seller `vendor_manage_whatsapp`.	`{"error":"insufficient vendor privileges","required":"vendor_manage_whatsapp"}`

Veja também

API atual/Referência completa/WhatsApp: número e perfil

Conectar um número

Cadastro guiado em passos: cadastrar o telefone, pedir o código, confirmá-lo e consultar o status.

Se o número já existe na Meta, use Salvar a credencial e pule este fluxo.

1. Cadastrar o número

Por padrão cada seller tem um número. Para trocar o ativo, envie replace_existing: true.

POST/api/v1/vendor/whatsapp/self-setup/registerSeller

Adiciona o número ao cadastro e cria a credencial pendente

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (lojista). Veja Tokens.

Content-Typestringobrigatório

application/json.

Corpo da requisição

phone_numberstringobrigatório

Telefone sem o código do país. Qualquer formatação é aceita; só os dígitos são usados. Obrigatório.

country_codestringpadrão: 55

Código do país, só dígitos, sem +.

display_namestringobrigatório

Nome oficial do negócio que a Meta vai revisar (verified_name). Obrigatório.

display_name_2string

Nome alternativo, guardado para reenvio se a Meta recusar o principal.

display_name_3string

Segundo nome alternativo.

categorystring

Categoria (vertical) da Meta, como RETAIL.

descriptionstring

Descrição do negócio.

addressstring

Endereço.

emailstring

E-mail de contato.

websitestring

Site principal.

website_2string

Segundo site (a Meta aceita até dois).

usernamestring

Novo @usuário do WhatsApp, opcional e de melhor esforço.

profile_picture_urlstring

Endereço público (/uploads/...) da foto de perfil, opcional.

replace_existingbooleanpadrão: false

Autoriza trocar o número ativo do seller por este. Sem isso, quem já tem número ativo recebe 409 limit_reached.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/self-setup/register" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "55",
    "phone_number": "(41) 99999-0000",
    "display_name": "Casa do Pão Quente",
    "category": "RETAIL",
    "description": "Pães artesanais e café fresco todos os dias.",
    "email": "contato@casadopao.example.com",
    "website": "https://casadopao.example.com"
  }'

Resposta

200Número cadastrado

json

{
  "success": true,
  "data": {
    "phone_number_id": "109876543210987",
    "business_phone": "+5541999990000",
    "already_existed": false,
    "status": "pending_verification"
  }
}

Campos da resposta

successboolean

Sempre true neste formato.

dataobject

Resultado do cadastro.

phone_number_idstring

Id do número na Meta. Guarde: os próximos passos pedem.

business_phonestring

Telefone completo em formato internacional.

already_existedboolean

true se o número já estava na conta empresarial.

statusstring

Sempre pending_verification aqui.

route_pendingboolean

Só aparece, com true, se o número já entrega mensagens a outro destino e a rota não foi sobrescrita.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é um JSON válido.	`{"error":"Invalid request body"}`
500	`phone_number` ou `display_name` ausentes, ou erro devolvido pela Meta. Hoje essas validações também saem como `500`, com a mensagem em `error`.	`{"error":"whatsapp self-setup: phone number required"}`
409	O seller já tem um número ativo e `replace_existing` não foi enviado (`kind: limit_reached`).	`{"error":"Esta loja já tem um número de WhatsApp ativo. Remova o atual antes de adicionar outro.","kind":"limit_reached"}`
409	O número já tem uma conta de WhatsApp pessoal ativa (`whatsapp_exists`), foi removido da Meta (`phone_deleted`), é de outro seller da loja (`number_in_use`) ou de outra loja (`number_in_use_other_store`).	`{"error":"Este número já possui uma conta WhatsApp ativa. Exclua a conta do WhatsApp neste número antes de cadastrá-lo na plataforma.","kind":"whatsapp_exists"}`
409	A loja tem números de vários sellers e quem chama não é o seller dono (`kind: seller_required_for_number`). Entre com o usuário do seller.	`{"error":"Esta loja tem números de vários vendedores. Entre com o usuário do vendedor dono do número para cadastrá-lo, trocá-lo ou verificá-lo.","kind":"seller_required_for_number"}`
503	A plataforma não tem token da Meta válido configurado para cadastrar números (`kind: config_missing`).	`{"error":"Token de acesso da Meta inválido ou expirado. ...","kind":"config_missing"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O usuário não é um seller, o módulo de WhatsApp está desligado na loja (`module_disabled`) ou o cadastro do seller ainda está em análise (`vendor_pending_review`).	`{"error":"module_disabled","module":"whatsapp-commerce"}`
403	O usuário não tem o privilégio de seller `vendor_manage_whatsapp`.	`{"error":"insufficient vendor privileges","required":"vendor_manage_whatsapp"}`

2. Pedir o código

POST/api/v1/vendor/whatsapp/self-setup/request-codeSeller

Envia o código de verificação por SMS ou ligação

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (lojista). Veja Tokens.

Content-Typestringobrigatório

application/json.

Corpo da requisição

phone_number_idstringobrigatório

Id devolvido no passo 1. Precisa ser o número do próprio seller.

methodstringpadrão: SMS

SMSVOICE

Como receber o código.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/self-setup/request-code" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "109876543210987",
    "method": "SMS"
  }'

Resposta

200Código enviado

json

{
  "success": true
}

Campos da resposta

successboolean

Sempre true.

Erros

Status	Quando	Corpo de exemplo
403	`phone_number_id` ausente ou que não é o número deste seller.	`{"error":"Número não pertence a esta loja"}`
429	Intervalo mínimo ou bloqueio ativo (`kind: rate_limited`). `retry_after_seconds` diz quanto esperar e `method` qual método está limitado.	`{"error":"Aguarde 45 segundos para solicitar um novo código via SMS, ou tente outro método.","kind":"rate_limited","retry_after_seconds":45,"method":"SMS"}`
409	O número foi removido da Meta (`kind: phone_deleted`): refaça o passo 1.	`{"error":"Este número foi removido da Meta. Cadastre o número novamente em \"Adicionar número\".","kind":"phone_deleted"}`
503	Sem token da Meta configurado na plataforma (`kind: config_missing`).	`{"error":"...","kind":"config_missing"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O usuário não é um seller, o módulo de WhatsApp está desligado na loja (`module_disabled`) ou o cadastro do seller ainda está em análise (`vendor_pending_review`).	`{"error":"module_disabled","module":"whatsapp-commerce"}`
403	O usuário não tem o privilégio de seller `vendor_manage_whatsapp`.	`{"error":"insufficient vendor privileges","required":"vendor_manage_whatsapp"}`

3. Confirmar o código

POST/api/v1/vendor/whatsapp/self-setup/verifySeller

Valida o código e conclui o registro do número

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (lojista). Veja Tokens.

Content-Typestringobrigatório

application/json.

Corpo da requisição

phone_number_idstringobrigatório

Id do passo 1.

codestringobrigatório

Código de 6 dígitos recebido.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/self-setup/verify" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "109876543210987",
    "code": "123456"
  }'

Resposta

200Número ativo

json

{
  "success": true,
  "two_step_pin": "482913",
  "register_ok": true,
  "data": {
    "two_step_pin": "482913",
    "register_ok": true
  }
}

Campos da resposta

successboolean

Sempre true.

two_step_pinstring

PIN de duas etapas gerado. Fica guardado e volta em Ler a credencial.

register_okboolean

false se a Meta recusou o registro na Cloud API por um motivo que não é "já registrado". O número pode então não receber mensagens.

dataobject

Cópia de two_step_pin e register_ok.

route_pendingboolean

Só aparece, com true, se o número já entrega mensagens a outro destino.

Erros

Status	Quando	Corpo de exemplo
403	`code` ausente, `phone_number_id` ausente ou que não é do seller.	`{"error":"Número não pertence a esta loja ou código ausente"}`
500	Código errado ou expirado: o erro da Meta sai como `500` com a mensagem dela em `error`.	`{"error":"meta 400: ..."}`
503	Sem token da Meta configurado na plataforma (`kind: config_missing`).	`{"error":"...","kind":"config_missing"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O usuário não é um seller, o módulo de WhatsApp está desligado na loja (`module_disabled`) ou o cadastro do seller ainda está em análise (`vendor_pending_review`).	`{"error":"module_disabled","module":"whatsapp-commerce"}`
403	O usuário não tem o privilégio de seller `vendor_manage_whatsapp`.	`{"error":"insufficient vendor privileges","required":"vendor_manage_whatsapp"}`

Conferir o status

GET/api/v1/vendor/whatsapp/self-setup/statusSeller

Retorna o nome verificado e a situação do código do número

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário seller (lojista). Veja Tokens.

Parâmetros de consulta

phone_number_idstringobrigatório

Id do número. Precisa ser o do próprio seller.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/whatsapp/self-setup/status?phone_number_id=109876543210987" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Estado do número

json

{
  "success": true,
  "data": {
    "phone_number_id": "109876543210987",
    "verified_name": "Casa do Pão Quente",
    "display_phone_number": "+55 41 99999-0000",
    "code_verification_status": "VERIFIED"
  }
}

Campos da resposta

successboolean

Sempre true.

dataobject

Estado lido na Meta.

phone_number_idstring

Id do número.

verified_namestring

Nome verificado pela Meta (vazio se ainda não aprovado).

display_phone_numberstring

Telefone como a Meta o mostra.

code_verification_statusstring

Situação do código, como VERIFIED ou NOT_VERIFIED, conforme a Meta.

Erros

Status	Quando	Corpo de exemplo
403	`phone_number_id` ausente ou que não é deste seller.	`{"error":"Número não pertence a esta loja"}`
503	Sem token da Meta configurado na plataforma (`kind: config_missing`).	`{"error":"...","kind":"config_missing"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O usuário não é um seller, o módulo de WhatsApp está desligado na loja (`module_disabled`) ou o cadastro do seller ainda está em análise (`vendor_pending_review`).	`{"error":"module_disabled","module":"whatsapp-commerce"}`
403	O usuário não tem o privilégio de seller `vendor_manage_whatsapp`.	`{"error":"insufficient vendor privileges","required":"vendor_manage_whatsapp"}`