Introduction

L'envoi d'un message WhatsApp à un numéro de téléphone invalide ou mal formaté se solde par un échec silencieux. Aucune erreur n'apparaît au moment de la saisie, mais le message n'arrive tout simplement jamais à destination. Avant d'envoyer ce premier message, il est donc judicieux de prendre un instant pour vérifier le numéro que vous souhaitez utiliser.

Dans ce tutoriel, vous apprendrez à utiliser l' API Identity Insights pour vérifier deux indicateurs clés, le format et l'opérateur actuel, avant d'envoyer un message WhatsApp. Nous allons d'abord explorer la solution à l'aide de commandes cURL et d'un environnement sandbox, puis voir comment configurer le serveur MCP de Vonage Tooling pour envoyer un message WhatsApp à un numéro de téléphone validé.

Conditions préalables

·       Une application Vonage générée avec une clé privée (pour l'authentification JWT)

·       curl est disponible dans votre terminal

· A Account développeur Vonage

Espace d'exploration « Identity Insights »

Avant de vous lancer dans l'envoi de messages WhatsApp, vous pouvez découvrir l'API. Ouvrez l' Identity Insights Playground dans le tableau de bord Vonage, saisissez un numéro de téléphone, sélectionnez format et current_carrier, puis consultez la réponse en temps réel. Il existe également un mode démo avec des Numbers prédéfinis si vous souhaitez explorer l'API sans utiliser de numéro réel.

Getting Started with Identity Insights

Format

La vérification du format permet de s'assurer qu'un numéro de téléphone est valide d'un point de vue structurel. S'il est conforme aux normes internationales de numérotation, elle renvoie :

• is_format_valid: une valeur booléenne indiquant si le numéro pourrait, de manière réaliste, être attribué à un abonné

• number_international: le numéro au format E.164 (par exemple : +447700900000)

• number_national: la version adaptée au format local

• country_code_iso2 et country_name

•  time_zones: utile pour programmer l'envoi de messages à l'heure locale appropriée

Voici la procédure à suivre avant d'enregistrer ou d'utiliser un numéro de téléphone. Elle permet de normaliser les données saisies au format E.164, garantissant ainsi leur cohérence.

Opérateur actuel

La fiche d'information « current_carrier » vous indique à quel réseau le numéro de téléphone est actuellement attribué, ainsi que le type de réseau. Les champs importants sont les suivants :

• name: le nom de l'opérateur (par exemple, EE, Verizon, Deutsche Telekom)

• network_type: MOBILE, FIXE, VIRTUEL, etc.

• country_code: le pays dans lequel le numéro est enregistré

Si network_type le résultat n'est pas MOBILE, ce numéro ne peut pas recevoir de messages WhatsApp. Enregistrer un numéro de téléphone fixe ou VoIP puis tenter d’y envoyer un message WhatsApp est voué à l’échec, et c’est une erreur tout à fait évitable.

Valider un numéro de téléphone

Ces deux informations peuvent être demandées en un seul appel API. Exécutez cette commande depuis votre terminal. Remplacez $JWT par un JWT valide généré à partir des identifiants de votre application Vonage, et remplacez le numéro de téléphone par celui que vous souhaitez valider.

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 votre réponse est correcte, elle ressemblera à l'extrait de code ci-dessous. Si is_format_valid est vrai et network_type est MOBILE, vous pouvez continuer.

{

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

    }

  }

}

Bac à sable de la Messages API

Nous disposons d'un environnement de test pour la Messages API où vous pouvez configurer divers canaux, notamment Viber, Facebook Messenger, Instagram et, enfin et surtout, WhatsApp. J’ai déjà créé deux tutoriels en JavaScript et Node.js expliquant comment envoyer un message WhatsApp avec Node.js et comment développer une application de rappel d’événements sur WhatsApp. En plus de ceux-ci, nous proposons des tutoriels pour différents langages de programmation qui expliquent comment envoyer un message test via le bac à sable de la Messages API.

Ajoutez votre numéro à la liste blanche

Lorsque vous ouvrez le Sandbox de la Messages API, vous verrez la section WhatsApp avec un code QR et une phrase de passe. Vous pouvez soit scanner le code QR, soit envoyer manuellement un message WhatsApp au +1 415-738-6102 en indiquant les trois mots affichés sur le tableau de bord. Une fois ajouté à la liste blanche, vous pourrez envoyer et recevoir des messages WhatsApp de test via le Sandbox.

Envoyer un message WhatsApp de test

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"

  }'

Remplacer YOUR_API_KEY, YOUR_API_SECRET, et YOUR_ALLOWLISTED_NUMBER par vos valeurs réelles. Le numéro de téléphone « de destination » doit être au format E.164, sans le signe « + » au début (par exemple : 447700900000).

Remarque : le domaine du point de terminaison du bac à sable, messages-sandbox.nexmo.com, est différent de celui du point de terminaison standard de la Messages API. Vérifiez bien votre URL de base lorsque vous passez du bac à sable à l'environnement de production.

Valider un numéro et envoyer un message WhatsApp à l'aide du serveur MCP de Vonage Tooling

Je vous ai présenté deux commandes cURL distinctes permettant d'abord de valider le numéro de téléphone, puis d'envoyer le message WhatsApp. Vous pouvez utiliser le serveur MCP de Vonage Tooling pour valider un numéro et envoyer un message WhatsApp via des invites en langage naturel dans un agent IA tel que Claude ou Gemini au sein de Google Antigravity.

Configurer le serveur MCP

Installez-le globalement :

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

Ou bien, lancez-le directement avec npx :

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

Ajoutez-le ensuite à votre fichier de configuration du client MCP. Emplacements par client :

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

      }

    }

  }

}

Remarque : VONAGE_PRIVATE_KEY64 est votre fichier de clé privée encodé en base64. Sous macOS/Linux, vous pouvez le générer à l'aide de base64 -i private.key | tr -d '\n' . Je souhaitais le copier dans mon presse-papiers tout en effectuant cette opération sur GitHub Codespaces, et j'ai utilisé la commande suivante : base64 -i private.key | tr -d '\n' > b64_key.txt && code b64_key.txt pour le copier dans un nouveau fichier .txt, mais vous pouvez utiliser | pbcopy sous macOS pour le copier dans votre presse-papiers.

Valider et envoyer à l'aide d'une invite

Une fois le serveur opérationnel, vous pouvez demander à votre agent IA de valider un numéro et d'envoyer un message WhatsApp en une seule commande. L'agent appellera d'abord l'API Number Insight, vérifiera le résultat et ne procédera à l'envoi que si le numéro est validé.

Vous pouvez interagir avec votre LLM en lui soumettant une consigne du type :

« Utilisez l'API Number Insight pour valider le numéro +447700900000. Vérifiez que la valeur de is_format_valid est « true » et que celle de network_type est « MOBILE ». Si ces deux conditions sont remplies, envoyez un message WhatsApp à ce numéro avec le texte « Bonjour de la part de Vonage ! »

Conclusion

Félicitations, vous êtes arrivé à la fin de ce tutoriel. Vous savez désormais comment valider un numéro de téléphone avant d'envoyer un message WhatsApp, que ce soit via la sandbox de la Messages API à l'aide de cURL ou via le serveur MCP. 

Pour en savoir plus

• Présentation de l'API Identity Insights

• Référence de l'API Identity Insights

• Concepts relatifs au bac à sable de la Messages API

• Comprendre la messagerie WhatsApp

• Qu'est-ce que le format E.164 ?

• Envoyer un message WhatsApp avec Node.js

• Créer une application de rappel d'événements sur WhatsApp