Introducción

Enviar un mensaje de WhatsApp a un número de teléfono no válido o con un formato incorrecto es un error silencioso. No aparece ningún mensaje de error al introducir el número, simplemente el mensaje nunca llega a su destino. Antes de enviar ese primer mensaje, vale la pena dedicar un momento a comprobar el número con el que estás trabajando.

En este tutorial, aprenderás a utilizar la API de Identity Insights para comprobar dos indicadores clave —el formato y el operador actual— antes de enviar un mensaje de WhatsApp. Primero analizaremos la solución mediante comandos cURL y un entorno de pruebas; a continuación, veremos cómo puedes configurar el servidor MCP de Vonage Tooling para enviar un mensaje de WhatsApp a un número de teléfono validado.

Requisitos previos

·       Una aplicación de Vonage generada con una clave privada (para la autenticación JWT)

·       curl está disponible en tu terminal

· Una Account de desarrollador de Vonage

Espacio de experimentación con datos sobre identidad

Antes de lanzarte a enviar mensajes por WhatsApp, puedes explorar la API. Abre el Identity Insights Playground en el panel de control de Vonage, introduce cualquier número de teléfono, selecciona format y current_carrier, y verás la respuesta en tiempo real. También hay un modo de demostración con Numbers predefinidos si quieres explorar la API sin utilizar un número real.

Getting Started with Identity Insights

Formato

La función de análisis de formato comprueba si un número de teléfono es válido desde el punto de vista estructural. Si cumple con las normas internacionales de numeración, devuelve:

• is_format_valid: un valor booleano que indica si el número podría asignarse de forma realista a un abonado

• number_international: el número en formato E.164 (p. ej., +447700900000)

• number_national: la versión adaptada al formato local

• country_code_iso2 y country_name

•  time_zones: útil para programar mensajes a la hora local adecuada

Esta es la información que hay que tener en cuenta antes de almacenar cualquier número de teléfono o realizar cualquier acción con él. Normaliza los datos introducidos a un formato E.164 coherente.

Operador actual

La información sobre el operador actual te indica a qué red está asignado actualmente el número de teléfono, junto con el tipo de red. Los campos importantes son:

• name: el nombre del operador (p. ej., EE, Verizon, Deutsche Telekom)

• network_type: MÓVIL, FIJO, VIRTUAL, etc.

• country_code: el país en el que está registrado el número

Si network_type el resultado no es MOBILE, el número no puede recibir mensajes de WhatsApp. Guardar un número de teléfono fijo o de VoIP e intentar enviarle un mensaje de WhatsApp es un error seguro, y totalmente evitable.

Validar un número de teléfono

Ambos datos se pueden solicitar en una sola llamada a la API. Ejecuta esto desde tu terminal. Sustituye $JWT por un JWT válido generado a partir de las credenciales de tu aplicación de Vonage, y sustituya el número de teléfono por el que desee 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": {}

    }

  }'

Si tu respuesta es correcta, tendrá el aspecto del fragmento de código que aparece a continuación. Si is_format_valid es verdadero y network_type es MOBILE, ya puedes continuar.

{

  "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" }

    }

  }

}

Entorno de pruebas de la Messages API

Tenemos un entorno de pruebas de la Messages API donde puedes configurar diversos canales, como Viber, Facebook Messenger, Instagram y, por último, pero no menos importante, WhatsApp. Anteriormente he creado dos tutoriales en JavaScript y Node.js en los que se muestra cómo enviar un mensaje de WhatsApp con Node.js y cómo crear una aplicación de recordatorios de eventos para WhatsApp. Además de estos, disponemos de tutoriales para diferentes lenguajes de programación que muestran cómo enviar un mensaje de prueba a través del entorno de pruebas de la Messages API.

Añade tu número a la lista de números permitidos

Al abrir el entorno de pruebas de la Messages API, verás la sección de WhatsApp con un código QR y una frase de acceso. Puedes escanear el código QR o enviar manualmente un mensaje de WhatsApp al +1 415-738-6102 con las tres palabras que aparecen en el panel de control. Una vez incluido en la lista de permitidos, podrás enviar y recibir mensajes de prueba de WhatsApp a través del entorno de pruebas.

Enviar un mensaje de prueba por WhatsApp

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"

  }'

Sustituir YOUR_API_KEY, YOUR_API_SECRET, y YOUR_ALLOWLISTED_NUMBER por tus valores reales. El número de teléfono «de destino» debe estar en formato E.164 sin el signo «+» inicial (p. ej., 447700900000).

Nota: el dominio del punto final del entorno de pruebas, messages-sandbox.nexmo.com, es diferente del punto final estándar de la Messages API. Comprueba bien tu URL base al cambiar entre el entorno de pruebas y el de producción.

Validar un número y enviar un mensaje de WhatsApp utilizando el servidor MCP de Vonage Tooling

Te he mostrado dos comandos cURL distintos para, primero, validar el número de teléfono y, después, enviar el mensaje de WhatsApp. Puedes utilizar el servidor MCP de Vonage Tooling para validar un número y enviar un mensaje de WhatsApp mediante indicaciones en lenguaje natural en un agente de IA como Claude o Gemini dentro de Google Antigravity.

Configurar el servidor MCP

Instálalo de forma global:

npm install -g @vonage/vonage-mcp-server-api-bindings

O bien, ejecútalo directamente con npx:

npx @vonage/vonage-mcp-server-api-bindings

A continuación, añádelo al archivo de configuración de tu cliente MCP. Ubicaciones por cliente:

· Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %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"

      }

    }

  }

}

Nota: VONAGE_PRIVATE_KEY64 es tu archivo de clave privada codificado en base64. En macOS/Linux, puedes generarlo con base64 -i private.key | tr -d '\n' . Quería copiarlo al portapapeles mientras lo hacía en GitHub Codespaces, así que utilicé el siguiente comando: base64 -i private.key | tr -d '\n' > b64_key.txt && code b64_key.txt para copiarlo en un nuevo archivo txt, pero también puedes usar | pbcopy en macOS para copiarlo al portapapeles.

Validar y enviar con un mensaje de aviso

Una vez que el servidor esté en funcionamiento, puedes pedirle a tu agente de IA que valide un número y envíe un mensaje de WhatsApp con una sola orden. El agente llamará primero a la API de Identity Insights, comprobará el resultado y solo procederá al envío si el número supera la validación.

Puedes hablar con tu LLM introduciendo una indicación del tipo:

«Utiliza la API de Number Insight para validar el número +447700900000. Comprueba que is_format_valid sea «true» y que network_type sea «MOBILE». Si ambos criterios se cumplen, envía un mensaje de texto por WhatsApp a ese número con el texto «¡Hola desde Vonage!».

Conclusión

Enhorabuena, has llegado al final de este tutorial. Ahora ya sabes cómo validar un número de teléfono antes de enviar un mensaje de WhatsApp, ya sea a través del entorno de pruebas de la Messages API utilizando cURL o a través del servidor MCP. 

Para saber más

• Descripción general de la API de Identity Insights

• Referencia de la API de Identity Insights

• Conceptos básicos del entorno de pruebas de la Messages API

• Entender la mensajería de WhatsApp

• ¿Qué es el formato E.164?

• Enviar un mensaje de WhatsApp con Node.js

• Crea una aplicación de recordatorios de eventos para WhatsApp