Einführung

Das Senden einer WhatsApp-Nachricht an eine ungültige oder falsch formatierte Telefonnummer führt zu einem stillen Fehler. Bei der Eingabe wird kein Fehler angezeigt, die Nachricht kommt lediglich nie an. Bevor Sie diese erste Nachricht versenden, sollten Sie sich einen Moment Zeit nehmen, um die Nummer zu überprüfen, mit der Sie arbeiten.

In diesem Tutorial erfahren Sie, wie Sie die Identity Insights-API nutzen können, um vor dem Versenden einer WhatsApp-Nachricht zwei wichtige Kennzeichen zu überprüfen: das Format und den aktuellen Netzbetreiber. Zunächst werden wir die Lösung mithilfe von cURL-Befehlen und einer Sandbox-Umgebung untersuchen und anschließend erläutern, wie Sie den Vonage Tooling MCP-Server so konfigurieren können, dass eine WhatsApp-Nachricht an eine validierte Telefonnummer gesendet wird.

Voraussetzungen

·       Eine generierte Vonage-Anwendung mit einem privaten Schlüssel (für die JWT-Authentifizierung)

·       curl ist in Ihrem Terminal verfügbar

· A Vonage-Entwickleraccount

Identity Insights Playground

Bevor Sie loslegen und WhatsApp-Nachrichten versenden, können Sie sich zunächst mit der Messages API vertraut machen. Öffnen Sie den „Identity Insights Playground“ im Vonage-Dashboard, geben Sie eine beliebige Telefonnummer ein und wählen Sie format und current_carrieraus und sehen Sie sich die Antwort in Echtzeit an. Es gibt auch einen Demo-Modus mit vordefinierten Numbers, falls Sie die API erkunden möchten, ohne eine echte Nummer zu verwenden.

Getting Started with Identity Insights

Format

Die Formatprüfung überprüft, ob eine Telefonnummer strukturell gültig ist. Entspricht sie den internationalen Nummerierungsstandards, gibt sie Folgendes zurück:

• is_format_valid: Ein boolescher Wert, der angibt, ob die Nummer realistischerweise einem Teilnehmer zugeordnet werden könnte

• number_international: die Nummer im E.164-Format (z. B. +447700900000)

• number_national: die lokal formatierte Version

• country_code_iso2 und country_name

•  time_zones: nützlich, um Nachrichten zur richtigen Ortszeit zu planen

Dies ist der Schritt, der vor dem Speichern oder der weiteren Verarbeitung einer Telefonnummer durchgeführt werden sollte. Dabei wird die Eingabe in ein einheitliches E.164-Format normiert.

Aktueller Netzbetreiber

Die Information „current_carrier“ gibt Auskunft darüber, welchem Netz die Telefonnummer derzeit zugeordnet ist, sowie über die Art des Netzes. Die wichtigen Felder sind:

• name: der Name des Netzbetreibers (z. B. EE, Verizon, Deutsche Telekom)

• network_type: MOBIL, FESTNETZ, VIRTUELL usw.

• country_code: das Land, in dem die Nummer registriert ist

Wenn network_type das Ergebnis etwas anderes als MOBILE, kann die Nummer keine WhatsApp-Nachrichten empfangen. Das Speichern einer Festnetz- oder VoIP-Nummer und der anschließende Versuch, eine WhatsApp-Nachricht an diese Nummer zu senden, führt garantiert zum Fehlschlagen – und das lässt sich vollständig vermeiden.

Eine Telefonnummer überprüfen

Beide Auswertungen können in einem einzigen API-Aufruf angefordert werden. Führen Sie diesen Befehl in Ihrem Terminal aus. Ersetzen Sie $JWT durch ein gültiges JWT, das anhand Ihrer Vonage-Anmeldedaten generiert wurde, und ersetzen Sie die Telefonnummer durch diejenige, die Sie überprüfen möchten.

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

    }

  }'

Wenn Ihre Antwort erfolgreich ist, sieht sie wie im folgenden Codeausschnitt aus. Wenn is_format_valid wahr ist und network_type ist MOBILEist, können Sie fortfahren.

{

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

    }

  }

}

Messages API-Sandbox

Wir haben eine Messages API-Sandbox , in der du verschiedene Kanäle einrichten kannst, darunter Viber, Facebook Messenger, Instagram und nicht zuletzt WhatsApp. Ich habe bereits zwei Tutorials in JavaScript und Node.js erstellt, in denen gezeigt wird, wie man man mit Node.js eine WhatsApp-Nachricht versendet und wie man eine WhatsApp-Erinnerungs-App für Termine erstellt. Darüber hinaus bieten wir Tutorials für verschiedene Programmiersprachen an, die zeigen, wie man eine Testnachricht über die Messages API-Sandbox sendet.

Fügen Sie Ihre Nummer zur Whitelist hinzu

Wenn Sie die Messages API-Sandbox, sehen Sie den WhatsApp-Bereich mit einem QR-Code und einer Passphrase. Sie können entweder den QR-Code scannen oder manuell eine WhatsApp-Nachricht mit den drei auf dem Dashboard angezeigten Wörtern an die Nummer +1 415-738-6102 senden. Sobald Sie auf die Whitelist gesetzt wurden, können Sie über die Sandbox Test-WhatsApp-Nachrichten senden und empfangen.

Eine WhatsApp-Testnachricht senden

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"

  }'

Ersetzen YOUR_API_KEY, YOUR_API_SECRETund YOUR_ALLOWLISTED_NUMBER durch Ihre tatsächlichen Werte. Die „to“-Telefonnummer sollte im E.164-Format ohne das führende + angegeben werden (z. B. 447700900000).

Hinweis: Die Endpunkt-Domain der Sandbox „messages-sandbox.nexmo.com“ unterscheidet sich vom Standard-Endpunkt der Messages API. Überprüfen Sie Ihre Basis-URL sorgfältig, wenn Sie zwischen Sandbox und Produktionsumgebung wechseln.

Numbers validieren und WhatsApp-Nachricht über den Vonage Tooling MCP-Server senden

Ich habe Ihnen zwei separate cURL-Befehle gezeigt, mit denen Sie zunächst die Telefonnummer überprüfen und anschließend die WhatsApp-Nachricht versenden können. Sie können den Vonage Tooling MCP Server nutzen, um eine Nummer zu validieren und eine WhatsApp-Nachricht über natürliche Sprachbefehle in einem KI-Agenten wie Claude oder Gemini innerhalb von Google Antigravity zu versenden.

MCP-Server einrichten

Global installieren:

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

Oder führen Sie es direkt mit npx aus:

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

Fügen Sie es anschließend Ihrer MCP-Client-Konfigurationsdatei hinzu. Standorte nach Client:

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

      }

    }

  }

}

Hinweis: VONAGE_PRIVATE_KEY64 ist Ihre in Base64-Kodierung vorliegende private Schlüsseldatei. Unter macOS/Linux können Sie diese mit folgendem Befehl generieren: base64 -i private.key | tr -d '\n' generieren. Ich wollte sie dabei in GitHub Codespaces in die Zwischenablage kopieren und habe folgenden Befehl verwendet: base64 -i private.key | tr -d '\n' > b64_key.txt && code b64_key.txt , um sie in eine neue TXT-Datei zu kopieren, aber du kannst auch | pbcopy verwenden, um die Datei in die Zwischenablage zu kopieren.

Überprüfen und mit einer Eingabeaufforderung senden

Sobald der Server läuft, können Sie Ihren KI-Agenten mit einem einzigen Befehl auffordern, eine Telefonnummer zu überprüfen und eine WhatsApp-Nachricht zu versenden. Der Agent ruft zunächst die Identity Insights-API auf, überprüft das Ergebnis und führt den Versand erst dann durch, wenn die Nummer die Überprüfung bestanden hat.

Sie können mit Ihrem LLM kommunizieren, indem Sie eine Eingabe wie die folgende eingeben:

„Verwenden Sie die Identity Insights-API, um die Nummer +447700900000 zu überprüfen. Stellen Sie sicher, dass is_format_valid den Wert „true“ hat und network_type den Wert „MOBILE“ hat. Wenn beide Bedingungen erfüllt sind, senden Sie eine WhatsApp-Nachricht mit dem Text „Hallo von Vonage!“ an diese Nummer.“

Schlussfolgerung

Herzlichen Glückwunsch, du hast das Ende dieses Tutorials erreicht. Du weißt nun, wie du eine Telefonnummer vor dem Versenden einer WhatsApp-Nachricht validieren kannst – entweder über die Messages API-Sandbox mit cURL oder über den MCP-Server. 

Weitere Lektüre

• Übersicht über die Identity Insights-API

• Identity Insights – API-Referenz

• Konzepte der Messages API-Sandbox

• Verstehen von WhatsApp-Nachrichten

• Was ist das E.164-Format?

• Eine WhatsApp-Nachricht mit Node.js senden

• Eine WhatsApp-App für Veranstaltungserinnerungen erstellen