){kind=small}
Valide números de telefone antes de enviar mensagens pelo WhatsApp com a Vonage
Tempo de leitura: 7 minutos
Enviar uma mensagem pelo WhatsApp para um número de telefone inválido ou com formatação incorreta é uma falha silenciosa. Não há nenhum erro no momento da digitação, apenas uma mensagem que nunca chega ao destinatário. Antes de enviar essa primeira mensagem, vale a pena reservar um momento para verificar o número que você está usando.
Neste tutorial, você aprenderá a usar a API do Identity Insights para verificar dois sinais importantes — o formato e a operadora atual — antes de enviar uma mensagem pelo WhatsApp. Primeiro, exploraremos a solução usando comandos cURL e um ambiente de sandbox; depois, veremos como você pode configurar o servidor MCP do Vonage Tooling para enviar uma mensagem pelo WhatsApp a um número de telefone validado.
· Um aplicativo Vonage gerado com uma chave privada (para autenticação JWT)
· o `curl` está disponível no seu terminal
· A Account de desenvolvedor da Vonage
Antes de começar a enviar mensagens pelo WhatsApp, você pode explorar a API. Abra o Identity Insights Playground no Painel da Vonage, digite qualquer número de telefone, selecione format e current_carrier, e veja a resposta em tempo real. Há também um modo de demonstração com números predefinidos, caso você queira explorar sem usar um número ativo.
Getting Started with Identity Insights
A verificação de formato verifica se um número de telefone é estruturalmente válido. Se ele estiver em conformidade com os padrões internacionais de numeração, ela retorna:
is_format_valid: um valor booleano que indica se o número poderia, de fato, ser atribuído a um assinantenumber_international: o número no formato E.164 (por exemplo, +447700900000)number_national: a versão formatada para o mercado localcountry_code_iso2ecountry_nametime_zones: útil para agendar mensagens na hora local correta
Essa é a informação essencial a ser considerada antes de armazenar ou realizar qualquer ação relacionada a um número de telefone. Ela normaliza os dados de entrada para um formato E.164 consistente.
A informação sobre a operadora atual indica a qual rede o número de telefone está atribuído no momento, juntamente com o tipo de rede. Os campos importantes são:
name: o nome da operadora (por exemplo, EE, Verizon, Deutsche Telekom)network_type: CELULAR, TELEFONE FIXO, VIRTUAL, etc.country_code: o país em que o número está registrado
Se network_type o resultado for diferente de MOBILE, o número não pode receber mensagens do WhatsApp. Salvar um número de telefone fixo ou de VoIP e, em seguida, tentar enviar uma mensagem do WhatsApp para ele é uma falha garantida, e que é totalmente evitável.
Ambas as informações podem ser solicitadas em uma única chamada de API. Execute este comando no seu terminal. Substitua $JWT por um JWT válido gerado a partir das credenciais do seu aplicativo Vonagee substitua o número de telefone pelo que você deseja validar.
curl -X POST https://api-eu.vonage.com/identity-insights/v1/requests \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+447700900000",
"purpose": "FraudPreventionAndDetection",
"insights": {
"format": {},
"current_carrier": {}
}
}'Se sua resposta for bem-sucedida, ela terá a aparência do trecho de código abaixo. Se is_format_valid for verdadeiro e network_type for MOBILE, você pode prosseguir.
{
"request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"insights": {
"format": {
"country_code_iso2": "GB",
"country_name": "United Kingdom",
"country_prefix": "44",
"offline_location": "United Kingdom",
"time_zones": ["Europe/London"],
"number_international": "+447700900000",
"number_national": "07700 900000",
"is_format_valid": true,
"status": { "code": "OK", "message": "Success" }
},
"current_carrier": {
"name": "EE",
"network_type": "MOBILE",
"country_code": "GB",
"network_code": "23430",
"status": { "code": "OK", "message": "Success" }
}
}
}
Temos uma Sandbox da Messages API onde você pode configurar diversos canais, incluindo Viber, Facebook Messenger, Instagram e, por último, mas não menos importante, o WhatsApp. Já criei dois tutoriais em JavaScript e Node.js mostrando como enviar uma mensagem pelo WhatsApp com o Node.js e como criar um aplicativo de lembretes de eventos pelo WhatsApp. Além desses, temos tutoriais para diferentes linguagens de programação que mostram como enviar uma mensagem de teste por meio do Sandbox da Messages API.
Ao abrir o Sandbox da Messages API, você verá a seção do WhatsApp com um código QR e uma senha. Você pode escanear o código QR ou enviar manualmente uma mensagem pelo WhatsApp para +1 415-738-6102 com as três palavras exibidas no painel. Depois de ser adicionado à lista de permissões, você poderá enviar e receber mensagens de teste pelo WhatsApp por meio do sandbox.
curl -X POST https://messages-sandbox.nexmo.com/v1/messages \
-u 'YOUR_API_KEY:YOUR_API_SECRET' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"from": "14157386102",
"to": "YOUR_ALLOWLISTED_NUMBER",
"message_type": "text",
"text": "This is a WhatsApp Message sent from the Messages API",
"channel": "whatsapp"
}'Substituir YOUR_API_KEY, YOUR_API_SECRET, e YOUR_ALLOWLISTED_NUMBER pelos seus valores reais. O número de telefone de destino deve estar no formato E.164, sem o sinal de mais (+) no início (por exemplo, 447700900000).
Observação: o domínio do endpoint do ambiente de teste, messages-sandbox.nexmo.com, é diferente do endpoint padrão da Messages API. Verifique novamente sua URL base ao alternar entre o ambiente de teste e o de produção.
Abra sua página de configurações da API para acessar sua chave e seu segredo da API da Vonage, ambos exibidos conforme mostrado na captura de tela abaixo. A chave da API está localizada na parte superior da página e, para acessar seu segredo da API, consulte a subseção “Segredo da Account”.
Observação: caso você não se lembre do seu segredo de API criado anteriormente, clique em “+ Criar novo segredo” e guarde-o em um local seguro.
Mostrei a vocês dois comandos cURL distintos: um para validar o número de telefone e outro para enviar a mensagem pelo WhatsApp. Vocês podem usar o Servidor MCP do Vonage Tooling para validar um número e enviar uma mensagem pelo WhatsApp por meio de comandos em linguagem natural em um agente de IA como o Claude ou o Gemini no Google Antigravity.
Instale globalmente:
npm install -g @vonage/vonage-mcp-server-api-bindingsOu execute diretamente com o npx:
npx @vonage/vonage-mcp-server-api-bindingsEm seguida, adicione-o ao seu arquivo de configuração do cliente MCP. Locais por cliente:
· Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows)
· Google Antigravity: ~/.config/antigravity/mcp_config.json
"mcpServers": {
"vonage": {
"command": "npx",
"args": ["-y", "@vonage/vonage-mcp-server-api-bindings"],
"env": {
"VONAGE_API_KEY": "your_api_key",
"VONAGE_API_SECRET": "your_api_secret",
"VONAGE_APPLICATION_ID": "your_application_id",
"VONAGE_PRIVATE_KEY64": "your_base64_encoded_private_key",
"VONAGE_WHATSAPP_NUMBER": "14157386102"
}
}
}
}Observação: VONAGE_PRIVATE_KEY64 é o seu arquivo de chave privada codificado em base64. No macOS/Linux, você pode gerá-lo com base64 -i private.key | tr -d '\n' . Eu queria copiá-la para a área de transferência enquanto fazia isso no GitHub Codespaces e usei o seguinte comando: base64 -i private.key | tr -d '\n' > b64_key.txt && code b64_key.txt para copiá-lo para um novo arquivo .txt, mas você pode usar | pbcopy no macOS para copiá-lo para a área de transferência.
Assim que o servidor estiver em funcionamento, você poderá solicitar ao seu agente de IA que valide um número e envie uma mensagem pelo WhatsApp com um único comando. O agente chamará primeiro a Number Insight API, verificará o resultado e só prosseguirá com o envio se o número for aprovado na validação.
Você pode interagir com o seu LLM digitando uma solicitação como:
“Use a Number Insight API para validar o número +447700900000. Verifique se is_format_valid é verdadeiro e se network_type é MOBILE. Se ambos forem válidos, envie uma mensagem de texto pelo WhatsApp para esse número dizendo “Olá, da Vonage!”
Parabéns, você chegou ao final deste tutorial. Agora você já sabe como validar um número de telefone antes de enviar uma mensagem pelo WhatsApp, seja por meio do Sandbox da Messages API usando o cURL, seja por meio do MCP Server.
Tem alguma dúvida ou quer compartilhar o que está criando?
Inscreva-se no Boletim Informativo para Desenvolvedores
Siga-nos no X (antigo Twitter) para ficar por dentro das novidades
Assista aos tutoriais no nosso canal do YouTube
Conecte-se conosco na página de desenvolvedores da Vonage no LinkedIn
Fique conectado e acompanhe as últimas notícias, dicas e eventos para desenvolvedores.