Como registrar o número na Cloud API: PIN de duas etapas e erros comuns

Atualizado em 28/10/2026

Para registrar o número na Cloud API, você faz POST /{phone-number-id}/register com messaging_product: "whatsapp" e um pin de 6 dígitos. Se o número ainda não tem verificação em duas etapas, esse PIN passa a ser o PIN dele; se já tem, você precisa informar o PIN atual, ou recebe o erro 133005. Sem esse registro, o número existe na sua conta, mas não envia nem recebe mensagens pela API.

Este guia mostra a ordem certa (verificar, registrar, conferir), o que o PIN faz, os limites de tentativas, o deregister e uma tabela com os erros de registro da documentação da Meta.

Onde o registro entra no processo

Colocar um número na Cloud API tem três etapas que costumam ser confundidas:

Etapa	O que comprova	Chamada
Adicionar o número	Que ele pertence à sua conta do WhatsApp Business	Feito no WhatsApp Manager ou no cadastro incorporado
Verificar o número	Que você tem acesso ao telefone (código por SMS ou ligação)	POST /{id}/request_code e POST /{id}/verify_code
Registrar o número	Que ele deve operar na Cloud API, com PIN de duas etapas	POST /{id}/register

Se você usa o cadastro incorporado de um provedor, parte dessas etapas acontece na própria tela de cadastro; mesmo assim, vale saber o que cada uma faz para entender os erros deste artigo. Antes de começar, confira os requisitos do número em como liberar um número que já está no WhatsApp.

Passo 1: verificar o número (se ainda não estiver)

Pela página de números de telefone da Meta, primeiro consulte o status de verificação:

curl "https://graph.facebook.com/v26.0/PHONE_NUMBER_ID?fields=code_verification_status,display_phone_number,verified_name" \
  -H "Authorization: Bearer $TOKEN"

Se code_verification_status não estiver como VERIFIED, peça o código. code_method aceita SMS ou VOICE:

curl -X POST "https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/request_code" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "code_method": "SMS", "language": "pt_BR" }'

E confirme com o código recebido:

curl -X POST "https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/verify_code" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

Se o número já estiver verificado, o request_code devolve HTTP 400 com o erro 136024. Por isso vale checar o status antes.

Quer testar enquanto lê? Crie sua conta na Vectalk e envie a primeira mensagem pela API oficial. Criar conta grátis →

Passo 2: registrar com o PIN

A chamada de registro, segundo a documentação de registro da Meta:

curl -X POST "https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/register" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "pin": "482915"
  }'

Parâmetros:

• messaging_product (obrigatório): sempre "whatsapp".
• pin (obrigatório): 6 dígitos. Se a verificação em duas etapas já está ativa, use o PIN existente. Se não está, o valor enviado vira o PIN do número.
• data_localization_region (opcional): código de país ISO 3166 de 2 letras para ativar o armazenamento local de dados. Não dá para desativar ou trocar diretamente depois: é preciso cancelar o registro e registrar de novo.

O token precisa das permissões whatsapp_business_management e whatsapp_business_messaging. Para produção, use um token permanente de usuário do sistema.

O que é o PIN de duas etapas

O PIN de verificação em duas etapas é uma camada extra de segurança: depois de definido, todo novo registro do número exige o PIN atual. Ele é diferente do código de 6 dígitos que chega por SMS. O código de SMS prova que você tem o chip; o PIN prova que você é o dono do registro.

Pela página de verificação em duas etapas, você também pode definir o PIN com POST /{phone-number-id} e o corpo {"pin": "123456"}. Não existe endpoint para desativar a verificação em duas etapas. Para trocar o PIN pelo WhatsApp Manager, abra as configurações do número, aba Verificação em duas etapas, e clique em Alterar PIN.

Guarde o PIN num cofre de senhas da empresa, não na cabeça de quem fez o cadastro. Ele será pedido de novo em qualquer novo registro, inclusive em troca de provedor. Mais sobre o assunto em segurança da conta business no WhatsApp.

Uma mudança em andamento: a Meta informa que está descontinuando gradualmente o PIN de 6 dígitos para números elegíveis da Cloud API. Nos números elegíveis, a aba de verificação em duas etapas some do WhatsApp Manager; se ela ainda aparece, o número ainda não é elegível. Acompanhe a página oficial antes de automatizar esse passo.

Passo 3: conferir o status

Depois do registro, consulte o número:

curl "https://graph.facebook.com/v26.0/PHONE_NUMBER_ID?fields=status,code_verification_status,name_status,quality_rating" \
  -H "Authorization: Bearer $TOKEN"

O que olhar:

• status: precisa estar CONNECTED para enviar e receber pela API.
• code_verification_status: VERIFIED.
• name_status: situação do nome de exibição (APPROVED, AVAILABLE_WITHOUT_REVIEW, DECLINED, EXPIRED, PENDING_REVIEW ou NONE). Veja nome de exibição na API.
• quality_rating: qualidade do número.

Limites de tentativas

Registro e cancelamento de registro têm limite: 10 requisições de cada por número em uma janela móvel de 72 horas. Passou disso, a API devolve 133016 e bloqueia a ação pelas próximas 72 horas. Por isso, não coloque o register dentro de um loop de retry automático. Se falhar, leia o erro, corrija a causa e só então tente de novo.

Erros de registro e como resolver

Os códigos abaixo estão na tabela de erros da Cloud API, exceto o 136024, que vem da página de números de telefone:

Código	Significado	O que fazer
133000	Uma tentativa anterior de cancelar o registro falhou	Cancele o registro de novo antes de registrar
133004	Servidor temporariamente indisponível	Veja a página de status da plataforma e o campo details antes de repetir
133005	PIN de duas etapas incorreto	Use o PIN atual ou troque o PIN no WhatsApp Manager e registre com o novo
133006	O número precisa ser verificado antes do registro	Faça request_code e verify_code
133008	Tentativas demais de PIN para este número	Espere o tempo indicado no campo details
133009	PIN digitado rápido demais	Confira o details antes de tentar de novo
133010	Número não registrado na plataforma	Registre o número antes de enviar mensagens
133015	O número foi excluído há pouco e a exclusão ainda não terminou	Espere 5 minutos e tente de novo
133016	Tentativas demais de registro ou cancelamento em pouco tempo	Espere o fim do bloqueio de 72 horas
136024	O número já está verificado (no request_code)	Pule para o registro

Os casos mais frequentes na prática:

133010 ao enviar mensagem. O número foi adicionado e até verificado, mas o register nunca foi chamado. É comum em números conectados manualmente ou em testes. A solução é registrar.

133005 em troca de provedor. O número veio de outra plataforma com verificação em duas etapas ativa, e ninguém sabe o PIN. Peça o PIN ao provedor anterior ou troque o PIN no WhatsApp Manager, se você tiver acesso à conta, e registre com o novo valor. Veja como trocar de provedor sem perder o número.

131031 durante o registro. Esse código costuma indicar conta restrita por violação de política, mas a Meta também cita como causa dados da requisição que não conferem com a conta, como um PIN de duas etapas incorreto. Se a conta não tem restrição, confira o PIN.

Quando registrar de novo

Pela documentação de registro, o registro não acontece só uma vez:

• Ao implementar a API pela primeira vez, quando a Meta exige a verificação em duas etapas.
• Depois de mudar o nome de exibição: quando o novo nome é aprovado (o webhook phone_number_name_update confirma), registre o número de novo. Registrar antes da aprovação não tem efeito.
• Ao trocar ou desativar o armazenamento local (data_localization_region): cancele o registro e registre outra vez.
• Em migração do On-Premises para a Cloud API, que tem passos extras antes do registro.

Cancelar o registro (deregister)

curl -X POST "https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/deregister" \
  -H "Authorization: Bearer $TOKEN"

O que acontece, segundo a Meta: o número deixa de funcionar na Cloud API e o armazenamento local é desativado, se estava ligado. O número e o histórico de mensagens não são apagados. Duas restrições importantes: não é possível cancelar o registro de um número usado ao mesmo tempo na Cloud API e no app WhatsApp Business (coexistência), e sem a permissão whatsapp_business_management a chamada devolve o erro 200. Lembre que o cancelamento também tem limite próprio de 10 tentativas por número em 72 horas.

Como fazer isso com a Vectalk

Na Vectalk, as rotas de número usam o token de instância, que já identifica o número, então você não precisa informar o phone-number-id. A API da Vectalk tem POST https://apis.vectalk.com.br/api/phone-numbers/register com o pin no corpo, POST /phone-numbers/deregister, POST /phone-numbers/request-code, POST /phone-numbers/verify-code e GET /phone-numbers para consultar status, qualidade e nível de throughput. A Vectalk também oferece coexistência, para o número continuar no app WhatsApp Business enquanto usa a API; detalhes em coexistência no WhatsApp. Crie sua conta em apps.vectalk.com.br/register.

Com o número registrado, os próximos passos são validar a assinatura do webhook e respeitar o throughput e o rate limit. A visão completa da plataforma está no guia da API oficial do WhatsApp.

Perguntas frequentes

O PIN de duas etapas é o mesmo código que chega por SMS?

Não. O código de SMS ou ligação verifica que você tem acesso ao telefone. O PIN de 6 dígitos é definido por você e passa a ser exigido em todo novo registro do número.

Esqueci o PIN. Como registro o número?

Troque o PIN no WhatsApp Manager, na aba de verificação em duas etapas do número, e registre com o novo valor. Não existe endpoint para desativar a verificação em duas etapas.

Quantas vezes posso tentar registrar?

Até 10 registros e 10 cancelamentos por número em 72 horas. Acima disso, a API devolve 133016 e bloqueia a ação por 72 horas.

Cancelar o registro apaga o número ou as mensagens?

Não. O número só deixa de funcionar na Cloud API. O número e o histórico continuam, e você pode registrar de novo depois.

Preciso registrar de novo depois de mudar o nome de exibição?

Sim. Depois que o novo nome for aprovado, chame o register outra vez. Registrar antes da aprovação não tem efeito.

---

Fontes oficiais consultadas em 28/10/2026: Register a phone number (Meta), Two-step verification (Meta), Phone numbers (Meta), Códigos de erro (Meta), Registrar número na API da Vectalk.