Números Cloud API Agora São Registrados Automaticamente no Embedded Signup
Resumo: quando você conecta um número pelo Embedded Signup, o PipesBot agora termina o serviço. Se o número é novo na Cloud API, a gente registra ele na Meta, resolve o PIN de verificação em duas etapas e só marca o número como ativo depois que ele está registrado ou conectado com Coexistence. Seu cliente consegue fazer tudo isso pelo link público de onboarding, sem conta no PipesBot.
O problema que corrigimos
A maioria dos números conectados ao PipesBot usa Coexistence: o número continua no app WhatsApp Business do celular e também funciona pela API. A Meta diz que esses números não devem ser registrados de novo, então nosso fluxo de signup nunca chamava o endpoint de registro da Meta.
Só que o mesmo diálogo da Meta também permite conectar um número Cloud API “puro”, que não está no app WhatsApp Business. Esses números precisam de uma chamada a mais, POST /{phone-number-id}/register, antes que o WhatsApp entregue qualquer coisa para eles. A gente pulava essa etapa. O número aparecia como Active no dashboard, a WABA estava inscrita nos webhooks, e nada funcionava: nenhuma mensagem chegava, e os envios falhavam com o erro 133010 da Meta (conta não registrada).
É o tipo de falha que custa um ticket de suporte e uma tarde inteira. Então fechamos esse buraco.
O que acontece agora
Quando o Embedded Signup termina, o PipesBot consulta o número na Meta antes de considerá-lo pronto:
| O que a Meta informa | O que o PipesBot faz | Status do número |
|---|---|---|
| O número está no app WhatsApp Business (Coexistence) | Nada. Registrar seria um erro | Ativo |
| O número já está registrado na Cloud API | Nada | Ativo |
| O número não está registrado | Chama register com um PIN de 6 dígitos gerado | Ativo quando a Meta aceitar |
O PIN gerado vira o PIN de verificação em duas etapas do número. Você, dono do App, consegue ver o PIN no dashboard (Numbers → Reveal PIN). Quem fez o signup nunca vê.
Quando o número já tem PIN
Se a verificação em duas etapas já está ligada, a Meta recusa o PIN gerado com o erro 133005. Em vez de falhar, o fluxo pede o PIN atual:
- Digite o PIN de 6 dígitos e clique em Finish.
- Não sabe o PIN? Abra “I don’t know the PIN” para ver como desligar a verificação em duas etapas no WhatsApp Manager e depois clique em “I turned it off, try again”. O PipesBot registra o número com um PIN novo.
A Meta permite 10 tentativas de registro por número a cada 72 horas. Passou disso, o registro fica bloqueado por 72 horas (133016). O PipesBot conta as tentativas do nosso lado, mostra quantas sobram e para de chamar a Meta antes de você queimar o limite. Muitos PINs errados seguidos (133008, 133009) pausam as tentativas por uma hora, e um número que acabou de ser excluído (133015) recebe um “tente de novo em 5 minutos” em vez de um erro.
Funciona no link de onboarding também
Muitos de vocês não conectam os números pessoalmente. Vocês mandam um link de signup para o cliente, e ele passa pelo fluxo da Meta sozinho. Essa pessoa não tem login no PipesBot, então um “termine isso no dashboard” seria um beco sem saída.
A página pública de onboarding agora cuida do registro do início ao fim:
- Se precisar de PIN, a própria página pede.
- O progresso fica guardado num ticket assinado na URL, válido por 7 dias. Seu cliente pode recarregar a página ou voltar amanhã sem refazer o Embedded Signup.
- Se algo falhar, a tela de erro tenta de novo a partir de onde parou, em vez de reiniciar o signup todo.
Menos estados confusos para o seu código
Duas mudanças menores vêm junto:
- Número ainda não registrado fica inativo. Enviar a partir dele retorna
409 Number registration pendingdo PipesBot, em vez de um erro obscuro da Meta. - Cobrança e o webhook
number.onboardedesperam o número estar utilizável. Você não paga o add-on BYON, e seu sistema não recebe o aviso de número pronto, até ele estar registrado ou conectado com Coexistence.
Também nesta rodada: Embedded Signup v4
Em setembro migramos o dashboard, o link de onboarding e os fluxos de admin para o Embedded Signup v4 da Meta. No caminho, garantimos que todos os fluxos mantêm a opção de Coexistence ligada, então um número que já está no app WhatsApp Business recebe a opção “conectar o app existente” em vez de ser recusado. Desde 3 de outubro o v4 é o único fluxo, sem flag de rollout por App.
Experimente
Conecte um número pelo dashboard do PipesBot ou gere um link de signup pela API. A documentação do Embedded Signup cobre os dois caminhos. Se você está decidindo entre manter o app WhatsApp Business e fazer a migração completa, leia antes o guia de Coexistence.