Schnellstart: Senden von WhatsApp-Nachrichten mit Advanced Messages

  • Artikel

Azure Communication Services ermöglicht es Ihnen, WhatsApp-Nachrichten zu senden und zu empfangen. In diesem Schnellstart integrieren Sie zunächst Ihre App mit dem Azure Communication-SDK für erweiterte Nachrichten und senden sowie empfangen WhatsApp-Nachrichten. Im Rahmen dieser Schnellstartanleitung fallen in Ihrem Azure-Konto ggf. geringfügige Kosten im Centbereich an.

Voraussetzungen

Einrichten

Erstellen des .NET-Projekts

Um Ihr Projekt zu erstellen, befolgen Sie das Tutorial unter Erstellen einer .NET-Konsolenanwendung mit Visual Studio.

Um den Code zu kompilieren, drücken Sie STRG+F7.

Installieren des Pakets

Installieren Sie das NuGet-Paket „Azure.Communication.Messages“ in Ihrem C#-Projekt.

  1. Öffnen Sie den NuGet-Paket-Manager unter Project>Manage NuGet Packages....
  2. Suchen Sie nach dem Paket Azure.Communication.Messages.
  3. Installieren Sie das neueste Release.

Einrichten des App-Frameworks

Öffnen Sie die Datei Program.cs in einem Text-Editor.

Ersetzen Sie die Inhalte von Program.cs durch den folgenden Code:

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Azure;
using Azure.Communication.Messages;

namespace AdvancedMessagingQuickstart
{
    class Program
    {
        public static async Task Main(string[] args)
        {
            Console.WriteLine("Azure Communication Services - Send WhatsApp Messages");

            // Quickstart code goes here
        }
    }
}

Um die erweiterten Messagingfeatures zu verwenden, fügen wir eine using-Anweisung hinzu, um den Azure.Communication.Messages-Namespace einzubinden.

using Azure.Communication.Messages;

Objektmodell

Die folgenden Klassen und Schnittstellen verarbeiten einige der wichtigsten Features des Azure Communication Services Advance Messaging SDK für .NET.

Name Beschreibung
NotificationMessagesClient Diese Klasse stellt eine Verbindung mit Ihrer Azure Communication Services-Ressource her. Sie sendet die Nachrichten.
MessageTemplate Diese Klasse definiert, welche Vorlage Sie verwenden, und den Inhalt der Vorlageneigenschaften für Ihre Nachricht.
TemplateNotificationContent Diese Klasse definiert das „Wer“ und das „Was“ der Vorlagennachricht, die Sie senden möchten.
TextNotificationContent Diese Klasse definiert das „Wer“ und das „Was“ der Textnachricht, die Sie senden möchten.
MediaNotificationContent Diese Klasse definiert das „Wer“ und das „Was“ der Mediennachricht, die Sie senden möchten.

Codebeispiele

Befolgen Sie diese Schritte, um die erforderlichen Codeschnipsel zur Main-Funktion Ihrer Program.cs-Datei hinzuzufügen.

Authentifizieren des Clients

NotificationMessagesClient wird verwendet, um eine Verbindung mit Ihrer Azure Communication Services-Ressource herzustellen.

Der Einfachheit halber wird in diesem Schnellstart eine Verbindungszeichenfolge zur Authentifizierung verwendet. In Produktionsumgebungen wird empfohlen, Dienstprinzipale zu verwenden.

Rufen Sie die Verbindungszeichenfolge aus Ihrer Azure Communication Services-Ressource im Azure-Portal ab. Navigieren Sie auf der linken Seite zur Registerkarte Keys. Kopieren Sie das Feld Connection string für den Primärschlüssel. Die Verbindungszeichenfolge hat das Format endpoint=https://{your Azure Communication Services resource name}.communication.azure.com/;accesskey={secret key}.

Screenshot einer Azure Communication Services-Ressource im Azure-Portal, die das Feld „Verbindungszeichenfolge“ im Abschnitt „Primärschlüssel“ anzeigt.

Legen Sie die Umgebungsvariable COMMUNICATION_SERVICES_CONNECTION_STRING auf den Wert Ihrer Verbindungszeichenfolge fest.
Öffnen Sie ein Konsolenfenster, und geben Sie den folgenden Befehl ein:

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

Nachdem Sie die Umgebungsvariable hinzugefügt haben, müssen Sie unter Umständen alle ausgeführten Programme neu starten, die die Umgebungsvariable lesen müssen, z. B. das Konsolenfenster. Wenn Sie beispielsweise Visual Studio als Editor verwenden, müssen Sie Visual Studio neu starten, bevor Sie das Beispiel ausführen.

Weitere Informationen zum Festlegen einer Umgebungsvariablen für Ihr System finden Sie in den Schritten unter Speichern der Verbindungszeichenfolge in einer Umgebungsvariablen.

Um NotificationMessagesClient zu instanziieren, fügen Sie der Main-Methode den folgenden Code hinzu:

// Retrieve connection string from environment variable
string connectionString = 
    Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_CONNECTION_STRING");

// Instantiate the client
var notificationMessagesClient = new NotificationMessagesClient(connectionString);

Festlegen der Kanalregistrierungs-ID

Die GUID der Kanalregistrierungs-ID wurde während der Kanalregistrierung erstellt. Sie können diese auf der Registerkarte „Kanäle“ im Portal Ihrer Azure Communication Services-Ressource finden.

Screenshot einer Azure Communication Services-Ressource im Azure-Portal, auf der die Registerkarte „Kanäle“ angezeigt wird. Besonderes Augenmerk wird auf die Kopierfunktion des Feldes „Kanal-ID“ gelegt.

Weisen Sie diese der Variablen „channelRegistrationId“ zu.

var channelRegistrationId = new Guid("<your channel registration ID GUID>");

Festlegen der Empfängerliste

Sie müssen eine echte Telefonnummer angeben, die einem WhatsApp-Konto zugeordnet ist. Dieses WhatsApp-Konto empfängt die Vorlagen-, Text- und Mediennachrichten, die in diesem Schnellstart gesendet werden. Für diesen Schnellstart können Sie Ihre persönliche Telefonnummer verwenden.

Die Empfängertelefonnummer kann nicht die geschäftliche Telefonnummer (Sender-ID) sein, die der WhatsApp-Kanalregistrierung zugeordnet ist. Die Sender-ID wird als Sender der Text- und Mediennachrichten angezeigt, die an den Empfänger gesendet werden.

Die Telefonnummer sollte die Landeskennzahl beinhalten. Weitere Informationen zur Formatierung von Telefonnummern finden Sie in der WhatsApp-Dokumentation für Telefonnummernformate.

Hinweis

In der Empfängerliste wird derzeit lediglich eine Telefonnummer unterstützt.

Erstellen Sie die Empfängerliste folgendermaßen:

var recipientList = new List<string> { "<to WhatsApp phone number>" };

Beispiel:

// Example only
var recipientList = new List<string> { "+14255550199" };

Einrichten des Nachrichtenversands zwischen Geschäfts- und WhatsApp-Benutzern

Unterhaltungen zwischen einem WhatsApp Business-Konto und WhatsApp-Benutzer*innen kann auf eine von zwei Arten initiiert werden:

  • Das Unternehmen sendet eine Nachrichtenvorlage an die WhatsApp-Benutzer*innen.
  • Die WhatsApp-Benutzer*innen senden eine beliebige Nachricht an die Geschäftsnummer.

Unabhängig davon, wie die Unterhaltung gestartet wurde, kann ein Unternehmen Vorlagennachrichten nur senden, bis der Benutzer eine Nachricht an das Unternehmen sendet. Erst nachdem der Benutzer eine Nachricht an das Unternehmen gesendet hat, darf das Unternehmen während der aktiven Unterhaltung Text- oder Mediennachrichten an den Benutzer senden. Nach Ablauf des 24-Stunden-Fensters muss die Unterhaltung erneut eingeleitet werden. Weitere Informationen zu Unterhaltungen finden Sie in der Definition auf der WhatsApp Business-Platform.

(Option 1) Initiieren einer Unterhaltung durch das Unternehmen durch das Senden einer Vorlagennachricht

Initiieren Sie eine Unterhaltung, indem Sie eine Nachrichtenvorlage senden.

Erstellen Sie zunächst ein MessageTemplate-Objekt mit den Werten für eine Vorlage.

Hinweis

Informationen zum Überprüfen der verfügbaren Vorlagen finden Sie in den Anweisungen unter Auflisten von Vorlagen. Wenn Sie keine Vorlage verwenden können, fahren Sie mit Option 2 fort.

Im folgenden Beispiel wird ein MessageTemplate-Objekt mithilfe der Standardvorlage sample_template erstellt.
Wenn sample_template Ihnen nicht zur Verfügung steht, fahren Sie mit Option 2 fort. Informationen zum Senden einer anderen Vorlage mit Option 1 finden Sie auf der Seite Vorlagen.

Mit dem Nachrichten-SDK kann Contoso vorlagenbasierte WhatsApp-Nachrichten an WhatsApp-Benutzer senden. Zum Senden von Vorlagen sind folgende Angaben erforderlich:

// Assemble the template content
string templateName = "sample_template";
string templateLanguage = "en_us";
var messageTemplate = new MessageTemplate(templateName, templateLanguage);

Weitere Beispiele zum Zusammenstellen von MessageTemplate und zum Erstellen einer eigenen Vorlage finden Sie in der folgenden Ressource:

Weitere WhatsApp-Anforderungen für Vorlagen finden Sie in den Referenzen zur WhatsApp Business-Platform-API:

Stellen Sie die Vorlagennachricht zusammen, und senden Sie sie:

// Assemble template message
var templateContent = 
    new TemplateNotificationContent(channelRegistrationId, recipientList, messageTemplate);

// Send template message
Response<SendMessageResult> sendTemplateMessageResult = 
    await notificationMessagesClient.SendAsync(templateContent);

Nun müssen die Benutzer auf die Vorlagennachricht antworten. Antworten Sie über das WhatsApp-Benutzerkonto auf die Nachrichtenvorlage, die vom WhatsApp Business-Konto empfangen wurde. Der Inhalt dieser Nachricht ist hierfür irrelevant.

Wichtig

Der Empfänger muss auf die Nachrichtenvorlage antworten, um die Unterhaltung zu initiieren, bevor Text- oder Mediennachrichten an den Empfänger übermittelt werden können.

(Option 2) Initiieren einer Unterhaltung durch Benutzer*innen

Als zweite Möglichkeit kann eine Unterhaltung zwischen einem WhatsApp Business-Konto und WhatsApp-Benutzer*innen durch die Benutzer*innen initiiert werden. Senden Sie dazu aus Ihrem persönlichen WhatsApp-Konto eine Nachricht an Ihre Geschäftsnummer (Sender-ID).

Eine im Web angezeigte WhatsApp-Konversation mit einer Nutzernachricht, die an die Nummer des WhatsApp-Business-Kontos gesendet wurde.

Senden einer Textnachricht an WhatsApp-Benutzer

Messages SDK ermöglicht Contoso das Senden von WhatsApp-Textnachrichten, die von WhatsApp-Nutzern initiiert wurden. Zum Senden von Textnachrichten sind die folgenden Angaben erforderlich:

Wichtig

Um eine SMS an einen WhatsApp-Benutzer zu senden, muss der WhatsApp-Benutzer zuerst eine Nachricht an das WhatsApp Business-Konto senden. Weitere Informationen finden Sie unter Einrichten des Nachrichtenversands zwischen Unternehmens- und WhatsApp-Benutzer*innen.

In diesem Beispiel antworten wir dem WhatsApp-Benutzer mit dem Text: „Danke für Ihre Rückmeldung..\n Von Notification Messaging SDK“.

Stellen Sie die Textnachricht zusammen, und senden Sie sie:

// Assemble text message
var textContent = 
    new TextNotificationContent(channelRegistrationId, recipientList, "Thanks for your feedback.\n From Notification Messaging SDK");

// Send text message
Response<SendMessageResult> sendTextMessageResult = 
    await notificationMessagesClient.SendAsync(textContent);

Senden einer Mediennachricht an WhatsApp-Benutzer

Mit dem Nachrichten-SDK kann Contoso Bild-WhatsApp-Nachrichten an WhatsApp-Benutzer senden. Zum Senden eingebetteter Bildnachrichten sind die folgenden Angaben erforderlich:

Wichtig

Um eine SMS an einen WhatsApp-Benutzer zu senden, muss der WhatsApp-Benutzer zuerst eine Nachricht an das WhatsApp Business-Konto senden. Weitere Informationen finden Sie unter Einrichten des Nachrichtenversands zwischen Unternehmens- und WhatsApp-Benutzer*innen.

Erstellen Sie einen Beispiel-URI:

var uri = new Uri("https://aka.ms/acsicon1");

Stellen Sie die Mediennachricht zusammen, und senden Sie sie:

// Assemble media message
var mediaContent = 
    new MediaNotificationContent(channelRegistrationId, recipientList, uri);

// Send media message
Response<SendMessageResult> sendMediaMessageResult = 
    await notificationMessagesClient.SendAsync(mediaContent);

Ausführen des Codes

Erstellen Sie Ihr Programm und führen Sie es aus.

Zum Senden einer Text- oder Mediennachricht an einen WhatsApp-Benutzer ist eine aktive Unterhaltung zwischen dem WhatsApp Business-Konto und dem WhatsApp-Benutzer erforderlich.
Wenn keine aktive Unterhaltung vorliegt, sollten Sie für diesen Schnellstart eine Wartezeit zwischen dem Senden der Vorlagennachricht und dem Senden der SMS hinzufügen. Diese zusätzliche Verzögerung gibt Ihnen genügend Zeit, um dem Unternehmen über das WhatsApp-Konto des Benutzers zu antworten. Das vollständige Beispiel unter Beispielcode verlangt vor dem Senden der nächsten Nachricht eine manuelle Benutzereingabe.

Bei Erfolg erhalten Sie drei Nachrichten im WhatsApp-Konto des Benutzers.

  1. Um den Code zu kompilieren, drücken Sie STRG+F7.
  2. Um das Programm ohne Debuggen auszuführen, drücken Sie STRG+F5.

Vollständiger Beispielcode

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Azure;
using Azure.Communication.Messages;

namespace AdvancedMessagingQuickstart
{
    class Program
    {
        public static async Task Main(string[] args)
        {
            Console.WriteLine("Azure Communication Services - Send WhatsApp Messages\n");

            string connectionString = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_CONNECTION_STRING");
            NotificationMessagesClient notificationMessagesClient = 
                new NotificationMessagesClient(connectionString);

            var channelRegistrationId = new Guid("<Your Channel ID>");
            var recipientList = new List<string> { "<Recipient's WhatsApp Phone Number>" };

            // Send sample template sample_template
            string templateName = "sample_template";
            string templateLanguage = "en_us";
            MessageTemplate sampleTemplate = new MessageTemplate(templateName, templateLanguage);
            TemplateNotificationContent templateContent = 
                new TemplateNotificationContent(channelRegistrationId, recipientList, sampleTemplate);
            Response<SendMessageResult> sendTemplateMessageResult = 
                await notificationMessagesClient.SendAsync(templateContent);

            PrintResult(sendTemplateMessageResult);
            Console.WriteLine("Template message sent.\nWait until the WhatsApp user responds " +
                "to the template message, then press any key to continue.\n");
            Console.ReadKey();

            // Send a text message
            string messageText = "Thanks for your feedback.";
            TextNotificationContent textContent =
                new TextNotificationContent(channelRegistrationId, recipientList, messageText);
            Response<SendMessageResult> sendTextMessageResult =
                await notificationMessagesClient.SendAsync(textContent);

            PrintResult(sendTextMessageResult);
            Console.WriteLine($"Text message sent to my phoneNumber.\nPress any key to continue.\n");
            Console.ReadKey();

            // Send a media message
            Uri uri = new Uri("https://aka.ms/acsicon1");
            MediaNotificationContent mediaContent =
                new MediaNotificationContent(channelRegistrationId, recipientList, uri);
            Response<SendMessageResult> sendMediaMessageResult =
                await notificationMessagesClient.SendAsync(mediaContent);

            PrintResult(sendMediaMessageResult);
            Console.WriteLine("Media message sent.\nPress any key to exit.\n");
            Console.ReadKey();
        }

        public static void PrintResult(Response<SendMessageResult> result)
        {
            Console.WriteLine($"Response: {result.GetRawResponse().Status} " +
                $"({result.GetRawResponse().ReasonPhrase})");
            Console.WriteLine($"Date: " +
                $"{result.GetRawResponse().Headers.First(header => header.Name == "Date").Value}");
            Console.WriteLine($"ClientRequestId: {result.GetRawResponse().ClientRequestId}");
            Console.WriteLine($"MS-CV: " +
                $"{result.GetRawResponse().Headers.First(header => header.Name == "MS-CV").Value}");
            foreach (var receipts in result.Value.Receipts)
            {
                Console.WriteLine($"MessageId: {receipts.MessageId}");
            }
            Console.WriteLine($"\n");
        }
    }
}

Voraussetzungen

Einrichten

Um eine Umgebung zum Senden von Nachrichten einzurichten, müssen Sie die Schritte in den folgenden Abschnitten ausführen.

Erstellen einer neuen Java-Anwendung

Öffnen Sie Ihr Terminal- oder Befehlsfenster, und navigieren Sie zu dem Verzeichnis, in dem Sie Ihre Java-Anwendung erstellen möchten. Führen Sie den folgenden Befehl aus, um das Java-Projekt aus der Vorlage „maven-archetype-quickstart“ zu generieren.

mvn archetype:generate -DgroupId="com.communication.quickstart" -DartifactId="communication-quickstart" -DarchetypeArtifactId="maven-archetype-quickstart" -DarchetypeVersion="1.4" -DinteractiveMode="false"

Das generate-Ziel erstellt ein Verzeichnis, das den gleichen Namen wie der artifactId-Wert besitzt. In diesem Verzeichnis enthält das Verzeichnis src/main/java den Quellcode des Projekts. Das Verzeichnis src/test/java enthält die Testquelle, und die Datei pom.xml ist das Projektobjektmodell (POM) des Projekts.

Installieren des Pakets

Öffnen Sie die Datei pom.xml in Ihrem Text-Editor. Fügen Sie der Gruppe „dependencies“ das folgende Abhängigkeitselement hinzu.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-messages</artifactId>
    <version>1.0.0</version>
</dependency>

Einrichten des App-Frameworks

Öffnen Sie /src/main/java/com/communication/quickstart/App.java in einem Text-Editor, fügen Sie Importanweisungen hinzu, und entfernen Sie die System.out.println("Hello world!");-Anweisung:

package com.communication.quickstart;

import com.azure.communication.messages.*;
import com.azure.communication.messages.models.*;

import java.util.ArrayList;
import java.util.List;
public class App
{
    public static void main( String[] args )
    {
        // Quickstart code goes here.
    }
}

Objektmodell

Die folgenden Klassen und Schnittstellen verarbeiten einige der wichtigsten Features des Azure Communication Services Advance Messaging SDK für Java.

Name Beschreibung
NotificationMessagesClientBuilder Diese Klasse erstellt die NotificationMessagesClient-Klasse. Sie stellen sie mit einem Endpunkt und Anmeldeinformationen bereit.
NotificationMessagesClient Diese Klasse wird benötigt, um WhatsApp-Nachrichten zu senden und Mediendateien herunterzuladen.
NotificationMessagesAsyncClient Diese Klasse wird benötigt, um WhatsApp-Nachrichten zu senden und Mediendateien asynchron herunterzuladen.
SendMessageResult Diese Klasse enthält das Ergebnis des Diensts für erweitertes Messaging zum Senden von Benachrichtigungen.
MessageTemplateClientBuilder Diese Klasse erstellt die MessageTemplateClient-Klasse. Sie stellen sie mit einem Endpunkt und Anmeldeinformationen bereit.
MessageTemplateClient Diese Klasse wird benötigt, um die Liste der WhatsApp-Vorlagen abzurufen.
MessageTemplateAsyncClient Diese Klasse wird benötigt, um die Liste der WhatsApp-Vorlagen asynchron abzurufen.

Codebeispiele

Befolgen Sie diese Schritte, um die erforderlichen Codeschnipsel zur main-Funktion Ihrer App.java-Datei hinzuzufügen.

Authentifizieren des Clients

Für die Authentifizierung eines Messagingclients stehen verschiedene Optionen zur Verfügung:

Um einen Client zu authentifizieren, instanziieren Sie NotificationMessagesClient oder MessageTemplateClient mit Ihrer Verbindungszeichenfolge. Sie können den Client auch mit einem beliebigen benutzerdefinierten HTTP-Client initialisieren, der die com.azure.core.http.HttpClient-Schnittstelle implementiert.

Der Einfachheit halber wird in diesem Schnellstart eine Verbindungszeichenfolge zur Authentifizierung verwendet. In Produktionsumgebungen wird empfohlen, Dienstprinzipale zu verwenden.

Rufen Sie die Verbindungszeichenfolge aus Ihrer Azure Communication Services-Ressource im Azure-Portal ab. Navigieren Sie auf der linken Seite zur Registerkarte Keys. Kopieren Sie das Feld Connection string für Primary key. Die Verbindungszeichenfolge hat das Format endpoint=https://{your Azure Communication Services resource name}.communication.azure.com/;accesskey={secret key}.

Screenshot einer Azure Communication Services-Ressource im Azure-Portal, die das Feld „Verbindungszeichenfolge“ im Abschnitt „Primärschlüssel“ anzeigt.

Legen Sie die Umgebungsvariable COMMUNICATION_SERVICES_CONNECTION_STRING auf den Wert Ihrer Verbindungszeichenfolge fest.
Öffnen Sie ein Konsolenfenster, und geben Sie den folgenden Befehl ein:

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

Weitere Informationen zum Festlegen einer Umgebungsvariablen für Ihr System finden Sie in den Schritten unter Speichern der Verbindungszeichenfolge in einer Umgebungsvariablen.

Zum Instanziieren von NotificationMessagesClient fügen Sie der main-Methode den folgenden Code hinzu:

// You can get your connection string from your resource in the Azure portal.
String connectionString = System.getenv("COMMUNICATION_SERVICES_CONNECTION_STRING");

NotificationMessagesClient notificationClient = new NotificationMessagesClientBuilder()
    .connectionString(connectionString)
    .buildClient();

Festlegen der Kanalregistrierungs-ID

Die GUID der Kanalregistrierungs-ID wurde während der Kanalregistrierung erstellt. Sie können diese auf der Registerkarte „Kanäle“ im Portal Ihrer Azure Communication Services-Ressource finden.

Screenshot einer Azure Communication Services-Ressource im Azure-Portal, auf der die Registerkarte „Kanäle“ angezeigt wird. Besonderes Augenmerk wird auf die Kopierfunktion des Feldes „Kanal-ID“ gelegt.

Weisen Sie diese der Variablen „channelRegistrationId“ zu.

String channelRegistrationId = "<your channel registration id GUID>";

Festlegen der Empfängerliste

Sie müssen eine echte Telefonnummer angeben, die einem WhatsApp-Konto zugeordnet ist. Dieses WhatsApp-Konto empfängt die Text- und Mediennachrichten, die in diesem Schnellstart gesendet werden. Für diesen Schnellstart können Sie Ihre persönliche Telefonnummer verwenden.

Die Empfängertelefonnummer kann nicht die geschäftliche Telefonnummer (Sender-ID) sein, die der WhatsApp-Kanalregistrierung zugeordnet ist. Die Sender-ID wird als Sender der Text- und Mediennachrichten angezeigt, die an den Empfänger gesendet werden.

Die Telefonnummer sollte die Landeskennzahl beinhalten. Weitere Informationen zur Formatierung von Telefonnummern finden Sie in der WhatsApp-Dokumentation für Telefonnummernformate.

Hinweis

In der Empfängerliste wird derzeit lediglich eine Telefonnummer unterstützt.

Erstellen Sie die Empfängerliste folgendermaßen:

List<String> recipientList = new ArrayList<>();
recipientList.add("<to WhatsApp phone number>");

Beispiel:

// Example only
List<String> recipientList = new ArrayList<>();
recipientList.add("+14255550199");

Einrichten des Nachrichtenversands zwischen Geschäfts- und WhatsApp-Benutzern

Unterhaltungen zwischen einem WhatsApp Business-Konto und WhatsApp-Benutzer*innen kann auf eine von zwei Arten initiiert werden:

  • Das Unternehmen sendet eine Nachrichtenvorlage an die WhatsApp-Benutzer*innen.
  • Die WhatsApp-Benutzer*innen senden eine beliebige Nachricht an die Geschäftsnummer.

Unabhängig davon, wie die Unterhaltung gestartet wurde, kann ein Unternehmen Vorlagennachrichten nur senden, bis der Benutzer eine Nachricht an das Unternehmen sendet. Erst nachdem der Benutzer eine Nachricht an das Unternehmen gesendet hat, darf das Unternehmen während der aktiven Unterhaltung Text- oder Mediennachrichten an den Benutzer senden. Nach Ablauf des 24-Stunden-Fensters muss die Unterhaltung erneut eingeleitet werden. Weitere Informationen zu Unterhaltungen finden Sie in der Definition auf der WhatsApp Business-Platform.

(Option 1) Initiieren einer Unterhaltung durch das Unternehmen durch das Senden einer Vorlagennachricht

Initiieren Sie eine Unterhaltung, indem Sie eine Nachrichtenvorlage senden.

Erstellen Sie zunächst ein MessageTemplate-Objekt mit den Werten für eine Vorlage.

Hinweis

Informationen zum Überprüfen der verfügbaren Vorlagen finden Sie in den Anweisungen unter Auflisten von Vorlagen. Wenn Sie keine Vorlage verwenden können, fahren Sie mit Option 2 fort.

Im folgenden Beispiel wird ein MessageTemplate-Objekt mithilfe der Standardvorlage sample_template erstellt.
Wenn sample_template Ihnen nicht zur Verfügung steht, fahren Sie mit Option 2 fort. Informationen zum Senden einer anderen Vorlage mit Option 1 finden Sie auf der Seite Vorlagen.

Mit dem Nachrichten-SDK kann Contoso vorlagenbasierte WhatsApp-Nachrichten an WhatsApp-Benutzer senden. Zum Senden von Vorlagen sind folgende Angaben erforderlich:

// Assemble the template content
String templateName = "sample_template";
String templateLanguage = "en_us";
MessageTemplate messageTemplate = new MessageTemplate(templateName, templateLanguage);

// Assemble template message
TemplateNotificationContent templateContent = new TemplateNotificationContent(channelRegistrationId, recipientList, messageTemplate);

// Send template message
SendMessageResult templateMessageResult = notificationClient.send(templateContent);

// Process result
for (MessageReceipt messageReceipt : templateMessageResult.getReceipts()) {
    System.out.println("Message sent to:" + messageReceipt.getTo() + " and message id:" + messageReceipt.getMessageId());
}

Nun müssen die Benutzer auf die Vorlagennachricht antworten. Antworten Sie über das WhatsApp-Benutzerkonto auf die Nachrichtenvorlage, die vom WhatsApp Business-Konto empfangen wurde. Der Inhalt dieser Nachricht ist hierfür irrelevant.

Wichtig

Der Empfänger muss auf die Nachrichtenvorlage antworten, um die Unterhaltung zu initiieren, bevor Text- oder Mediennachrichten an den Empfänger übermittelt werden können.

(Option 2) Initiieren einer Unterhaltung durch Benutzer*innen

Als zweite Möglichkeit kann eine Unterhaltung zwischen einem WhatsApp Business-Konto und WhatsApp-Benutzer*innen durch die Benutzer*innen initiiert werden. Senden Sie dazu aus Ihrem persönlichen WhatsApp-Konto eine Nachricht an Ihre Geschäftsnummer (Sender-ID).

Eine im Web angezeigte WhatsApp-Konversation mit einer Nutzernachricht, die an die Nummer des WhatsApp-Business-Kontos gesendet wurde.

Senden einer Textnachricht an WhatsApp-Benutzer

Messages SDK ermöglicht Contoso das Senden von WhatsApp-Textnachrichten, die von WhatsApp-Nutzern initiiert wurden. Zum Senden von Textnachrichten sind die folgenden Angaben erforderlich:

Wichtig

Um eine SMS an einen WhatsApp-Benutzer zu senden, muss der WhatsApp-Benutzer zuerst eine Nachricht an das WhatsApp Business-Konto senden. Weitere Informationen finden Sie unter Einrichten des Nachrichtenversands zwischen Unternehmens- und WhatsApp-Benutzer*innen.

In diesem Beispiel antworten wir dem WhatsApp-Benutzer mit dem Text: „Danke für Ihre Rückmeldung..\n Von Notification Messaging SDK“.

Stellen Sie die Textnachricht zusammen, und senden Sie sie:

// Assemble text message
TextNotificationContent textContent = new TextNotificationContent(channelRegistrationId, recipientList, "“Thanks for your feedback.\n From Notification Messaging SDK");

// Send text message
SendMessageResult textMessageResult = notificationClient.send(textContent);

// Process result
for (MessageReceipt messageReceipt : textMessageResult.getReceipts()) {
    System.out.println("Message sent to:" + messageReceipt.getTo() + " and message id:" + messageReceipt.getMessageId());
}

Senden einer Mediennachricht an WhatsApp-Benutzer

Mit dem Nachrichten-SDK kann Contoso Bild-WhatsApp-Nachrichten an WhatsApp-Benutzer senden. Zum Senden eingebetteter Bildnachrichten sind die folgenden Angaben erforderlich:

Wichtig

Um eine SMS an einen WhatsApp-Benutzer zu senden, muss der WhatsApp-Benutzer zuerst eine Nachricht an das WhatsApp Business-Konto senden. Weitere Informationen finden Sie unter Einrichten des Nachrichtenversands zwischen Unternehmens- und WhatsApp-Benutzer*innen.

Erstellen Sie einen Beispiel-URI:

String mediaUrl = "https://aka.ms/acsicon1";

Stellen Sie die Mediennachricht zusammen, und senden Sie sie:

// Assemble media message
MediaNotificationContent mediaContent = new MediaNotificationContent(channelRegistrationId, recipientList, mediaUrl);

// Send media message
SendMessageResult mediaMessageResult = notificationClient.send(mediaContent);

// Process result
for (MessageReceipt messageReceipt : mediaMessageResult.getReceipts()) {
    System.out.println("Message sent to:" + messageReceipt.getTo() + " and message id:" + messageReceipt.getMessageId());
}

Ausführen des Codes

  1. Navigieren Sie zum Verzeichnis, das die Datei pom.xml enthält, und kompilieren Sie das Projekt mithilfe des Befehls mvn.

    mvn compile

  2. Führen Sie die App aus, indem Sie den folgenden mvn-Befehl ausführen.

    mvn exec:java -D"exec.mainClass"="com.communication.quickstart.App" -D"exec.cleanupDaemonThreads"="false"

Vollständiger Beispielcode

Den fertigen Code für diese Schnellstartanleitung finden Sie auf GitHub.

Voraussetzungen

Einrichten

Um eine Umgebung zum Senden von Nachrichten einzurichten, müssen Sie die Schritte in den folgenden Abschnitten ausführen.

Erstellen einer neuen Node.js-Anwendung

  1. Erstellen Sie ein neues Verzeichnis für Ihre App, und navigieren Sie zu diesem, indem Sie Ihr Terminal- oder Befehlsfenster öffnen und dann den folgenden Befehl ausführen.

    mkdir advance-messages-quickstart && cd advance-messages-quickstart

  2. Führen Sie den folgenden Befehl aus, um eine package.json-Datei mit den Standardeinstellungen zu erstellen.

    npm init -y

  3. Verwenden Sie einen Text-Editor, um im Stammverzeichnis des Projekts die Datei send-messages.js zu erstellen.

  4. Fügen Sie der Datei send-messages.js das folgende Codeschnipsel hinzu.

    async function main() {
    // Quickstart code goes here.
}

main().catch((error) => {
    console.error("Encountered an error while sending message: ", error);
    process.exit(1);
});

In den folgenden Abschnitten fügen Sie den gesamten Quellcode aus diesem Schnellstart zur soeben erstellten Datei send-messages.js hinzu.

Installieren des Pakets

Verwenden Sie den Befehl npm install, um das Azure Communication Services Advance Messaging SDK für JavaScript zu installieren.

npm install @azure-rest/communication-messages --save

Durch die Option --save wird die Bibliothek als Abhängigkeit in der Datei package.json aufgeführt.

Objektmodell

Die folgenden Klassen und Schnittstellen verarbeiten einige der wichtigsten Features des Azure Communication Services Advance Messaging SDK für JavaScript.

Name Beschreibung
MessageClient Diese Klasse stellt eine Verbindung mit Ihrer Azure Communication Services-Ressource her. Sie sendet die Nachrichten.
MessageTemplate Diese Klasse definiert, welche Vorlage Sie verwenden, und den Inhalt der Vorlageneigenschaften für Ihre Nachricht.

Codebeispiele

Befolgen Sie diese Schritte, um die erforderlichen Codeschnipsel zur main-Funktion Ihrer send-messages.js-Datei hinzuzufügen.

Authentifizieren des Clients

Im folgenden Code wird die Verbindungszeichenfolge für die Ressource aus einer Umgebungsvariablen namens COMMUNICATION_SERVICES_CONNECTION_STRING mithilfe des dotenv-Pakets abgerufen.

Der Einfachheit halber wird in diesem Schnellstart eine Verbindungszeichenfolge zur Authentifizierung verwendet. In Produktionsumgebungen wird empfohlen, Dienstprinzipale zu verwenden.

Rufen Sie die Verbindungszeichenfolge aus Ihrer Azure Communication Services-Ressource im Azure-Portal ab. Navigieren Sie auf der linken Seite zur Registerkarte Keys. Kopieren Sie das Feld Connection string für Primary key. Die Verbindungszeichenfolge hat das Format endpoint=https://{your Azure Communication Services resource name}.communication.azure.com/;accesskey={secret key}.

Screenshot einer Azure Communication Services-Ressource im Azure-Portal, die das Feld „Verbindungszeichenfolge“ im Abschnitt „Primärschlüssel“ anzeigt.

Legen Sie die Umgebungsvariable COMMUNICATION_SERVICES_CONNECTION_STRING auf den Wert Ihrer Verbindungszeichenfolge fest.
Öffnen Sie ein Konsolenfenster, und geben Sie den folgenden Befehl ein:

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

Weitere Informationen zum Festlegen einer Umgebungsvariablen für Ihr System finden Sie in den Schritten unter Speichern der Verbindungszeichenfolge in einer Umgebungsvariablen.

Um MessageClient zu instanziieren, fügen Sie der Main-Methode den folgenden Code hinzu:

const MessageClient = require("@azure-rest/communication-messages").default;

// Set Connection string
const connectionString = process.env["COMMUNICATION_SERVICES_CONNECTION_STRING"];

// Instantiate the client
const client = MessageClient(connectionString);

Festlegen der Kanalregistrierungs-ID

Die GUID der Kanalregistrierungs-ID wurde während der Kanalregistrierung erstellt. Sie können diese auf der Registerkarte „Kanäle“ im Portal Ihrer Azure Communication Services-Ressource finden.

Screenshot einer Azure Communication Services-Ressource im Azure-Portal, auf der die Registerkarte „Kanäle“ angezeigt wird. Besonderes Augenmerk wird auf die Kopierfunktion des Feldes „Kanal-ID“ gelegt.

Weisen Sie diese der Variablen „channelRegistrationId“ zu.

const channelRegistrationId = "<your channel registration id GUID>";

Festlegen der Empfängerliste

Sie müssen eine echte Telefonnummer angeben, die einem WhatsApp-Konto zugeordnet ist. Dieses WhatsApp-Konto empfängt die Vorlagen-, Text- und Mediennachrichten, die in diesem Schnellstart gesendet werden. Für diesen Schnellstart können Sie Ihre persönliche Telefonnummer verwenden.

Die Empfängertelefonnummer kann nicht die geschäftliche Telefonnummer (Sender-ID) sein, die der WhatsApp-Kanalregistrierung zugeordnet ist. Die Sender-ID wird als Sender der Text- und Mediennachrichten angezeigt, die an den Empfänger gesendet werden.

Die Telefonnummer sollte die Landeskennzahl beinhalten. Weitere Informationen zur Formatierung von Telefonnummern finden Sie in der WhatsApp-Dokumentation für Telefonnummernformate.

Hinweis

In der Empfängerliste wird derzeit lediglich eine Telefonnummer unterstützt.

Erstellen Sie die Empfängerliste folgendermaßen:

const recipientList = ["<to WhatsApp phone number>"];

Beispiel:

// Example only
const recipientList = ["+14255550199"];

Einrichten des Nachrichtenversands zwischen Geschäfts- und WhatsApp-Benutzern

Unterhaltungen zwischen einem WhatsApp Business-Konto und WhatsApp-Benutzer*innen kann auf eine von zwei Arten initiiert werden:

  • Das Unternehmen sendet eine Nachrichtenvorlage an die WhatsApp-Benutzer*innen.
  • Die WhatsApp-Benutzer*innen senden eine beliebige Nachricht an die Geschäftsnummer.

Unabhängig davon, wie die Unterhaltung gestartet wurde, kann ein Unternehmen Vorlagennachrichten nur senden, bis der Benutzer eine Nachricht an das Unternehmen sendet. Erst nachdem der Benutzer eine Nachricht an das Unternehmen gesendet hat, darf das Unternehmen während der aktiven Unterhaltung Text- oder Mediennachrichten an den Benutzer senden. Nach Ablauf des 24-Stunden-Fensters muss die Unterhaltung erneut eingeleitet werden. Weitere Informationen zu Unterhaltungen finden Sie in der Definition auf der WhatsApp Business-Platform.

(Option 1) Initiieren einer Unterhaltung durch das Unternehmen durch das Senden einer Vorlagennachricht

Initiieren Sie eine Unterhaltung, indem Sie eine Nachrichtenvorlage senden.

Erstellen Sie zunächst ein MessageTemplate-Objekt mit den Werten für eine Vorlage.

Hinweis

Informationen zum Überprüfen der verfügbaren Vorlagen finden Sie in den Anweisungen unter Auflisten von Vorlagen. Wenn Sie keine Vorlage verwenden können, fahren Sie mit Option 2 fort.

Im folgenden Beispiel wird ein MessageTemplate-Objekt mithilfe der Standardvorlage sample_template erstellt.
Wenn sample_template Ihnen nicht zur Verfügung steht, fahren Sie mit Option 2 fort. Informationen zum Senden einer anderen Vorlage mit Option 1 finden Sie auf der Seite Vorlagen.

Mit dem Nachrichten-SDK kann Contoso vorlagenbasierte WhatsApp-Nachrichten an WhatsApp-Benutzer senden. Zum Senden von Vorlagen sind folgende Angaben erforderlich:

// Assemble the template content
const template = {
    name: "sample_template",
    language: "en_US"
};

Weitere Beispiele zum Zusammenstellen von MessageTemplate und zum Erstellen einer eigenen Vorlage finden Sie in der folgenden Ressource:

Weitere WhatsApp-Anforderungen für Vorlagen finden Sie in den Referenzen zur WhatsApp Business-Platform-API:

// Send template message
const templateMessageResult = await client.path("/messages/notifications:send").post({
    contentType: "application/json",
    body: {
        channelRegistrationId: channelRegistrationId,
        to: recipientList,
        kind: "template",
        template: template
    }
});

// Process result
if (templateMessageResult.status === "202") {
    templateMessageResult.body.receipts.forEach((receipt) => {
        console.log("Message sent to:"+receipt.to+" with message id:"+receipt.messageId);
    });
} else {
    throw new Error("Failed to send message");
}

Nun müssen die Benutzer auf die Vorlagennachricht antworten. Antworten Sie über das WhatsApp-Benutzerkonto auf die Nachrichtenvorlage, die vom WhatsApp Business-Konto empfangen wurde. Der Inhalt dieser Nachricht ist hierfür irrelevant.

Wichtig

Der Empfänger muss auf die Nachrichtenvorlage antworten, um die Unterhaltung zu initiieren, bevor Text- oder Mediennachrichten an den Empfänger übermittelt werden können.

(Option 2) Initiieren einer Unterhaltung durch Benutzer*innen

Als zweite Möglichkeit kann eine Unterhaltung zwischen einem WhatsApp Business-Konto und WhatsApp-Benutzer*innen durch die Benutzer*innen initiiert werden. Senden Sie dazu aus Ihrem persönlichen WhatsApp-Konto eine Nachricht an Ihre Geschäftsnummer (Sender-ID).

Eine im Web angezeigte WhatsApp-Konversation mit einer Nutzernachricht, die an die Nummer des WhatsApp-Business-Kontos gesendet wurde.

Senden einer Textnachricht an WhatsApp-Benutzer

Messages SDK ermöglicht Contoso das Senden von WhatsApp-Textnachrichten, die von WhatsApp-Nutzern initiiert wurden. Zum Senden von Textnachrichten sind die folgenden Angaben erforderlich:

Wichtig

Um eine SMS an einen WhatsApp-Benutzer zu senden, muss der WhatsApp-Benutzer zuerst eine Nachricht an das WhatsApp Business-Konto senden. Weitere Informationen finden Sie unter Einrichten des Nachrichtenversands zwischen Unternehmens- und WhatsApp-Benutzer*innen.

In diesem Beispiel antworten wir dem WhatsApp-Benutzer mit dem Text: „Danke für Ihre Rückmeldung..\n Von Notification Messaging SDK“.

Stellen Sie die Mediennachricht zusammen, und senden Sie sie:

// Send text message
const textMessageResult = await client.path("/messages/notifications:send").post({
    contentType: "application/json",
    body: {
        channelRegistrationId: channelRegistrationId,
        to: recipientList,
        kind: "text",
        content: "Thanks for your feedback.\n From Notification Messaging SDK"
    }
});

// Process result
if (textMessageResult.status === "202") {
    textMessageResult.body.receipts.forEach((receipt) => {
        console.log("Message sent to:"+receipt.to+" with message id:"+receipt.messageId);
    });
} else {
    throw new Error("Failed to send message");
}

Senden einer Mediennachricht an WhatsApp-Benutzer

Mit dem Nachrichten-SDK kann Contoso Bild-WhatsApp-Nachrichten an WhatsApp-Benutzer senden. Zum Senden eingebetteter Bildnachrichten sind die folgenden Angaben erforderlich:

Wichtig

Um eine SMS an einen WhatsApp-Benutzer zu senden, muss der WhatsApp-Benutzer zuerst eine Nachricht an das WhatsApp Business-Konto senden. Weitere Informationen finden Sie unter Einrichten des Nachrichtenversands zwischen Unternehmens- und WhatsApp-Benutzer*innen.

Stellen Sie zum Senden einer Mediennachricht eine URL zu einem Bild bereit. Beispiel:

const url = "https://aka.ms/acsicon1";

Stellen Sie die Mediennachricht zusammen, und senden Sie sie:

// Send media message
const mediaMessageResult = await client.path("/messages/notifications:send").post({
    contentType: "application/json",
    body: {
        channelRegistrationId: channelRegistrationId,
        to: recipientList,
        kind: "image",
        mediaUri: url
    }
});

// Process result
if (mediaMessageResult.status === "202") {
    mediaMessageResult.body.receipts.forEach((receipt) => {
        console.log("Message sent to:"+receipt.to+" with message id:"+receipt.messageId);
    });
} else {
    throw new Error("Failed to send message");
}

Ausführen des Codes

Verwenden Sie den node-Befehl, um den Code auszuführen, den Sie der Datei „send-messages.js“ hinzugefügt haben.

node ./send-messages.js

Vollständiger Beispielcode

Sie können die Beispiel-App von GitHub herunterladen.

Voraussetzungen

Einrichten

Erstellen einer neuen Python-Anwendung

Erstellen Sie in einem Terminal- oder Konsolenfenster einen neuen Ordner für Ihre Anwendung, und navigieren Sie zu diesem Verzeichnis.

mkdir messages-quickstart && cd messages-quickstart

Installieren des Pakets

Sie müssen die Azure Communication Messages-Clientbibliothek für Räume für Python Version 1.0.0 oder höher verwenden.

Führen Sie in der Konsolen-Eingabeaufforderung den folgenden Befehl aus:

pip install azure-communication-messages

Einrichten des App-Frameworks

Erstellen Sie eine neue Datei namens messages-quickstart.py, und fügen Sie die grundlegende Programmstruktur hinzu.

type nul > messages-quickstart.py

Basic Programmstruktur

import os

class MessagesQuickstart(object):
    print("Azure Communication Services - Advanced Messages SDK Quickstart")

if __name__ == '__main__':
    messages = MessagesQuickstart()

Objektmodell

Die folgenden Klassen und Schnittstellen dienen zur Behandlung einiger der wichtigsten Features des Azure Communication Services Messages SDK für Python.

Name Beschreibung
NotificationMessagesClient Diese Klasse stellt eine Verbindung mit Ihrer Azure Communication Services-Ressource her. Sie sendet die Nachrichten.
MessageTemplate Diese Klasse definiert, welche Vorlage Sie verwenden, und den Inhalt der Vorlageneigenschaften für Ihre Nachricht.
TemplateNotificationContent Diese Klasse definiert das „Wer“ und das „Was“ der Vorlagennachricht, die Sie senden möchten.
TextNotificationContent Diese Klasse definiert das „Wer“ und das „Was“ der Textnachricht, die Sie senden möchten.
ImageNotificationContent Diese Klasse definiert das „Wer“ und das „Was“ der Bildmediennachricht, die Sie senden möchten.

Codebeispiele

Führen Sie die folgenden Schritte aus, um dem Python-Programm messages-quickstart.py die erforderlichen Codeschnipsel hinzuzufügen.

Authentifizieren des Clients

Das Senden von Nachrichten erfolgt mithilfe von NotificationMessagesClient. NotificationMessagesClient wird mit Ihrer Verbindungszeichenfolge authentifiziert, die von einer Azure Communication Services-Ressource im Azure-Portal abgerufen wird. Weitere Informationen zu Verbindungszeichenfolgen finden Sie unter access-your-connection-strings-and-service-endpoints.

Rufen Sie die Azure Communication Resource-Verbindungszeichenfolge aus dem Azure-Portal ab, wie im Screenshot angegeben. Navigieren Sie auf der linken Seite zur Keys-Registerkarte. Kopieren Sie das Feld Connection string für den Primärschlüssel. Die Verbindungszeichenfolge hat das Format endpoint=https://{your Azure Communication Services resource name}.communication.azure.com/;accesskey={secret key}.

Screenshot einer Azure Communication Services-Ressource im Azure-Portal, die das Feld „Primärschlüssel“ im Abschnitt „Schlüssel“ anzeigt.

Legen Sie die Umgebungsvariable COMMUNICATION_SERVICES_CONNECTION_STRING auf den Wert Ihrer Verbindungszeichenfolge fest.
Öffnen Sie ein Konsolenfenster, und geben Sie den folgenden Befehl ein:

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

Nachdem Sie die Umgebungsvariable hinzugefügt haben, müssen Sie unter Umständen alle ausgeführten Programme neu starten, die die Umgebungsvariable lesen müssen, z. B. das Konsolenfenster. Wenn Sie beispielsweise Visual Studio als Editor verwenden, müssen Sie Visual Studio neu starten, bevor Sie das Beispiel ausführen.

Weitere Informationen zum Festlegen einer Umgebungsvariablen für Ihr System finden Sie in den Schritten unter Speichern der Verbindungszeichenfolge in einer Umgebungsvariablen.

    # Get a connection string to our Azure Communication Services resource.
    connection_string = os.getenv("COMMUNICATION_SERVICES_CONNECTION_STRING")
    
    def send_template_message(self):
        from azure.communication.messages import NotificationMessagesClient

        # Create NotificationMessagesClient Client
        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)

Festlegen der Kanalregistrierungs-ID

Die GUID der Kanalregistrierungs-ID wurde während der Kanalregistrierung erstellt. Sie können diese auf der Registerkarte „Kanäle“ im Portal Ihrer Azure Communication Services-Ressource finden.

Screenshot einer Azure Communication Services-Ressource im Azure-Portal, auf der die Registerkarte „Kanäle“ angezeigt wird. Besonderes Augenmerk wird auf die Kopierfunktion des Feldes „Kanal-ID“ gelegt.

Weisen Sie diese der Variablen „channelRegistrationId“ zu.

    channelRegistrationId = os.getenv("WHATSAPP_CHANNEL_ID_GUID")

Festlegen der Empfängerliste

Sie müssen eine echte Telefonnummer angeben, die einem WhatsApp-Konto zugeordnet ist. Dieses WhatsApp-Konto empfängt die Vorlagen-, Text- und Mediennachrichten, die in diesem Schnellstart gesendet werden. Für diesen Schnellstart können Sie Ihre persönliche Telefonnummer verwenden.

Die Empfängertelefonnummer kann nicht die geschäftliche Telefonnummer (Sender-ID) sein, die der WhatsApp-Kanalregistrierung zugeordnet ist. Die Sender-ID wird als Sender der Text- und Mediennachrichten angezeigt, die an den Empfänger gesendet werden.

Die Telefonnummer sollte die Landeskennzahl beinhalten. Weitere Informationen zur Formatierung von Telefonnummern finden Sie in der WhatsApp-Dokumentation für Telefonnummernformate.

Hinweis

In der Empfängerliste wird derzeit lediglich eine Telefonnummer unterstützt.

Legen Sie die Empfängerliste folgendermaßen fest:

    phone_number = os.getenv("RECIPIENT_WHATSAPP_PHONE_NUMBER")

Anwendungsbeispiel:

    # Example only
    to=[self.phone_number],

Einrichten des Nachrichtenversands zwischen Geschäfts- und WhatsApp-Benutzern

Unterhaltungen zwischen einem WhatsApp Business-Konto und WhatsApp-Benutzer*innen kann auf eine von zwei Arten initiiert werden:

  • Das Unternehmen sendet eine Nachrichtenvorlage an die WhatsApp-Benutzer*innen.
  • Die WhatsApp-Benutzer*innen senden eine beliebige Nachricht an die Geschäftsnummer.

Unabhängig davon, wie die Unterhaltung gestartet wurde, kann ein Unternehmen Vorlagennachrichten nur senden, bis der Benutzer eine Nachricht an das Unternehmen sendet. Erst nachdem der Benutzer eine Nachricht an das Unternehmen gesendet hat, darf das Unternehmen während der aktiven Unterhaltung Text- oder Mediennachrichten an den Benutzer senden. Nach Ablauf des 24-Stunden-Fensters muss die Unterhaltung erneut eingeleitet werden. Weitere Informationen zu Unterhaltungen finden Sie in der Definition auf der WhatsApp Business-Platform.

(Option 1) Initiieren einer Unterhaltung durch das Unternehmen durch das Senden einer Vorlagennachricht

Initiieren Sie eine Unterhaltung, indem Sie eine Nachrichtenvorlage senden.

Erstellen Sie zunächst ein MessageTemplate-Objekt mit den Werten für eine Vorlage.

Hinweis

Informationen zum Überprüfen der verfügbaren Vorlagen finden Sie in den Anweisungen unter Auflisten von Vorlagen. Wenn Sie keine Vorlage verwenden können, fahren Sie mit Option 2 fort.

Im folgenden Beispiel wird ein MessageTemplate-Objekt mithilfe der Standardvorlage sample_template erstellt.
Wenn sample_template Ihnen nicht zur Verfügung steht, fahren Sie mit Option 2 fort. Informationen zum Senden einer anderen Vorlage mit Option 1 finden Sie auf der Seite Vorlagen.

Mit dem Nachrichten-SDK kann Contoso vorlagenbasierte WhatsApp-Nachrichten an WhatsApp-Benutzer senden. Zum Senden von Vorlagen sind folgende Angaben erforderlich:

Weitere Beispiele zum Zusammenstellen von MessageTemplate und zum Erstellen einer eigenen Vorlage finden Sie in der folgenden Ressource:

Weitere WhatsApp-Anforderungen für Vorlagen finden Sie in den Referenzen zur WhatsApp Business-Platform-API:

Fügen Sie den folgenden Code in die Funktion send_template_message(self) ein, um eine WhatsApp-Vorlagennachricht zu senden.

        input_template: MessageTemplate = MessageTemplate(
            name="<<template_name>>",
            language="<<template_language>>")
        template_options = TemplateNotificationContent(
            channel_registration_id=self.channelRegistrationId,
            to=[self.phone_number],
            template=input_template
        )

        # calling send() with whatsapp template details
        message_responses = messaging_client.send(template_options)
        response = message_responses.receipts[0]
        
        if (response is not None):
            print("WhatsApp Templated Message with message id {} was successfully sent to {}."
            .format(response.message_id, response.to))
        else:
            print("Message failed to send")

Fügen Sie den Aufruf send_template_message() zu der Hauptmethode hinzu.

    # Calling send_template_message()
    messages.send_template_message()

Nun müssen die Benutzer auf die Vorlagennachricht antworten. Antworten Sie über das WhatsApp-Benutzerkonto auf die Nachrichtenvorlage, die vom WhatsApp Business-Konto empfangen wurde. Der Inhalt dieser Nachricht ist hierfür irrelevant.

Wichtig

Der Empfänger muss auf die Nachrichtenvorlage antworten, um die Unterhaltung zu initiieren, bevor Text- oder Mediennachrichten an den Empfänger übermittelt werden können.

(Option 2) Initiieren einer Unterhaltung durch Benutzer*innen

Als zweite Möglichkeit kann eine Unterhaltung zwischen einem WhatsApp Business-Konto und WhatsApp-Benutzer*innen durch die Benutzer*innen initiiert werden. Senden Sie dazu aus Ihrem persönlichen WhatsApp-Konto eine Nachricht an Ihre Geschäftsnummer (Sender-ID).

Eine im Web angezeigte WhatsApp-Konversation mit einer Nutzernachricht, die an die Nummer des WhatsApp-Business-Kontos gesendet wurde.

Senden einer Textnachricht an WhatsApp-Benutzer

Messages SDK ermöglicht Contoso das Senden von WhatsApp-Textnachrichten, die von WhatsApp-Nutzern initiiert wurden. Zum Senden von Textnachrichten sind die folgenden Angaben erforderlich:

Wichtig

Um eine SMS an einen WhatsApp-Benutzer zu senden, muss der WhatsApp-Benutzer zuerst eine Nachricht an das WhatsApp Business-Konto senden. Weitere Informationen finden Sie unter Einrichten des Nachrichtenversands zwischen Unternehmens- und WhatsApp-Benutzer*innen.

In diesem Beispiel antworten wir dem WhatsApp-Benutzer mit dem Text: „Danke für Ihre Rückmeldung..\n Von Notification Messaging SDK“.

    def send_text_message(self):
        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import ( TextNotificationContent)

        # Create NotificationMessagesClient Client
        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)
        text_options = TextNotificationContent (
            channel_registration_id=self.channelRegistrationId,
            to= [self.phone_number],
            content="Thanks for your feedback.\n From Notification Messaging SDK",
        )
        
        # calling send() with whatsapp message details
        message_responses = messaging_client.send(text_options)
        response = message_responses.receipts[0]
        
        if (response is not None):
            print("WhatsApp Text Message with message id {} was successfully sent to {}."
            .format(response.message_id, response.to))
        else:
            print("Message failed to send")

Aktualisieren der Hauptmethode zum Ausführen von send_text_message()

    #Calling send_text_message()
    messages.send_text_message()

Senden einer Mediennachricht an WhatsApp-Benutzer

Mit dem Nachrichten-SDK kann Contoso Bild-WhatsApp-Nachrichten an WhatsApp-Benutzer senden. Zum Senden eingebetteter Bildnachrichten sind die folgenden Angaben erforderlich:

Wichtig

Um eine SMS an einen WhatsApp-Benutzer zu senden, muss der WhatsApp-Benutzer zuerst eine Nachricht an das WhatsApp Business-Konto senden. Weitere Informationen finden Sie unter Einrichten des Nachrichtenversands zwischen Unternehmens- und WhatsApp-Benutzer*innen.

Ein Beispiel für eine media_uri, die beim Versenden von WhatsApp-Mediennachrichten verwendet wird.

input_media_uri: str = "https://aka.ms/acsicon1"

    def send_image_message(self):
        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import ( ImageNotificationContent)

        # Create NotificationMessagesClient Client
        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)
        input_media_uri: str = "https://aka.ms/acsicon1"
        image_message_options = ImageNotificationContent(
            channel_registration_id=self.channelRegistrationId,
            to=[self.phone_number],
            media_uri=input_media_uri
        )

        # calling send() with whatsapp image message
        message_responses = messaging_client.send(image_message_options)
        response = message_responses.receipts[0]
        
        if (response is not None):
            print("WhatsApp Image containing Message with message id {} was successfully sent to {}"
            .format(response.message_id, response.to))
        else:
            print("Message failed to send")

Aktualisieren der Hauptmethode zum Ausführen von send_image_message()

    # Calling send_image_message()
    messages.send_image_message()

Ausführen des Codes

Vergewissern Sie sich, dass Sie sich in dem Verzeichnis befinden, in dem sich die messages-quickstart.py-Datei befindet, um den Code auszuführen.

python messages-quickstart.py

Azure Communication Services - Advanced Messages Quickstart
WhatsApp Templated Message with message id <<GUID>> was successfully sent to <<ToRecipient>>
WhatsApp Text Message with message id <<GUID>> was successfully sent to <<ToRecipient>>
WhatsApp Image containing Message with message id <<GUID>> was successfully sent to <<ToRecipient>>

Vollständiger Beispielcode

import os

class MessagesQuickstart(object):
    print("Azure Communication Services - Advanced Messages SDK Quickstart using connection string.")
    # Advanced Messages SDK implementations goes in this section.
   
    connection_string = os.getenv("COMMUNICATION_SERVICES_CONNECTION_STRING")
    phone_number = os.getenv("RECIPIENT_PHONE_NUMBER")
    channelRegistrationId = os.getenv("WHATSAPP_CHANNEL_ID")

    def send_template_message(self):
        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import ( TemplateNotificationContent , MessageTemplate )

        # client creation
        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)
        input_template: MessageTemplate = MessageTemplate(
            name="<<TEMPLATE_NAME>>",
            language="<<LANGUAGE>>")
        template_options = TemplateNotificationContent(
            channel_registration_id=self.channelRegistrationId,
            to=[self.phone_number],
            template=input_template
        )

        # calling send() with WhatsApp template details.
        message_responses = messaging_client.send(template_options)
        response = message_responses.receipts[0]
        
        if (response is not None):
            print("WhatsApp Templated Message with message id {} was successfully sent to {}"
            .format(response.message_id, response.to))
        else:
            print("Message failed to send")

    def send_text_message(self):
        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import ( TextNotificationContent )

        # client creation
        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)

        text_options = TextNotificationContent (
            channel_registration_id=self.channelRegistrationId,
            to= [self.phone_number],
            content="Hello World via ACS Advanced Messaging SDK.",
        )
        
        # calling send() with WhatsApp message details
        message_responses = messaging_client.send(text_options)
        response = message_responses.receipts[0]
        
        if (response is not None):
            print("WhatsApp Text Message with message id {} was successfully sent to {}"
            .format(response.message_id, response.to))
        else:
            print("Message failed to send")

    def send_image_message(self):
        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import ( ImageNotificationContent)

        # Create NotificationMessagesClient Client
        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)
        input_media_uri: str = "https://aka.ms/acsicon1"
        image_message_options = ImageNotificationContent(
            channel_registration_id=self.channelRegistrationId,
            to=[self.phone_number],
            media_uri=input_media_uri
        )

        # calling send() with whatsapp image message
        message_responses = messaging_client.send(image_message_options)
        response = message_responses.receipts[0]
        
        if (response is not None):
            print("WhatsApp Image containing Message with message id {} was successfully sent to {}"
            .format(response.message_id, response.to))
        else:
            print("Message failed to send")

if __name__ == '__main__':
    messages = MessagesQuickstart()
    messages.send_template_message()
    messages.send_text_message()
    messages.send_image_message()

Weitere Beispiele

Sie können andere Beispielcodes für Python Messages SDK auf GitHub überprüfen und herunterladen.

Nächste Schritte

In diesem Schnellstart haben Sie erweitertes Messaging für das WhatsApp-SDK ausprobiert. Die folgenden Artikel könnten ebenfalls hilfreich sein: