你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：下载 WhatsApp 消息媒体

2025-05-01

Azure 通信服务让你能够发送和接收 WhatsApp 消息。本文介绍如何下载 WhatsApp 消息中收到的媒体有效负载。

用例：某家企业收到了客户发来的包含图像的 WhatsApp 消息。该商家需要从 WhatsApp 下载并查看该图像。

传入业务的消息作为 Microsoft.Communication.AdvancedMessageReceived 事件网格事件发布。此示例使用 AdvancedMessageReceived 事件中的媒体 ID 和媒体 MIME 类型来下载媒体有效负载。

带有媒体内容的 AdvancedMessageReceived 事件示例：

[{
  "id": "00000000-0000-0000-0000-000000000000",
  "topic": "/subscriptions/{subscription-id}/resourcegroups/{resourcegroup-name}/providers/microsoft.communication/communicationservices/{communication-services-resource-name}",
  "subject": "advancedMessage/sender/{sender@id}/recipient/11111111-1111-1111-1111-111111111111",
  "data": {
    "channelType": "whatsapp",
    "media": {
      "mimeType": "image/jpeg",
      "id": "22222222-2222-2222-2222-222222222222"
    },
    "from": "{sender@id}",
    "to": "11111111-1111-1111-1111-111111111111",
    "receivedTimestamp": "2023-07-06T18:30:19+00:00"
  },
  "eventType": "Microsoft.Communication.AdvancedMessageReceived",
  "dataVersion": "1.0",
  "metadataVersion": "1",
  "eventTime": "2023-07-06T18:30:22.1921716Z"
}]

先决条件

注册到 Azure 通信服务资源的 WhatsApp Business 帐户。
.NET 开发环境，如 Visual Studio、Visual Studio Code 或 .NET CLI。
事件订阅和高级消息接收事件的处理。

设置环境

创建 .NET 项目

若要创建项目，请按照使用 Visual Studio 创建 .NET 控制台应用程序的教程进行操作。

若要编译代码，请按 Ctrl+F7。

若要创建项目，请按照使用 Visual Studio Code 创建 .NET 控制台应用程序的教程进行操作。

通过在 Visual Studio Code 终端（“查看”>“终端”）中运行以下命令来生成和运行程序。

dotnet build
dotnet run

创建项目。

dotnet new console -o AdvancedMessagingQuickstart

导航到项目目录并生成项目。

cd AdvancedMessagingQuickstart
dotnet build

安装包

将 Azure.Communication.Messages NuGet 包安装到你的 C# 项目。

打开 NuGet 包管理器：Project>Manage NuGet Packages...。
搜索包 Azure.Communication.Messages。
安装最新版本。

打开 Visual Studio Code 终端 ( View>Terminal )。
运行以下命令来安装包。

dotnet add package Azure.Communication.Messages

运行以下命令来安装包。

dotnet add package Azure.Communication.Messages

设置应用框架

在文本编辑器中打开 Program.cs 文件。

使用以下代码替换 Program.cs 的内容：

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 - Advanced Messages quickstart samples.");

            // Quickstart code goes here
        }
    }
}

若要使用高级消息传递功能，请添加一个 using 指令以包含 Azure.Communication.Messages 命名空间。

using Azure.Communication.Messages;

对象模型

以下类和接口处理适用于 .NET 的 Azure 通信服务高级消息传送 SDK 的某些主要功能。

名称	描述
NotificationMessagesClient	此类连接到你的 Azure 通信服务资源。它会发送消息。
DownloadMediaAsync	异步下载用户到企业消息中的媒体有效负载，并将内容写入流中。
DownloadMediaToAsync	异步下载用户到企业消息中的媒体有效负载，并将内容写入文件中。
Microsoft.Communication.AdvancedMessageReceived	高级消息传递收到消息时发布的事件网格事件。

通用配置

按照以下步骤将所需的代码片段添加到 messages-quickstart.py python 程序。

开始在企业和 WhatsApp 用户之间发送消息。
对客户端进行身份验证
设置频道注册 ID
设置收件人列表

对客户端进行身份验证

消息 SDK 使用 NotificationMessagesClient 发送消息。 NotificationMessagesClient 方法使用从 Microsoft Azure 门户中的 Azure 通信服务资源获取的连接字符串进行身份验证。有关连接字符串的详细信息，请参阅访问连接字符串和服务终结点。

为简单起见，本文使用连接字符串进行身份验证。在生产环境中，我们建议使用服务主体。

从 Azure 门户中的 Azure 通信服务资源获取连接字符串。在左侧，导航到“Keys”选项卡。复制主键的 Connection string 字段。连接字符串采用 endpoint=https://{your Azure Communication Services resource name}.communication.azure.com/;accesskey={secret key} 格式。

将环境变量 COMMUNICATION_SERVICES_CONNECTION_STRING 设置为连接字符串的值。
打开控制台窗口并输入以下命令：

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

添加环境变量后，可能需要重启任何正在运行的、需要读取环境变量的程序（包括控制台窗口）。例如，如果使用 Visual Studio 作为编辑器，请在运行示例之前重启 Visual Studio。

有关如何为系统设置环境变量的详细信息，请按照在环境变量中存储连接字符串的步骤操作。

若要实例化 NotificationMessagesClient，请将以下代码添加到 Main 方法：

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

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

还可以使用 Azure 标识库对 Microsoft Entra ID 进行身份验证。

Azure.Identity 包提供应用程序可用于身份验证的各种凭据类型。可以选择各种选项来对标识进行身份验证：Azure 标识 - 凭据提供程序和 Azure 标识 - 对客户端进行身份验证。此选项将演示一种使用 DefaultAzureCredential 的方法。

DefaultAzureCredential 会尝试通过 several mechanisms 进行身份验证，如果你登录到了 Visual Studio 或 Azure CLI，它可以获取其身份验证凭据。但是，此选项将引导你完成使用环境变量的设置。

若要创建 DefaultAzureCredential 对象，请执行以下操作：

若要设置服务主体应用，请按照创建 Microsoft Entra 注册的应用程序的说明进行操作。
使用你的应用的创建的输出设置环境变量 AZURE_CLIENT_ID、AZURE_CLIENT_SECRET 和 AZURE_TENANT_ID。
打开控制台窗口并输入以下命令：
```
setx AZURE_CLIENT_ID "<your app's appId>"
setx AZURE_CLIENT_SECRET "<your app's password>"
setx AZURE_TENANT_ID "<your app's tenant>"
```
添加环境变量后，可能需要重启任何正在运行的、需要读取环境变量的程序（包括控制台窗口）。例如，如果使用 Visual Studio 作为编辑器，请在运行示例之前重启 Visual Studio。
若要使用 Azure SDK 提供的 DefaultAzureCredential 提供程序或其他凭据提供程序，请安装 Azure.Identity NuGet 包并将以下 using 指令添加到你的 Program.cs 文件。
```
using Azure.Identity;
```

若要实例化 NotificationMessagesClient，请将以下代码添加到 Main 方法。

// Configure authentication
var endpoint = new Uri("https://<resource name>.communication.azure.com");
var credential = new DefaultAzureCredential();

// Instantiate the client
var notificationMessagesClient = 
    new NotificationMessagesClient(endpoint, credential);

还可以使用 AzureKeyCredential 进行身份验证。

从 Azure 门户中的 Azure 通信服务资源获取终结点和密钥。在左侧，导航到“Keys”选项卡。复制主键的 Endpoint 和 Key 字段。

将环境变量 COMMUNICATION_SERVICES_KEY 设置为连接字符串的值。
打开控制台窗口并输入以下命令：

setx COMMUNICATION_SERVICES_KEY "<your key>"

有关如何为系统设置环境变量的详细信息，请按照在环境变量中存储连接字符串的步骤操作。

若要实例化 NotificationMessagesClient，请将以下代码添加到 Main 方法：

// Retrieve key from environment variable
string key = 
    Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_KEY");

// Configure authentication
var endpoint = new Uri("https://<resource name>.communication.azure.com");
var credential = new AzureKeyCredential(key);

// Instantiate the client
var notificationMessagesClient = 
    new NotificationMessagesClient(endpoint, credential);

设置频道注册 ID

你已在频道注册期间创建了频道注册 ID GUID。在门户中 Azure 通信服务资源的“频道”选项卡中可以找到它。

将它分配给名为 channelRegistrationId 的变量。

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

设置收件人列表

需要提供与 WhatsApp 帐户关联的有效电话号码。此 WhatsApp 帐户会接收本快速入门中发送的模版、文本和媒体消息。

对于此示例，可以使用个人电话号码。

收件人电话号码不能是与 WhatsApp 频道注册关联的业务电话号码（发件人 ID）。发件人 ID 显示为发送给收件人的文本和媒体消息的发件人。

电话号码必须包括国家/地区代码。有关电话号码格式的详细信息，请查看 WhatsApp 文档中的电话号码格式。

注意

收件人列表中当前仅支持一个电话号码。

创建如下所示的收件人列表：

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

示例：

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

开始在企业和 WhatsApp 用户之间发送消息

可通过下面两种方式之一发起 WhatsApp Business 帐户与 WhatsApp 用户之间的对话：

企业向 WhatsApp 用户发送模板消息。
WhatsApp 用户向企业号码发送任何消息。

企业无法发起交互式对话。企业只能在收到用户的消息后发送交互式消息。企业只能在活动对话过程中向用户发送交互式消息。一旦 24 小时对话窗口过期，只有用户才能重新开始交互式对话。有关对话的详细信息，请访问 WhatsApp Business 平台查看定义。

若要从个人 WhatsApp 帐户发起交互式对话，请向企业号码（发送方 ID）发送消息。

代码示例

按照以下步骤将所需的代码片段添加到 Program.cs 文件的 Main 函数中。

将媒体有效负载下载到流中
将媒体有效负载下载到文件中

将媒体有效负载下载到流中

消息 SDK 使 Contoso 能够下载从 WhatsApp 用户收到的 WhatsApp 媒体消息中的媒体。若要将媒体有效负载下载到流中，需要：

经过身份验证的 NotificationMessagesClient。
媒体的媒体 ID GUID（从 AdvancedMessageReceived 事件中的传入消息接收）。

定义要提取的媒体的媒体 ID。

// MediaId GUID of the media received in an incoming message.
// Ex. "00000000-0000-0000-0000-000000000000"
var mediaId = "<MediaId>";

将媒体下载到目标流中。

// Download media to stream
Response<Stream> fileResponse = await notificationMessagesClient.DownloadMediaAsync(mediaId);

媒体有效负载现在可在响应流中使用。

继续学习此示例，将流写入文件中。

有效负载的媒体 ID 和 MIME 类型可在 AdvancedMessageReceived 事件的媒体内容中找到。但是，将媒体下载到流时，可以在 Response<Stream> 中的响应标头中再次找到 MIME 类型。

无论哪种情况，都需要将 MIME 类型转换为文件类型。定义此帮助程序来进行转换。

private static string GetFileExtension(string contentType)
{
    return MimeTypes.TryGetValue(contentType, out var extension) ? extension : string.Empty;
}

private static readonly Dictionary<string, string> MimeTypes = new Dictionary<string, string>
{
    { "application/pdf", ".pdf" },
    { "image/jpeg", ".jpg" },
    { "image/png", ".png" },
    { "video/mp4", ".mp4" },
    // Add more mappings as needed
};

定义要写入媒体的文件位置。此示例使用来自 DownloadMediaAsync 的响应标头中返回的 MIME 类型。

// File extension derived from the MIME type in the response headers.
// Ex. A MIME type of "image/jpeg" would mean the fileExtension should be ".jpg"
var contentType = fileResponse.GetRawResponse().Headers.ContentType;
string fileExtension = GetFileExtension(contentType);

// File location to write the media. 
// Ex. @"c:\temp\media.jpg"
string filePath = @"<FilePath>" + "<FileName>" + fileExtension;

将流写入文件中。

 // Write the media stream to the file
using (Stream outStream = File.OpenWrite(filePath))
{
    fileResponse.Value.CopyTo(outStream);
}

将媒体有效负载下载到文件中

消息 SDK 使 Contoso 能够下载从 WhatsApp 用户收到的 WhatsApp 媒体消息中的媒体。若要将媒体有效负载下载到文件中，需要：

经过身份验证的 NotificationMessagesClient。
媒体的媒体 ID GUID（从 AdvancedMessageReceived 事件中的传入消息接收）。
媒体文件扩展名，从具有媒体内容的传入消息中接收的 MIME 类型派生。
所选的目标文件名。
所选的目标文件路径。

定义你要提取的媒体的媒体 ID，以及想要写入媒体的文件位置。

// MediaId GUID of the media received in an incoming message.
// Ex. "00000000-0000-0000-0000-000000000000"
var mediaId = "<MediaId>";

// File extension derived from the MIME type received in an incoming message
// Ex. A MIME type of "image/jpeg" would mean the fileExtension should be ".jpg"
string fileExtension = "<FileExtension>";
// File location to write the media. 
// Ex. @"c:\temp\media.jpg"
string filePath = @"<FilePath>" + "<FileName>" + fileExtension;

将媒体下载到目标路径中。

// Download media to file
Response response = await notificationMessagesClient.DownloadMediaToAsync(mediaId, filePath);

运行代码

构建程序并运行。

若要编译代码，请按 Ctrl+F7。
要运行程序而不进行调试，请按 Ctrl+F5。

在 Visual Studio Code 终端（“视图”“终端”）中生成并运行程序>。

dotnet build
dotnet run

构建程序并运行。

dotnet build
dotnet run

完整示例代码

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

namespace AdvancedMessagingDownloadMediaQuickstart
{
    class Program
    {
        public static async Task Main(string[] args)
        {
            Console.WriteLine("Azure Communication Services - Download WhatsApp message media");

            // Authenticate the client
            string connectionString = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_CONNECTION_STRING");
            NotificationMessagesClient notificationMessagesClient =
                new NotificationMessagesClient(connectionString);

            await DownloadMediaWithStreamAsync(notificationMessagesClient);
            await DownloadMediaToFileAsync(notificationMessagesClient);

            Console.WriteLine("\n\nPress any key to exit.");
            Console.ReadKey();
        }

        public static async Task DownloadMediaWithStreamAsync(NotificationMessagesClient notificationMessagesClient)
        {
            // MediaId GUID of the media received in an incoming message.
            // Ex. "00000000-0000-0000-0000-000000000000"
            var mediaId = "<MediaId>";

            Response<Stream> fileResponse;
            try
            {
                // Download media to stream
                fileResponse = await notificationMessagesClient.DownloadMediaAsync(mediaId);

                Console.WriteLine(fileResponse.ToString());
            }
            catch (RequestFailedException e)
            {
                Console.WriteLine(e);
                return;
            }

            // File extension derived from the MIME type in the response headers.
            // Ex. A MIME type of "image/jpeg" would mean the fileExtension should be ".jpg"
            var contentType = fileResponse.GetRawResponse().Headers.ContentType;
            string fileExtension = GetFileExtension(contentType);

            // File location to write the media. 
            // Ex. @"c:\temp\media.jpg"
            string filePath = @"<FilePath>" + "<FileName>" + fileExtension;
            Console.WriteLine(filePath);

            // Write the media stream to the file
            using (Stream outStream = File.OpenWrite(filePath))
            {
                fileResponse.Value.CopyTo(outStream);
            }
        }

        private static string GetFileExtension(string contentType)
        {
            return MimeTypes.TryGetValue(contentType, out var extension) ? extension : string.Empty;
        }

        private static readonly Dictionary<string, string> MimeTypes = new Dictionary<string, string>
        {
            { "application/pdf", ".pdf" },
            { "image/jpeg", ".jpg" },
            { "image/png", ".png" },
            { "video/mp4", ".mp4" },
            // Add more mappings as needed
        };

        public static async Task DownloadMediaToFileAsync(NotificationMessagesClient notificationMessagesClient)
        {
            // MediaId GUID of the media received in an incoming message.
            // Ex. "00000000-0000-0000-0000-000000000000"
            var mediaId = "<MediaId>";

            // File extension derived from the MIME type received in an incoming message
            // Ex. A MIME type of "image/jpeg" would mean the fileExtension should be ".jpg"
            string fileExtension = "<FileExtension>";

            // File location to write the media. 
            // Ex. @"c:\temp\media.jpg"
            string filePath = @"<FilePath>" + "<FileName>" + fileExtension;
            Console.WriteLine(filePath);

            try
            {
                // Download media to file
                Response response = await notificationMessagesClient.DownloadMediaToAsync(mediaId, filePath);

                Console.WriteLine(response.ToString());
            }
            catch (RequestFailedException e)
            {
                Console.WriteLine(e);
                return;
            }
        }
    }
}

先决条件

设置环境

若要设置用于发送消息的环境，请完成以下步骤。

创建新的 Java 应用程序

打开终端或命令窗口，并导航到要在其中创建 Java 应用程序的目录。运行以下命令，从 maven-archetype-quickstart 模板生成 Java 项目。

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

generate 目标将创建一个名称与 artifactId 值相同的目录。在此目录下，src/main/java 目录包含项目源代码，src/test/java 目录包含测试源，pom.xml 文件是项目的项目对象模型 (POM)。

安装包

在文本编辑器中打开 pom.xml 文件pom.xml。将以下依赖项元素添加到依赖项组。

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

设置应用框架

在文本编辑器中打开 /src/main/java/com/communication/quickstart/App.java，添加 import 指令并删除 System.out.println("Hello world!"); 语句：

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

对象模型

以下类和接口处理适用于 Java 的 Azure 通信服务高级消息传送 SDK 的某些主要功能。

名称	描述
NotificationMessagesClient	此类连接到你的 Azure 通信服务资源。它会发送消息。
DownloadMediaAsync	异步下载用户到企业消息中的媒体有效负载，并将内容写入流中。
Microsoft.Communication.AdvancedMessageReceived	高级消息传递收到消息时发布的事件网格事件。

注意

有关详细信息，请参阅 com.azure.communication.messages 包中的 Azure SDK for Java 参考内容。

通用配置

按照以下步骤将必要的代码片段添加到 App.java 文件的 main 函数。

开始在企业和 WhatsApp 用户之间发送消息。
对客户端进行身份验证
设置频道注册 ID
设置收件人列表

开始在企业和 WhatsApp 用户之间发送消息

可通过下面两种方式之一发起 WhatsApp Business 帐户与 WhatsApp 用户之间的对话：

企业向 WhatsApp 用户发送模板消息。
WhatsApp 用户向企业号码发送任何消息。

无论对话是如何启动的，在用户向企业发送消息之前，企业只能发送模板消息。只有在用户向企业发送消息后，企业才能在活动对话期间向用户发送文本或媒体消息。 24 小时对话窗口到期后，必须重新发起对话。若要了解有关对话的详细信息，请访问 WhatsApp Business 平台查看定义。

对客户端进行身份验证

可使用几个不同的选项对消息客户端进行身份验证：

若要对客户端进行身份验证，请使用连接字符串实例化 NotificationMessagesClient 或 MessageTemplateClient。还可以使用任何实现 com.azure.core.http.HttpClient 接口的自定义 HTTP 客户端来初始化此客户端。

为简单起见，本文使用连接字符串进行身份验证。在生产环境中，我们建议使用服务主体。

从 Azure 门户中的 Azure 通信服务资源获取连接字符串。在左侧，导航到“Keys”选项卡。复制 Connection string 的 Primary key 字段。连接字符串采用 endpoint=https://{your Azure Communication Services resource name}.communication.azure.com/;accesskey={secret key} 格式。

将环境变量 COMMUNICATION_SERVICES_CONNECTION_STRING 设置为连接字符串的值。
打开控制台窗口并输入以下命令：

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

有关如何为系统设置环境变量的详细信息，请按照在环境变量中存储连接字符串的步骤操作。

若要实例化 NotificationMessagesClient，请将以下代码添加到 main 方法：

// 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();

还可以使用 Azure 标识库对 Microsoft Entra ID 进行身份验证。

DefaultAzureCredential 会尝试通过 several mechanisms 进行身份验证，如果你登录到了 Visual Studio 或 Azure CLI，它可能能够找到其身份验证凭据。但是，此选项将引导你完成使用环境变量的设置。

若要创建 DefaultAzureCredential 对象，请执行以下操作：

若要设置服务主体应用，请按照创建 Microsoft Entra 注册的应用程序的说明进行操作。
使用你的应用的创建的输出设置环境变量 AZURE_CLIENT_ID、AZURE_CLIENT_SECRET 和 AZURE_TENANT_ID。
打开控制台窗口并输入以下命令：
```
setx AZURE_CLIENT_ID "<your app's appId>"
setx AZURE_CLIENT_SECRET "<your app's password>"
setx AZURE_TENANT_ID "<your app's tenant>"
```
添加环境变量后，可能需要重启任何正在运行的、需要读取环境变量的程序（包括控制台窗口）。例如，如果使用 Visual Studio 作为编辑器，请在运行示例之前重启 Visual Studio。
若要使用 DefaultAzureCredential 提供程序或随 Azure SDK 提供的其他凭据提供程序，请按照 azure-identity处的说明加入包。

若要实例化 NotificationMessagesClient，请将以下代码添加到 Main 方法。

String endpoint = "https://<resource name>.communication.azure.com/";
NotificationMessagesClient notificationClient =  new NotificationMessagesClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

必须通过方法将 ClientBuilder 对象传递给 credential()。还必须通过 endpoint() 方法设置终结点。

还可以使用终结点和从 Azure 门户中的 Azure 通信资源获取的 Azure 密钥凭据来创建 NotificationMessage 或 MessageTemplate 客户端并对其进行身份验证。

添加导入

import com.azure.core.credential.AzureKeyCredential;

若要实例化 NotificationMessagesClient，请将以下代码添加到 Main 方法。

String endpoint = "https://<resource name>.communication.azure.com";
AzureKeyCredential azureKeyCredential = new AzureKeyCredential("<access key>");
NotificationMessagesClient notificationClient = new NotificationMessagesClientBuilder()
    .endpoint(endpoint)
    .credential(azureKeyCredential)
    .buildClient();

设置频道注册 ID

频道注册 ID GUID 是在频道注册期间创建的。可在门户中，访问 Azure 通信服务资源的“频道”选项卡来查找它。

将它分配给名为 channelRegistrationId 的变量。

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

设置收件人列表

你需要提供一个与 WhatsApp 帐户关联的真实电话号码。此 WhatsApp 帐户接收本文中发送的文本和媒体消息。在本文中，此电话号码可以是你的个人电话号码。

收件人电话号码不能是与 WhatsApp 频道注册关联的业务电话号码（发件人 ID）。发件人 ID 显示为发送给收件人的文本和媒体消息的发件人。

电话号码应包括国家/地区代码。有关电话号码格式的详细信息，请查看 WhatsApp 文档中的电话号码格式。

注意

收件人列表中当前仅支持一个电话号码。

创建如下所示的收件人列表：

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

示例：

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

代码示例

按照以下步骤将所需的代码片段添加到 App.java 的 main 函数中。

将媒体有效负载下载到流中

将媒体有效负载下载到流中

消息 SDK 使 Contoso 能够下载从 WhatsApp 用户收到的 WhatsApp 媒体消息中的媒体。若要将媒体有效负载下载到流中，需要：

经过身份验证的 NotificationMessagesClient。
媒体的媒体 ID GUID（从 AdvancedMessageReceived 事件中的传入消息接收）。

    public static void main(String[] args) throws IOException {

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

        BinaryData data = messagesClient.downloadMedia("<MEDIA_ID>");
        BufferedImage image = ImageIO.read(data.toStream());
        ImageIcon icon = new ImageIcon(image);
        JLabel label  = new JLabel(icon);
        JFrame frame = new JFrame();
        frame.add(label);
        frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
        frame.pack();
        frame.setVisible(true);
    }

运行代码

打开包含 pom.xml 文件的目录，并使用 mvn 命令编译该项目。
```
mvn compile
```

通过执行以下 mvn 命令运行应用。

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

完整示例代码

在 Java 消息 SDK 的 GitHub 上查找最终的代码。

先决条件

注册到 Azure 通信服务资源的 WhatsApp Business 帐户。
用于接收消息的活动的 WhatsApp 电话号码。
Node.js 活动 LTS 和维护 LTS 版本（建议使用 8.11.1 和 10.14.1）。

在终端或命令窗口中，运行以下命令验证是否已安装 Node.js：
```
node --version
```

设置环境

若要设置用于发送消息的环境，请完成以下步骤。

创建新的 Node.js 应用程序

为应用创建一个新目录，并在终端或命令窗口中打开该目录。

运行以下命令。

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

运行以下命令以使用默认设置创建 package.json 文件。
```
npm init -y
```
使用文本编辑器在项目根目录中创建名为“send-messages.js”的文件。

将以下代码片段添加到文件 send-messages.js 中。

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

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

完成以下部分，将此示例的源代码添加到你创建的 send-messages.js 文件。

安装包

使用 npm install 命令安装适用于 JavaScript 的 Azure 通信服务高级消息传送 SDK。

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

--save 选项将该库作为 package.json 文件中的依赖项列出。

对象模型

以下类和接口处理适用于 JavaScript 的 Azure 通信服务高级消息传送 SDK 的某些主要功能。

名称	描述
NotificationClient	此类连接到你的 Azure 通信服务资源。它会发送消息。
DownloadMediaAsync	异步下载用户到企业消息中的媒体有效负载，并将内容写入流中。
Microsoft.Communication.AdvancedMessageReceived	高级消息传递收到消息时发布的事件网格事件。

注意

有关详细信息，请参阅适用于 JavaScript 的 Azure SDK 参考文章 @Azure-rest/communication-messages 包

通用配置

按照以下步骤将所需的代码片段添加到 DownloadMedia.js 文件的 main 函数中。

开始在企业和 WhatsApp 用户之间发送消息。
对客户端进行身份验证。
设置频道注册 ID。
设置接收方列表。

开始在企业和 WhatsApp 用户之间发送消息

可通过下面两种方式之一发起 WhatsApp Business 帐户与 WhatsApp 用户之间的对话：

企业向 WhatsApp 用户发送模板消息。
WhatsApp 用户向企业号码发送任何消息。

对客户端进行身份验证

以下代码使用 dotenv 包从名为 COMMUNICATION_SERVICES_CONNECTION_STRING 的环境变量中检索资源的连接字符串。

为简单起见，本文使用连接字符串进行身份验证。在生产环境中，我们建议使用服务主体。

将环境变量 COMMUNICATION_SERVICES_CONNECTION_STRING 设置为连接字符串的值。
打开控制台窗口并输入以下命令：

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

有关如何为系统设置环境变量的详细信息，请按照在环境变量中存储连接字符串的步骤操作。

若要实例化 NotificationClient，请将以下代码添加到 Main 方法：

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

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

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

还可以使用 Azure 标识库对 Microsoft Entra ID 进行身份验证。

@Azure/identity 包提供应用程序可用于身份验证的各种凭据类型。可以选择各种选项来对标识进行身份验证：Azure 标识 - 凭据提供程序和 Azure 标识 - 对客户端进行身份验证。此选项将演示一种使用 DefaultAzureCredential 的方法。

若要创建 DefaultAzureCredential 对象，请执行以下操作：

若要设置服务主体应用，请按照创建 Microsoft Entra 注册的应用程序的说明进行操作。
使用你的应用的创建的输出设置环境变量 AZURE_CLIENT_ID、AZURE_CLIENT_SECRET 和 AZURE_TENANT_ID。
打开控制台窗口并输入以下命令：
```
setx AZURE_CLIENT_ID "<your app's appId>"
setx AZURE_CLIENT_SECRET "<your app's password>"
setx AZURE_TENANT_ID "<your app's tenant>"
```
添加环境变量后，可能需要重启任何正在运行的、需要读取环境变量的程序（包括控制台窗口）。例如，如果使用 Visual Studio 作为编辑器，请在运行示例之前重启 Visual Studio。
若要使用 DefaultAzureCredential 提供程序或 Azure SDK 提供的其他凭据提供程序，请安装 @azure/identity 包。
```
npm install @azure/identity
```

若要实例化 NotificationClient，请将以下代码添加到 Main 方法。

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

// Configure authentication
const endpoint = "https://<resource name>.communication.azure.com";
let credential = new DefaultAzureCredential();

// Instantiate the client
const client = NotificationClient(endpoint, credential);

还可以使用 AzureKeyCredential 进行身份验证。

从 Azure 门户中的 Azure 通信服务资源获取终结点和密钥。在左侧，导航到“Keys”选项卡。复制主键的 Endpoint 和 Key 字段。

将环境变量 COMMUNICATION_SERVICES_KEY 设置为连接字符串的值。
打开控制台窗口并输入以下命令：

setx COMMUNICATION_SERVICES_KEY "<your key>"

有关如何为系统设置环境变量的详细信息，请按照在环境变量中存储连接字符串的步骤操作。

若要实例化 NotificationClient，请将以下代码添加到 Main 方法：

const AzureKeyCredential = require("@azure/core-auth").AzureKeyCredential;
const NotificationClient = require("@azure-rest/communication-messages").default;

// Configure authentication
const endpoint = "https://<resource name>.communication.azure.com";
const credential = new AzureKeyCredential("<your key credential>");

// Instantiate the client
const client = NotificationClient(endpoint, credential);

设置频道注册 ID

频道注册 ID GUID 是在频道注册期间创建的。可在门户中，访问 Azure 通信服务资源的“频道”选项卡来查找它。

将它分配给名为 channelRegistrationId 的变量。

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

设置收件人列表

你需要提供一个与 WhatsApp 帐户关联的真实电话号码。此 WhatsApp 帐户接收本文中发送的模板、文本和媒体消息。在本文中，此电话号码可以是你的个人电话号码。

收件人电话号码不能是与 WhatsApp 频道注册关联的业务电话号码（发件人 ID）。发件人 ID 显示为发送给收件人的文本和媒体消息的发件人。

电话号码应包括国家/地区代码。有关电话号码格式的详细信息，请查看 WhatsApp 文档中的电话号码格式。

注意

收件人列表中当前仅支持一个电话号码。

创建如下所示的收件人列表：

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

示例：

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

代码示例

按照以下步骤将所需的代码片段添加到 DownloadMedia.js 文件的 main 函数中。

将媒体有效负载下载到流中

将媒体有效负载下载到流中

Messages SDK 使 Contoso 能够在 WhatsApp 用户发起对话时使用 WhatsApp 文本消息做出响应。若要发送文本消息，请完成以下步骤：

经过身份验证的 NotificationMessagesClient
媒体的媒体 ID GUID（从 AdvancedMessageReceived 事件中的传入消息接收）

在此示例中，我们使用以下文本回复 WhatsApp 用户："Thanks for your feedback.\n From Notification Messaging SDK."

组装并发送媒体消息：

const credential = new AzureKeyCredential(process.env.ACS_ACCESS_KEY || "");
const endpoint = process.env.ACS_URL || "";
const client = NotificationClient(endpoint, credential);
console.log("Downloading...");
await client
.path("/messages/streams/{id}", "<MEDIA_ID>")
.get()
.asNodeStream()
.then((resp) => {
    resp.body?.pipe(fs.createWriteStream("downloadedMedia.jpeg"));
    return;
});

运行代码

使用 node 命令运行添加到 send-messages.js 文件中的代码。

node ./send-messages.js

完整示例代码

下载高级消息传递事件接收的媒体。

/**
 * @summary Download a media file
 */

const NotificationClient = require("@azure-rest/communication-messages").default;
const { AzureKeyCredential } = require("@azure/core-auth");
const fs = require("fs");

// Load the .env file if it exists
require("dotenv").config();

async function main() {
  const credential = new AzureKeyCredential(process.env.ACS_ACCESS_KEY || "");
  const endpoint = process.env.ACS_URL || "";
  const client = NotificationClient(endpoint, credential);
  console.log("Downloading...");
  await client
    .path("/messages/streams/{id}", "<MEDIA_ID>")
    .get()
    .asNodeStream()
    .then((resp) => {
      resp.body?.pipe(fs.createWriteStream("downloadedMedia.jpeg"));
      return;
    });
}

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

先决条件

注册到 Azure 通信服务资源的 WhatsApp Business 帐户。
.NET 开发环境，如 Visual Studio、Visual Studio Code 或 .NET CLI。
事件订阅和高级消息接收事件的处理。

设置

创建新的 Python 应用程序

在终端或控制台窗口中，为应用程序创建一个新文件夹并打开它。

mkdir messages-quickstart && cd messages-quickstart

安装包

使用适用于 Python 1.1.0 或更高版本的 Azure 通信消息客户端库。

在控制台提示中运行以下命令：

pip install azure-communication-messages

对于“InteractiveMessages、Reactions 和 Stickers”，请使用以下 Beta 版本：

pip install azure-communication-messages==1.2.0b1

设置应用框架

创建一个名为 messages-quickstart.py 的新文件并添加基本程序结构。

type nul > messages-quickstart.py

基本程序结构

import os

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

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

对象模型

以下类和接口用于处理适用于 Python 的 Azure 通信服务消息 SDK 的某些主要功能。

名称	描述
NotificationMessagesClient	此类连接到你的 Azure 通信服务资源。它会发送消息。
DownloadMediaAsync	异步下载用户到企业消息中的媒体有效负载，并将内容写入流中。
Microsoft.Communication.AdvancedMessageReceived	高级消息传递收到消息时发布的事件网格事件。

注意

有关详细信息，请参阅 Azure SDK for Python 参考文章消息包。

通用配置

按照以下步骤将所需的代码片段添加到 messages-quickstart.py Python 程序。

开始在企业和 WhatsApp 用户之间发送消息。
对客户端进行身份验证。
设置频道注册 ID。
设置接收方列表。

对客户端进行身份验证

发送的消息使用 NotificationMessagesClient。 NotificationMessagesClient 使用从 Azure 门户中的 Azure 通信服务资源获取的连接字符串进行身份验证。F

有关连接字符串的详细信息，请参阅访问连接字符串和服务终结点。

从 Microsoft Azure 门户获取 Azure 通信资源连接字符串，如屏幕截图中所示。在左侧，导航到“Keys”选项卡。复制主键的 Connection string 字段。连接字符串采用 endpoint=https://{your Azure Communication Services resource name}.communication.azure.com/;accesskey={secret key} 格式。

显示 Microsoft Azure 门户中的 Azure 通信服务资源的屏幕截图，其中显示了“键”部分中的“主键”字段。

将环境变量 COMMUNICATION_SERVICES_CONNECTION_STRING 设置为连接字符串的值。
打开控制台窗口并输入以下命令：

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

有关如何为系统设置环境变量的详细信息，请按照在环境变量中存储连接字符串的步骤操作。

    # 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)

NotificationMessagesClient 也使用 Microsoft Entra ID/TokenCredentials 进行身份验证。有关详细信息，请参阅 access-Azure-Communication-Resources-using-TokenCredentials。

azure.identity 包提供应用程序可用于身份验证的各种凭据类型。可以选择各种选项来对标识进行身份验证：Azure 标识 - 凭据提供程序和 Azure 标识 - 对客户端进行身份验证。此选项将演示一种使用 DefaultAzureCredential 的方法。

若要创建 DefaultAzureCredential 对象，请执行以下操作：

若要设置服务主体应用，请按照创建 Microsoft Entra 注册的应用程序的说明进行操作。
使用你的应用的创建的输出设置环境变量 AZURE_CLIENT_ID、AZURE_CLIENT_SECRET 和 AZURE_TENANT_ID。
打开控制台窗口并输入以下命令：
```
setx COMMUNICATION_SERVICES_ENDPOINT_STRING "<https://<resource name>.communication.azure.com>"
setx AZURE_CLIENT_ID "<your app's appId>"
setx AZURE_CLIENT_SECRET "<your app's password>"
setx AZURE_TENANT_ID "<your app's tenant>"
```
添加环境变量后，可能需要重启任何正在运行的、需要读取环境变量的程序（包括控制台窗口）。例如，如果使用 Visual Studio 作为编辑器，请在运行示例之前重启 Visual Studio。
若要使用 DefaultAzureCredential 提供程序或 Azure SDK 提供的其他凭据提供程序，请安装 azure.identity python 包，然后实例化客户端。

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

        # Create NotificationMessagesClient Client
        messaging_client = NotificationMessagesClient(endpoint=self.endpoint_string,
                                                    credential=DefaultAzureCredential())

还可以使用 AzureKeyCredential 进行身份验证。

从 Azure 门户中的 Azure 通信服务资源获取终结点和密钥。在左侧，导航到“Keys”选项卡。复制主键的 Endpoint 和 Key 字段。

将环境变量 COMMUNICATION_SERVICES_KEY 设置为连接字符串的值。
打开控制台窗口并输入以下命令：

setx COMMUNICATION_SERVICES_ENDPOINT_STRING "<https://<resource name>.communication.azure.com>"
setx COMMUNICATION_SERVICES_KEY "<your key>"

有关如何为系统设置环境变量的详细信息，请按照在环境变量中存储连接字符串的步骤操作。

若要实例化 NotificationMessagesClient，请添加以下代码：

    # Get a connection string to our Azure Communication Services resource.
    endpoint_string = os.getenv("COMMUNICATION_SERVICES_ENDPOINT_STRING")
    key = os.getenv("COMMUNICATION_SERVICES_KEY")

    def send_template_message(self):
        from azure.core.credentials import AzureKeyCredential
        from azure.communication.messages import NotificationMessagesClient

        # Create NotificationMessagesClient Client
        messaging_client = NotificationMessagesClient(endpoint=self.endpoint_string,
                                                    credential=AzureKeyCredential(self.key))

设置频道注册 ID

你已在频道注册期间创建了频道注册 ID GUID。在门户中 Azure 通信服务资源的“频道”选项卡中可以找到它。

将它分配给名为 channelRegistrationId 的变量。

    channelRegistrationId = os.getenv("WHATSAPP_CHANNEL_ID_GUID")

设置收件人列表

需要提供与 WhatsApp 帐户关联的有效电话号码。此 WhatsApp 帐户接收本文中发送的模板、文本和媒体消息。

对于此示例，可以使用个人电话号码。

收件人电话号码不能是与 WhatsApp 频道注册关联的业务电话号码（发件人 ID）。发件人 ID 显示为发送给收件人的文本和媒体消息的发件人。

电话号码必须包括国家/地区代码。有关电话号码格式的详细信息，请查看 WhatsApp 文档中的电话号码格式。

注意

收件人列表中当前仅支持一个电话号码。

设置如下所示的收件人列表：

    phone_number = os.getenv("RECIPIENT_WHATSAPP_PHONE_NUMBER")

用例：

    # Example only
    to=[self.phone_number],

开始在企业和 WhatsApp 用户之间发送消息

可通过下面两种方式之一发起 WhatsApp Business 帐户与 WhatsApp 用户之间的对话：

企业向 WhatsApp 用户发送模板消息。
WhatsApp 用户向企业号码发送任何消息。

若要从个人 WhatsApp 帐户发起交互式对话，请向企业号码（发送方 ID）发送消息。

代码示例

按照以下步骤将所需的代码片段添加到 messages-quickstart.py Python 程序。

将媒体有效负载下载到流中

将媒体有效负载下载到流中

Messages SDK 使 Contoso 能够在 WhatsApp 用户发起对话时从 WhatsApp 用户接收或下载媒体。若要将媒体有效负载下载到流中，需要：

WhatsApp 频道 ID。
E16 格式的接收方电话号码。
下载 GUID 格式的媒体 ID。

重要

若要向 WhatsApp 用户发送文本消息，WhatsApp 用户必须先向 WhatsApp 企业帐户发送消息。有关详细信息，请参阅开始在企业和 WhatsApp 用户之间发送消息。

在此示例中，企业向用户发送了响应消息。

      def download_media(self):

        from azure.communication.messages import NotificationMessagesClient

        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)
        input_media_id: str = "de7558b5-e169-4d47-9ba4-37a95c28f390"

        # calling send() with whatsapp message details
        media_stream = messaging_client.download_media(input_media_id)
        length : int = 0
        for byte in media_stream:
            length = length + 1
        print("WhatsApp Media stream downloaded.It's length is {}".format(length))

若要运行 download_media()，请更新 main 方法。

    #Calling download_media()
    messages.download_media()

运行代码

若要运行代码，请确保你位于 download-media-quickstart.py 文件所在的目录中。

python download-media-quickstart.py

Azure Communication Services - Advanced Messages Quickstart
WhatsApp Media stream downloaded.

完整示例代码

注意

更改以下代码中的所有占位符变量，使之与你的值匹配。

import os
from io import BytesIO

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

     def download_media(self):

        from azure.communication.messages import NotificationMessagesClient

        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)
        input_media_id: str = "de7558b5-e169-4d47-9ba4-37a95c28f390"

        # calling send() with whatsapp message details
        media_stream = messaging_client.download_media(input_media_id)
        length : int = 0
        for byte in media_stream:
            length = length + 1
        print("WhatsApp Media stream downloaded.It's length is {}".format(length))

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

示例代码

在 Python 消息 SDK 的 GitHub 上查看并下载其他示例代码。

通过

快速入门：下载 WhatsApp 消息媒体

先决条件

设置环境

创建 .NET 项目

安装包

设置应用框架

对象模型

通用配置

对客户端进行身份验证

设置频道注册 ID

设置收件人列表

开始在企业和 WhatsApp 用户之间发送消息

代码示例

将媒体有效负载下载到流中

将媒体有效负载下载到文件中

运行代码

完整示例代码

先决条件

设置环境

创建新的 Java 应用程序

安装包

设置应用框架

对象模型

通用配置

开始在企业和 WhatsApp 用户之间发送消息

对客户端进行身份验证

设置频道注册 ID

设置收件人列表

代码示例

将媒体有效负载下载到流中

运行代码

完整示例代码

先决条件

设置环境

创建新的 Node.js 应用程序

安装包

对象模型

通用配置

开始在企业和 WhatsApp 用户之间发送消息

对客户端进行身份验证

设置频道注册 ID

设置收件人列表

代码示例

将媒体有效负载下载到流中

运行代码

完整示例代码

先决条件

设置

创建新的 Python 应用程序

安装包

设置应用框架

基本程序结构

对象模型

通用配置

对客户端进行身份验证

设置频道注册 ID

设置收件人列表

开始在企业和 WhatsApp 用户之间发送消息

代码示例

将媒体有效负载下载到流中

运行代码

完整示例代码

示例代码

后续步骤

反馈

其他资源