Como escolher um número virtual para a WhatsApp Business API

Um número usado na WhatsApp Business API é um remetente: antes de escolher, decida se você quer provisionar um número brasileiro pelo fluxo disponível ou conectar um número que já está registrado na Meta. Na Tyxter, os dois caminhos têm operações e responsabilidades diferentes; veja o fluxo completo na página de números de telefone.

A expressão “número virtual” costuma esconder decisões importantes. Para uma integração, não basta receber um identificador: o número precisa estar no ambiente certo, ter uma ligação válida com a conta de WhatsApp quando o caso exigir e ser observado como um recurso cujo estado pode mudar. Planejar essas etapas antes de automatizar o envio reduz tentativas contra a rota errada e facilita explicar para a equipe quem conclui cada parte.

Qual é a diferença entre provisionar e conectar um número?

POST /v1/phone-numbers/provision solicita o provisionamento pela Salvy e devolve um recurso de número inicialmente com status requested; o provisionamento continua de forma assíncrona. Consulte o status do recurso e avance depois que esse processo estiver concluído. Mesmo um número provisionado não é registrado automaticamente na Meta: um registro de produção pode estar ativo no nível da operadora e ainda não ter um meta_phone_number_id; a conclusão do registro é feita por um proprietário ou administrador no fluxo de WhatsApp Embedded Signup do dashboard.

POST /v1/phone-numbers/connect, por sua vez, é o caminho BYON, de bring your own number. Use-o quando o número já está registrado na Meta e você pode informar o identificador de telefone da Meta. Ele não é uma rota para registrar um número recém-provisionado. Se um número E.164 corresponde a um registro Salvy ainda sem registro na Meta, a resposta documentada é meta_registration_required; o encaminhamento é o fluxo de Embedded Signup, não uma sequência improvisada de rotas de verificação.

Essa origem também afeta como pensar na continuidade do remetente. Um número BYON continua sob controle do cliente. Um número Salvy é um aluguel gerenciado pela Tyxter, sem garantia pública de portabilidade. Antes de fixar um número em campanhas, integrações e documentação interna, registre qual desses modelos a equipe escolheu e quem é o responsável por concluir a conexão.

Como validar o ambiente antes de escolher um número?

Comece pelo sandbox quando o objetivo é integrar e testar a aplicação. A chave de sandbox só opera no ambiente sandbox, e a chave de produção só opera no ambiente de produção. No sandbox, chame a prontidão antes de enviar mensagens: o retorno informa o remetente padrão e se o recurso de envio está disponível. Não invente um sender_id quando esse retorno ainda não o fornece.

import { Tyxter } from '@tyxter/sdk-js';

const apiKey = process.env.TYXTER_API_KEY;
if (!apiKey?.startsWith('tx_sandbox_')) throw new Error('Sandbox API key required');

const tyxter = new Tyxter({ apiKey });
const ready = await tyxter.sandbox.quickstart();
const senderId = ready.sender.default_sender_id;

if (!senderId || !ready.capabilities.send_outbound_messages) {
  throw new Error('Sandbox sender is not ready');
}

O sandbox é uma simulação determinística para testar integrações. Ele não exige credenciais da Meta para o caminho de início rápido e nunca entrega mensagens a telefones reais. Por isso, ele é o lugar adequado para confirmar que sua aplicação preserva o message_id, o trace_id, os estados de mensagem e a verificação de webhooks, sem concluir que um número de sandbox está pronto para uma operação de produção.

Para cada mutação, gere uma chave de idempotência para a operação lógica e conserve-a se a mesma solicitação precisar de retry. O exemplo de envio no quickstart segue esse padrão: uma chave para o inbound simulado e outra para o envio são duas operações diferentes. Em uma tentativa repetida do mesmo provisionamento ou conexão, a chave deve permanecer estável junto com o mesmo payload.

O que acontece depois que um número é provisionado?

Depois de provisionar um número Salvy em produção, um proprietário ou administrador abre o Embedded Signup para concluir o registro do WhatsApp. No assistente da Meta, a documentação orienta escolher SMS, e o código de verificação aparece no dashboard depois que a Salvy o recebe. Quando o Embedded Signup termina com sucesso, a conexão passa a expor o telefone da Meta e o waba_id no recurso do número.

Não confunda essa etapa humana com uma chamada de leitura. Consultar GET /v1/phone-numbers/{phone_number_id} devolve o estado conhecido do recurso; essa leitura não chama a Meta. Campos de saúde como qualidade e tier carregam meta_health_synced_at, a marca da última leitura bem-sucedida da Meta. Um valor nulo nessa marca significa que esses dados ainda não foram lidos; uma marca antiga significa que os campos representam aquele momento observado.

Essa diferença importa para dashboards e automações. Em vez de transformar um campo desconhecido em “ruim” ou “aprovado”, mostre o estado e a marca de atualização. Da mesma forma, pending_name_review: null no sandbox indica ausência de uma observação pendente simulada, não uma aprovação de nome. A referência de números de telefone descreve os campos de listagem, leitura e ciclo de vida.

Como conectar um número que já existe na Meta?

Use o fluxo BYON somente com o número e o identificador de telefone da Meta já registrados. A conexão é um passo de integração, não uma tentativa de tomar controle de qualquer número digitado por um usuário. Mantenha o identificador retornado pela Meta associado ao ambiente correto e confirme que a chave usada tem o escopo necessário para a operação.

Depois da conexão, trate o recurso como fonte de verdade para o remetente que a aplicação usa. Liste os números do projeto e ambiente com GET /v1/phone-numbers e recupere o recurso específico quando for necessário observar seus dados atuais. Essas leituras não substituem a automação de envio nem precisam disparar um refresh externo em cada tela.

Quando precisar remover um remetente, leia o estado antes de agir. DELETE /v1/phone-numbers/{id} desconecta o número e é documentado como no-op idempotente quando o recurso já está em um estado terminal. A liberação é uma operação separada: POST /v1/phone-numbers/{id}/release aceita uma chave de idempotência e pode retornar enquanto um trabalhador conclui a liberação de um número Salvy. Planejar a diferença evita chamar “desconectado” de “liberado” no seu produto.

Como preparar o número para mensagens e webhooks?

O número é somente uma parte do envio. Para texto livre, o quickstart abre primeiro uma janela de serviço com uma mensagem inbound simulada e então envia a resposta. Uma resposta de envio bem-sucedida retorna 202 com status: accepted; esse status confirma que a API aceitou o trabalho, não que o destinatário já recebeu a mensagem. Consulte a mensagem ou receba os eventos de webhook para observar a evolução para estados como enviado, entregue ou lido.

Registre webhooks e valide a assinatura sobre o corpo bruto da requisição antes de fazer parse. Também deduplique por tyxter-webhook-id, porque um receiver pode receber nova tentativa. Esse cuidado vale para sandbox e produção: ele protege a aplicação contra processar duas vezes um evento cuja primeira resposta não foi reconhecida pelo transportador. O guia de webhooks explica a assinatura, os eventos e o tratamento de retries.

Quais são as dúvidas mais comuns sobre números para a API?

Provisionar um número já o registra na Meta?

Não. O provisionamento Salvy e o registro na Meta são etapas diferentes; o segundo é concluído pelo fluxo de Embedded Signup.

Posso usar connect para registrar um número Salvy recém-criado?

Não. connect é BYON e requer um número já registrado na Meta. Para um registro Salvy que precisa desse passo, siga o encaminhamento de Embedded Signup.

O sandbox envia mensagens para meu celular?

Não. O sandbox simula o envio e nunca alcança telefones reais.

Uma mensagem com status accepted já foi entregue?

Não. accepted informa que a API aceitou o envio; acompanhe a mensagem ou os webhooks para os estados posteriores.

Quando sua equipe tiver decidido a origem do número e o ambiente de teste, comece no sandbox e avance para a configuração da conta com esse plano registrado.