使用進階訊息傳送 WhatsApp 範本訊息

必要條件

向您的 Azure 通訊服務資源註冊 WhatsApp Business 帳戶。
建立 WhatsApp 範本訊息。
要接收訊息的作用中 WhatsApp 電話號碼。

物件模型

下列類別和介面會處理適用於 .NET 的 Azure 通訊服務 Messages SDK 的一些主要功能。

類別名稱	描述
`NotificationMessagesClient`	線上到您的 Azure 通訊服務資源。它會傳送訊息。
`MessageTemplate`	定義您使用的範本，以及訊息範本屬性的內容。
`TemplateNotificationContent`	定義您想要傳送之範本訊息的「誰」和「內容」。

注意

如需詳細資訊，請參閱適用於 .NET 的 Azure SDK 參考 Azure.Communication.Messages 命名空間。

支援的 WhatsApp 範本類型

範本類型	描述
以文字為基礎的訊息範本	WhatsApp 訊息範本是具有或不含參數的特定訊息格式。
以媒體為基礎的訊息範本	WhatsApp 訊息範本與標頭元件的媒體參數。
互動式訊息範本	互動式訊息範本會展開您可以傳送收件者的內容，方法是使用 components 物件來包含互動式按鈕。同時支援通話和快速回復。
以位置為基礎的訊息範本	WhatsApp 訊息範本，其位置參數在標頭元件的經度和緯度方面。

一般設定

請遵循下列步驟，將必要的代碼段新增至檔案 Program.cs 的 Main 函式。

建立和管理 WhatsApp 範本訊息。
驗證用戶端。
設定通道註冊標識碼。
設定收件者清單。

建立和管理 WhatsApp 範本訊息

WhatsApp 訊息範本是企業用來將通知或客戶服務訊息傳送給加入通知的人員的特定訊息格式。訊息可以包含約會提醒、出貨資訊、問題解決或付款更新。 在開始使用進階傳訊 SDK 來傳送範本化訊息之前，用戶必須在 WhatsApp Business Platform 中建立必要的範本。

如需範本 WhatsApp 需求的詳細資訊，請參閱 WhatsApp Business Platform API 參考：

建立和管理範本。
檢視範本元件。
傳送範本訊息。
企業也必須遵守選擇加入要求，才能將訊息傳送給 WhatsApp 使用者。

驗證用戶端

訊息 SDK 會使用 NotificationMessagesClient 來傳送訊息。方法會NotificationMessagesClient使用從 Azure 入口網站中的 Azure 通訊服務資源取得的連接字串進行驗證。如需連接字串的詳細資訊，請參閱 access-your-connection-strings-and-service-endpoints。

為了簡單起見，本快速入門會使用連接字串進行驗證。在實際執行環境中，我們建議服務主體。

在 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。
若要使用 DefaultAzureCredential 提供者或其他 Azure SDK 所提供的認證提供者，請安裝 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>"

新增環境變數之後，您可能需要重新啟動任何需要讀取環境變數的執行中程式，包括主控台視窗。例如，如果您使用 Visual Studio 作為編輯器，請在執行範例前重新啟動 Visual Studio。

如需如何為系統設定環境變數的詳細資訊，請遵循將連接字串儲存在環境變數中的步驟。

若要具現化 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);

設定頻道註冊識別碼

您在通道註冊期間建立了通道註冊標識碼 GUID。在入口網站中尋找 Azure 通訊服務資源的 [通道] 索引標籤。

將其指派給名為 channelRegistrationId 的變數。

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

設定收件者清單

您必須提供與 WhatsApp 帳戶相關聯的使用中電話號碼。此 WhatsApp 帳戶會接收本快速入門中傳送的範本、文字和媒體訊息。

在此範例中，您可以使用個人電話號碼。

收件者電話號碼不能是與 WhatsApp 頻道註冊相關聯的商務電話號碼 (傳送者識別碼)。傳送者識別碼會顯示為傳送給收件者之文字和媒體訊息的傳送者。

電話號碼必須包含國家/地區代碼。如需電話號碼格式的詳細資訊，請參閱 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 Platform 的定義。

若要從您的個人 WhatsApp 帳戶起始互動式交談，請將訊息傳送至您的商務號碼（寄件人標識符）。

設定環境

建立 .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

Install the package

將 Azure.Communication.Messages NuGet 套件安裝至 C# 專案。

在 Project>Manage NuGet Packages... 開啟 NuGet 套件管理員。
搜尋套件 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;

程式碼範例

請遵循下列步驟，將必要的代碼段新增至檔案 Program.cs 的 Main 函式。

列出 Azure 入口網站中的 WhatsApp 範本。
傳送沒有參數的範本訊息。
使用本文中的文字參數傳送範本訊息。
使用標頭中的媒體參數傳送範本訊息。
傳送標頭中位置的範本訊息。
使用快速回復按鈕傳送範本訊息。
使用動態連結來傳送具有動作按鈕呼叫的範本訊息。
使用靜態連結來傳送具有動作按鈕呼叫的範本訊息。

列出 Azure 入口網站中的 WhatsApp 範本

您可以移至 Azure 通訊服務資源 >[進階傳訊>範本]，以檢視 Azure 入口網站中的範本。

選取範本以檢視詳細數據。

content範本詳細數據的欄位可以包含參數係結。參數繫結可以表示為：

format具有值的欄位，例如 IMAGE。
括住數字的雙括弧，例如 {{1}}。這些數字 (從 1 開始編製索引) 表示必須提供繫結值來建立訊息範本的順序。

或者，您可以在 WhatsApp Manager 帳戶工具>訊息範本中檢視和編輯所有 WhatsApp Business 帳戶範本。>

若要以程序設計方式列出範本，您可以擷取通道標識碼的所有範本，如下所示：

MessageTemplateClient messageTemplateClient = new MessageTemplateClient(connectionString);
Pageable<MessageTemplateItem> templates = messageTemplateClient.GetTemplates(channelRegistrationId);

傳送沒有參數的範本訊息

如果範本不需要參數，您不需要在建立 MessageTemplate時提供任何值或系結。

var messageTemplate = new MessageTemplate(templateName, templateLanguage);

範例

sample_template不採用任何參數。

MessageTemplate藉參考目標樣本名稱與語言來組合。

string templateName = "sample_template"; 
string templateLanguage = "en_us"; 

var sampleTemplate = new MessageTemplate(templateName, templateLanguage);

使用本文中的文字參數傳送範本訊息

使用 MessageTemplateText，定義內文中透過雙括弧括住數字來表示的參數，例如 {{1}}。從 1 開始的數位索引表示必須提供系結值的順序，才能建立訊息範本。不可包含不在範本中的參數。

具有兩個參數的範本定義：

{
  "type": "BODY",
  "text": "Message with two parameters: {{1}} and {{2}}"
}

範例

sample_shipping_confirmation 樣本：

在此範例中，範本的內文有一個參數：

{
  "type": "BODY",
  "text": "Your package has been shipped. It will be delivered in {{1}} business days."
},

參數會使用 MessageTemplateValue 值和 MessageTemplateWhatsAppBindings 繫結來定義。使用值與繫結來組合 MessageTemplate。

string templateName = "sample_shipping_confirmation"; 
string templateLanguage = "en_us"; 

var threeDays = new MessageTemplateText("threeDays", "3");

WhatsAppMessageTemplateBindings bindings = new();
bindings.Body.Add(new(threeDays.Name));

MessageTemplate shippingConfirmationTemplate  = new(templateName, templateLanguage);
shippingConfirmationTemplate.Bindings = bindings;
shippingConfirmationTemplate.Values.Add(threeDays);

在標頭中使用媒體參數傳送範本訊息

使用 MessageTemplateImage、MessageTemplateVideo 或 MessageTemplateDocument 定義標頭中的媒體參數。

標頭中具有影像媒體參數的範本定義：

{
  "type": "HEADER",
  "format": "IMAGE"
},

format可以有 WhatsApp 支援的不同媒體類型。在 .NET SDK 中，每個媒體類型都會使用對應的 MessageTemplateValue 類型。

格式	MessageTemplateValue 類型	檔案類型
`IMAGE`	`MessageTemplateImage`	png、jpg
`VIDEO`	`MessageTemplateVideo`	mp4
`DOCUMENT`	`MessageTemplateDocument`	PDF

若要深入了解支援的媒體類型和大小限制，請參閱 WhatsApp 的訊息媒體文件。

影像媒體的訊息範本組件：

var url = new Uri("< Your media URL >");

var media = new MessageTemplateImage("image", url);
WhatsAppMessageTemplateBindings bindings = new();
bindings.Header.Add(new(media.Name));

var messageTemplate = new MessageTemplate(templateName, templateLanguage);
template.Bindings = bindings;
template.Values.Add(media);

範例

sample_movie_ticket_confirmation 樣本：

在此範例中，範本的標頭需要影像：

{
  "type": "HEADER",
  "format": "IMAGE"
},

樣本本文需要四個文字參數：

{
  "type": "BODY",
  "text": "Your ticket for *{{1}}*\n*Time* - {{2}}\n*Venue* - {{3}}\n*Seats* - {{4}}"
},

建立一個 MessageTemplateText 和四個 MessageTemplateImage 變數。然後，以參數出現在範本內容中的順序提供參數，組合您的 MessageTemplateValue 清單和 MessageTemplateWhatsAppBindings。

string templateName = "sample_movie_ticket_confirmation"; 
string templateLanguage = "en_us"; 
var imageUrl = new Uri("https://aka.ms/acsicon1");

var image = new MessageTemplateImage("image", imageUrl);
var title = new MessageTemplateText("title", "Contoso");
var time = new MessageTemplateText("time", "July 1st, 2023 12:30PM");
var venue = new MessageTemplateText("venue", "Southridge Video");
var seats = new MessageTemplateText("seats", "Seat 1A");

WhatsAppMessageTemplateBindings bindings = new();
bindings.Header.Add(new(image.Name));
bindings.Body.Add(new(title.Name));
bindings.Body.Add(new(time.Name));
bindings.Body.Add(new(venue.Name));
bindings.Body.Add(new(seats.Name));

MessageTemplate movieTicketConfirmationTemplate = new(templateName, templateLanguage);
movieTicketConfirmationTemplate.Values.Add(image);
movieTicketConfirmationTemplate.Values.Add(title);
movieTicketConfirmationTemplate.Values.Add(time);
movieTicketConfirmationTemplate.Values.Add(venue);
movieTicketConfirmationTemplate.Values.Add(seats);
movieTicketConfirmationTemplate.Bindings = bindings;

傳送標頭中位置的範本訊息

使用 MessageTemplateLocation 在標頭中定義location 參數。

標頭元件的範本定義，需要位置為：

{
  "type": "header",
  "parameters": [
    {
      "type": "location",
      "location": {
        "latitude": "<LATITUDE>",
        "longitude": "<LONGITUDE>",
        "name": "<NAME>",
        "address": "<ADDRESS>"
      }
    }
  ]
}

format可能需要不同的媒體類型。在 .NET SDK 中，每個媒體類型都會使用對應的 MessageTemplateValue 類型。

屬性	描述	類型
`ADDRESS`	出現在值之後 `NAME` 的位址，位於訊息頂端的泛型對應下方。	字串
`LATITUDE`	位置緯度。	double
`LONGITUDE`	位置經度。	double
`LOCATIONNAME`	出現在訊息頂端泛型對應下方的文字。	字串

如需位置型範本的詳細資訊，請參閱 WhatsApp 的訊息媒體檔。

範例

sample_movie_location 樣本：

以位置為基礎的訊息模組：

 var location = new MessageTemplateLocation("location");
 location.LocationName = "Pablo Morales";
 location.Address = "1 Hacker Way, Menlo Park, CA 94025";
 location.Position = new Azure.Core.GeoJson.GeoPosition(longitude: 122.148981, latitude: 37.483307);

 WhatsAppMessageTemplateBindings location_bindings = new();
 location_bindings.Header.Add(new(location.Name));

 var messageTemplateWithLocation = new MessageTemplate(templateNameWithLocation, templateLanguage);
 messageTemplateWithLocation.Values.Add(location);
 messageTemplateWithLocation.Bindings = location_bindings;

使用快速回復按鈕傳送範本訊息

使用 MessageTemplateQuickAction 來定義快速回復按鈕和 MessageTemplateQuickAction 對象的承載，具有下列三個屬性。

屬性	描述	類型
名稱	`name`，用來查閱中的`MessageTemplateWhatsAppBindings`值。	字串
Text	選擇性的快速動作 `text`。	字串
酬載	`payload`如果使用者選取按鈕，則指派給訊息回復中可用的按鈕。	字串

具有快速回覆按鈕的樣本定義：

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "QUICK_REPLY",
      "text": "Yes"
    },
    {
      "type": "QUICK_REPLY",
      "text": "No"
    }
  ]
}

按鈕出現在範本定義中的順序必須符合使用建立系結 MessageTemplateWhatsAppBindings時所定義按鈕的順序。

如需使用者快速回復響應中承載的詳細資訊，請參閱從快速回復按鈕接收回呼的 WhatsApp 檔。

範例

sample_issue_resolution 樣本：

樣本的本文需要一個文字參數：

{
  "type": "BODY",
  "text": "Hi {{1}}, were we able to solve the issue that you were facing?"
},

樣本包含兩個預先填入的回復按鈕， Yes 以及 No。

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "QUICK_REPLY",
      "text": "Yes"
    },
    {
      "type": "QUICK_REPLY",
      "text": "No"
    }
  ]
}

建立一個 MessageTemplateQuickAction 和兩個 MessageTemplateText 變數。然後，依照參數出現在範本內容中的順序提供參數，以組合您的清單 MessageTemplateValue 和您的 MessageTemplateWhatsAppBindings 。定義系結按鈕時，順序也很重要。

string templateName = "sample_issue_resolution";
string templateLanguage = "en_us";

var name = new MessageTemplateText(name: "name", text: "Kat");
var yes = new MessageTemplateQuickAction(name: "Yes"){ Payload =  "Kat said yes" };
var no = new MessageTemplateQuickAction(name: "No") { Payload = "Kat said no" };

WhatsAppMessageTemplateBindings bindings = new();
bindings.Body.Add(new(name.Name));
bindings.Buttons.Add(new(WhatsAppMessageButtonSubType.QuickReply.ToString(), yes.Name));
bindings.Buttons.Add(new(WhatsAppMessageButtonSubType.QuickReply.ToString(), no.Name));

MessageTemplate issueResolutionTemplate = new(templateName, templateLanguage);
issueResolutionTemplate.Values.Add(name);
issueResolutionTemplate.Values.Add(yes);
issueResolutionTemplate.Values.Add(no);
issueResolutionTemplate.Bindings = bindings;

使用動態連結傳送具有動作按鈕呼叫的範本訊息

使用 MessageTemplateQuickAction 來定義呼叫動作按鈕和 MessageTemplateQuickAction 物件的 URL 後綴，具有下列兩個屬性。

屬性	描述	類型
名稱	`name` 會用來查閱 `MessageTemplateWhatsAppBindings` 中的值。	字串
Text	`text`附加至網址的。	字串

範本定義按鈕：

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "URL",
      "text": "Take Survey",
      "url": "https://www.example.com/{{1}}"
    }
  ]
}

按鈕出現在範本定義中的順序必須符合使用建立系結 MessageTemplateWhatsAppBindings時所定義按鈕的順序。

範例

sample_purchase_feedback 樣本：

此範例範本會將具有動態 URL 連結的按鈕新增至訊息。也會在標頭中使用影像，並在內文中使用文字參數。

在此範例中，範本的標頭需要影像：

{
  "type": "HEADER",
  "format": "IMAGE"
},

樣本的本文需要一個文字參數：

{
  "type": "BODY",
  "text": "Thank you for purchasing {{1}}! We value your feedback and would like to learn more about your experience."
},

此樣本包含具有一個參數的動態URL 按鈕：

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "URL",
      "text": "Take Survey",
      "url": "https://www.example.com/{{1}}"
    }
  ]
}

建立一個 MessageTemplateImage、一個 MessageTemplateText 和一個 MessageTemplateQuickAction 變數。然後，依照參數出現在範本內容中的順序提供參數，以組合您的清單 MessageTemplateValue 和您的 MessageTemplateWhatsAppBindings 。定義系結按鈕時，順序也很重要。

string templateName = "sample_purchase_feedback";
string templateLanguage = "en_us";
var imageUrl = new Uri("https://aka.ms/acsicon1");

var image = new MessageTemplateImage(name: "image", uri: imageUrl);
var product = new MessageTemplateText(name: "product", text: "coffee");
var urlSuffix = new MessageTemplateQuickAction(name: "text") { Text = "survey-code" };

WhatsAppMessageTemplateBindings bindings = new();
bindings.Header.Add(new(image.Name));
bindings.Body.Add(new(product.Name));
bindings.Buttons.Add(new(WhatsAppMessageButtonSubType.Url.ToString(), urlSuffix.Name));

MessageTemplate purchaseFeedbackTemplate = new("sample_purchase_feedback", "en_us");
purchaseFeedbackTemplate.Values.Add(image);
purchaseFeedbackTemplate.Values.Add(product);
purchaseFeedbackTemplate.Values.Add(urlSuffix);
purchaseFeedbackTemplate.Bindings = bindings;

使用靜態連結傳送具有動作按鈕呼叫的範本訊息

針對靜態連結，您不需要包含 MessageTemplateQuickAction 模型，因為 WhatsApp 範本具有靜態 CallToAction 連結，不需要使用者輸入。

範本定義按鈕：

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "URL",
      "text": "Take Survey",
      "url": "https://www.example.com/{{1}}"
    }
  ]
}

範例

purchase_feedback_static 樣本：

此範例範本會將具有靜態 URL 連結的按鈕新增至訊息。也會在標頭中使用影像，並在內文中使用文字參數。

在此範例中，範本的標頭需要影像：

{
  "type": "HEADER",
  "format": "IMAGE"
},

樣本的本文需要一個文字參數：

{
  "type": "BODY",
  "text": "Hello {{1}}, \nHope you are great day!.\n Please click on given link to explore about our program.."
},

此樣本包含具有一個參數的動態URL 按鈕：

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "URL",
      "text": "Take Survey",
      "url": "https://www.example.com/"
    }
  ]
}

建立一個 MessageTemplateImage、一個 MessageTemplateText。然後，依照參數出現在範本內容中的順序提供參數，以組合您的清單 MessageTemplateValue 和您的 MessageTemplateWhatsAppBindings 。定義系結按鈕時，順序也很重要。

// Send sample template sample_template
string templateNameWithcta = "purchase_feedback_static";
var bodyParam1 = new MessageTemplateText(name: "customer", text: "Joe");
var image = new MessageTemplateImage("image", new Uri("https://aka.ms/acsicon1"));

WhatsAppMessageTemplateBindings cta_bindings = new();
cta_bindings.Body.Add(new(bodyParam1.Name));
cta_bindings.Header.Add(new(image.Name));

var messageTemplateWithcta = new MessageTemplate(templateNameWithcta, templateLanguage);
messageTemplateWithcta.Values.Add(bodyParam1);
messageTemplateWithcta.Values.Add(image);
messageTemplateWithcta.Bindings = cta_bindings;

TemplateNotificationContent templateContent4 =
    new TemplateNotificationContent(channelRegistrationId, recipientList, messageTemplateWithcta);
Response<SendMessageResult> sendTemplateMessageResult4 =
    notificationMessagesClient.Send(templateContent4);

執行程式碼

建立並執行您的程式。

若要傳送文字或媒體訊息給 WhatsApp 使用者，WhatsApp Business 帳戶與 WhatsApp 使用者之間必須有作用中交談。

如果您沒有使用中的交談，針對此範例的目的，您可以在傳送範本訊息和傳送簡訊之間新增等候。這個新增的延遲可讓您有足夠的時間對使用者的 WhatsApp 帳戶進行回覆。如需參考，指定的範例會在傳送下一則訊息之前提示手動用戶輸入。如需詳細資訊，請參閱範例程式代碼的完整範例。如果成功，您會在使用者的 WhatsApp 帳戶上收到三則訊息。

建立並執行您的程式。

dotnet build
dotnet run

在 Visual Studio Code 終端機中，使用下列命令建置和執行程式（檢視>終端機）。

dotnet build
dotnet run

完整的程式碼範例

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

namespace SendTemplateMessages
{
    class Program
    {
        public static async Task Main(string[] args)
        {
            Console.WriteLine("Azure Communication Services - Send WhatsApp Template 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>" };

            // List out available templates for a channel ID
            MessageTemplateClient messageTemplateClient = new MessageTemplateClient(connectionString);
            Pageable<MessageTemplateItem> templates = messageTemplateClient.GetTemplates(channelRegistrationId);
            foreach (WhatsAppMessageTemplateItem template in templates)
            {
                Console.WriteLine("Name: {0}\tLanguage: {1}\tStatus: {2}\tContent: {3}\n",
                    template.Name, template.Language, template.Status, template.Content);
            }

            // Send Sample Template sample_template
            MessageTemplate sampleTemplate = AssembleSampleTemplate();
            var sampleTemplateContent = new TemplateNotificationContent(channelRegistrationId, recipientList, sampleTemplate);
            var result = await notificationMessagesClient.SendAsync(sampleTemplateContent);
            PrintResponse(result);
           
            // Send sample template sample_shipping_confirmation
            MessageTemplate shippingConfirmationTemplate = AssembleSampleShippingConfirmation();
            var shippingConfirmationTemplateContent = new TemplateNotificationContent(channelRegistrationId, recipientList, shippingConfirmationTemplate);
            result = await notificationMessagesClient.SendAsync(shippingConfirmationTemplateContent);
            PrintResponse(result);

            // Send sample template sample_movie_ticket_confirmation
            MessageTemplate movieTicketConfirmationTemplate = AssembleSampleMovieTicketConfirmation();
            var movieTicketConfirmationTemplateContent = new TemplateNotificationContent(channelRegistrationId, recipientList, movieTicketConfirmationTemplate);
            result = await notificationMessagesClient.SendAsync(movieTicketConfirmationTemplateContent);
            PrintResponse(result);

            // Send sample template sample_happy_hour_announcement
            MessageTemplate happyHourTemplate = AssembleSampleHappyHourAnnouncement();
            var happyHourTemplateContent = new TemplateNotificationContent(channelRegistrationId, recipientList, happyHourTemplate);
            result = await notificationMessagesClient.SendAsync(happyHourTemplateContent);
            PrintResponse(result);

            // Send sample template sample_flight_confirmation
            MessageTemplate flightConfirmationTemplate = AssembleSampleFlightConfirmation();
            var flightConfirmationTemplateContent = new TemplateNotificationContent(channelRegistrationId, recipientList, flightConfirmationTemplate);
            result = await notificationMessagesClient.SendAsync(flightConfirmationTemplateContent);
            PrintResponse(result);

            // Send sample template sample_issue_resolution
            MessageTemplate issueResolutionTemplate = AssembleSampleIssueResolution();
            var issueResolutionTemplateContent = new TemplateNotificationContent(channelRegistrationId, recipientList, issueResolutionTemplate);
            result = await notificationMessagesClient.SendAsync(issueResolutionTemplateContent);
            PrintResponse(result);

            // Send sample template sample_purchase_feedback
            MessageTemplate purchaseFeedbackTemplate = AssembleSamplePurchaseFeedback();
            var purchaseFeedbackTemplateContent = new TemplateNotificationContent(channelRegistrationId, recipientList, purchaseFeedbackTemplate);
            result = await notificationMessagesClient.SendAsync(purchaseFeedbackTemplateContent);
            PrintResponse(result);

            Console.WriteLine("Press any key to exit.");
            Console.ReadKey(true);
        }

        public static MessageTemplate AssembleSampleTemplate()
        {
            string templateName = "sample_template";
            string templateLanguage = "en_us";

            return new MessageTemplate(templateName, templateLanguage);
        }

        public static MessageTemplate AssembleSampleShippingConfirmation()
        {
            string templateName = "sample_shipping_confirmation";
            string templateLanguage = "en_us";

            var threeDays = new MessageTemplateText("threeDays", "3");

            WhatsAppMessageTemplateBindings bindings = new();
            bindings.Body.Add(new(threeDays.Name));

            MessageTemplate shippingConfirmationTemplate = new(templateName, templateLanguage);
            shippingConfirmationTemplate.Bindings = bindings;
            shippingConfirmationTemplate.Values.Add(threeDays);

            return shippingConfirmationTemplate;
        }

        public static MessageTemplate AssembleSampleMovieTicketConfirmation()
        {
            string templateName = "sample_movie_ticket_confirmation"; 
            string templateLanguage = "en_us"; 
            var imageUrl = new Uri("https://aka.ms/acsicon1");

            var image = new MessageTemplateImage("image", imageUrl);
            var title = new MessageTemplateText("title", "Contoso");
            var time = new MessageTemplateText("time", "July 1st, 2023 12:30PM");
            var venue = new MessageTemplateText("venue", "Southridge Video");
            var seats = new MessageTemplateText("seats", "Seat 1A");

            WhatsAppMessageTemplateBindings bindings = new();
            bindings.Header.Add(new(image.Name));
            bindings.Body.Add(new(title.Name));
            bindings.Body.Add(new(time.Name));
            bindings.Body.Add(new(venue.Name));
            bindings.Body.Add(new(seats.Name));

            MessageTemplate movieTicketConfirmationTemplate = new(templateName, templateLanguage);
            movieTicketConfirmationTemplate.Values.Add(image);
            movieTicketConfirmationTemplate.Values.Add(title);
            movieTicketConfirmationTemplate.Values.Add(time);
            movieTicketConfirmationTemplate.Values.Add(venue);
            movieTicketConfirmationTemplate.Values.Add(seats);
            movieTicketConfirmationTemplate.Bindings = bindings;

            return movieTicketConfirmationTemplate;
        }

        public static MessageTemplate AssembleSampleHappyHourAnnouncement()
        {
            string templateName = "sample_happy_hour_announcement";
            string templateLanguage = "en_us";
            var videoUrl = new Uri("< Your .mp4 Video URL >");

            var video = new MessageTemplateVideo("video", videoUrl);
            var venue = new MessageTemplateText("venue", "Fourth Coffee");
            var time = new MessageTemplateText("time", "Today 2-4PM");
            WhatsAppMessageTemplateBindings bindings = new();
            bindings.Header.Add(new(video.Name));
            bindings.Body.Add(new(venue.Name));
            bindings.Body.Add(new(time.Name));

            MessageTemplate happyHourAnnouncementTemplate = new(templateName, templateLanguage);
            happyHourAnnouncementTemplate.Values.Add(venue);
            happyHourAnnouncementTemplate.Values.Add(time);
            happyHourAnnouncementTemplate.Values.Add(video);
            happyHourAnnouncementTemplate.Bindings = bindings;

            return happyHourAnnouncementTemplate;
        }

        public static MessageTemplate AssembleSampleFlightConfirmation()
        {
            string templateName = "sample_flight_confirmation";
            string templateLanguage = "en_us";
            var documentUrl = new Uri("< Your .pdf document URL >");

            var document = new MessageTemplateDocument("document", documentUrl);
            var firstName = new MessageTemplateText("firstName", "Kat");
            var lastName = new MessageTemplateText("lastName", "Larssen");
            var date = new MessageTemplateText("date", "July 1st, 2023");

            WhatsAppMessageTemplateBindings bindings = new();
            bindings.Header.Add(new(document.Name));
            bindings.Body.Add(new(firstName.Name));
            bindings.Body.Add(new(lastName.Name));
            bindings.Body.Add(new(date.Name));

            MessageTemplate flightConfirmationTemplate = new(templateName, templateLanguage);
            flightConfirmationTemplate.Values.Add(document);
            flightConfirmationTemplate.Values.Add(firstName);
            flightConfirmationTemplate.Values.Add(lastName);
            flightConfirmationTemplate.Values.Add(date);
            flightConfirmationTemplate.Bindings = bindings;

            return flightConfirmationTemplate;
        }

        public static MessageTemplate AssembleSampleIssueResolution()
        {
            string templateName = "sample_issue_resolution";
            string templateLanguage = "en_us";

            var name = new MessageTemplateText(name: "name", text: "Kat");
            var yes = new MessageTemplateQuickAction(name: "Yes"){ Payload =  "Kat said yes" };
            var no = new MessageTemplateQuickAction(name: "No") { Payload = "Kat said no" };

            WhatsAppMessageTemplateBindings bindings = new();
            bindings.Body.Add(new(name.Name));
            bindings.Buttons.Add(new(WhatsAppMessageButtonSubType.QuickReply.ToString(), yes.Name));
            bindings.Buttons.Add(new(WhatsAppMessageButtonSubType.QuickReply.ToString(), no.Name));

            MessageTemplate issueResolutionTemplate = new(templateName, templateLanguage);
            issueResolutionTemplate.Values.Add(name);
            issueResolutionTemplate.Values.Add(yes);
            issueResolutionTemplate.Values.Add(no);
            issueResolutionTemplate.Bindings = bindings;

            return issueResolutionTemplate;
        }

        public static MessageTemplate AssembleSamplePurchaseFeedback()
        {
            
            string templateName = "sample_purchase_feedback";
            string templateLanguage = "en_us";
            var imageUrl = new Uri("https://aka.ms/acsicon1");

            var image = new MessageTemplateImage(name: "image", uri: imageUrl);
            var product = new MessageTemplateText(name: "product", text: "coffee");
            var urlSuffix = new MessageTemplateQuickAction(name: "text") { Text = "survey-code"};
            
            WhatsAppMessageTemplateBindings bindings = new();
            bindings.Header.Add(new(image.Name));
            bindings.Body.Add(new(product.Name));
            bindings.Buttons.Add(new(WhatsAppMessageButtonSubType.Url.ToString(), urlSuffix.Name));

            MessageTemplate purchaseFeedbackTemplate = new(templateName, templateLanguage);
            purchaseFeedbackTemplate.Values.Add(image);
            purchaseFeedbackTemplate.Values.Add(product);
            purchaseFeedbackTemplate.Values.Add(urlSuffix);
            purchaseFeedbackTemplate.Bindings = bindings;

            return purchaseFeedbackTemplate;
        }

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

必要條件

向您的 Azure 通訊服務資源註冊 WhatsApp Business 帳戶。
建立 WhatsApp 範本訊息。
要接收訊息的作用中 WhatsApp 電話號碼。

物件模型

下列類別和介面會處理適用於 Java Azure 通訊服務 Messages SDK 的一些主要功能。

類別名稱	描述
`NotificationMessagesClient`	線上到您的 Azure 通訊服務資源。它會傳送訊息。
`MessageTemplate`	定義您使用的範本，以及訊息範本屬性的內容。
`TemplateNotificationContent`	定義您想要傳送之範本訊息的「誰」和「內容」。

注意

如需詳細資訊，請參閱 com.azure.communication.messages 套件的 Azure SDK for Java 參考。

支援的 WhatsApp 範本類型

範本類型	描述
以文字為基礎的訊息範本	WhatsApp 訊息範本是具有或不含參數的特定訊息格式。
以媒體為基礎的訊息範本	WhatsApp 訊息範本與標頭元件的媒體參數。
互動式訊息範本	互動式訊息範本會展開您可以傳送收件者的內容，方法是使用 components 物件來包含互動式按鈕。同時支援通話和快速回復。
以位置為基礎的訊息範本	WhatsApp 訊息範本，其位置參數在標頭元件的經度和緯度方面。

一般設定

請遵循下列步驟，將必要的代碼段新增至檔案 App.java 的主要函式。

建立和管理 WhatsApp 範本訊息。
驗證用戶端。
設定通道註冊標識碼。
設定收件者清單。

建立和管理 WhatsApp 範本訊息

WhatsApp 訊息範本是企業用來將通知或客戶服務訊息傳送給加入通知的人員的特定訊息格式。訊息可以包含約會提醒、出貨資訊、問題解決或付款更新。 在開始使用進階傳訊 SDK 來傳送範本化訊息之前，用戶必須在 WhatsApp Business Platform 中建立必要的範本。

如需範本 WhatsApp 需求的詳細資訊，請參閱 WhatsApp Business Platform API 參考：

建立和管理範本。
檢視範本元件。
傳送範本訊息。
企業也必須遵守選擇加入要求，才能將訊息傳送給 WhatsApp 使用者。

開始在企業與 WhatsApp 使用者之間傳送訊息

WhatsApp Business 帳戶與 WhatsApp 使用者之間的交談可以透過下列兩種方式來開始：

企業將範本訊息傳送給 WhatsApp 使用者。
WhatsApp 使用者將任何訊息傳送給企業號碼。

不論交談如何開始，企業只能傳送範本訊息，直到使用者傳送訊息給企業為止。只有在使用者傳送訊息給企業之後，企業才能在作用中交談期間將文字或媒體訊息傳送給使用者。一旦 24 小時交談視窗過期，就必須重新開始交談。若要深入了解交談，請參閱 WhatsApp Business Platform 中的定義。

驗證用戶端

有一些不同的選項可用來驗證訊息用戶端：

若要驗證用戶端，您可以使用連接字串具現化 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 進行驗證。

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。
若要使用 DefaultAzureCredential 提供者或其他 Azure SDK 所提供的認證提供者，請遵循指示，在 Azure 身分識別 - 包含套件中包含 azure-identity 套件。

若要具現化 NotificationMessagesClient，請將下列程式碼新增至 Main 方法。

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

DefaultAzureCredential 物件必須透過 credential() 方法傳遞至 ClientBuilder。端點也必須透過 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();

設定頻道註冊識別碼

頻道註冊識別碼 GUID 是在頻道註冊期間建立。您可以在入口網站中的 Azure 通訊服務資源 [頻道] 索引標籤上查閱。

將其指派給名為 channelRegistrationId 的變數。

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

設定收件者清單

您必須提供與 WhatsApp 帳戶相關聯的真實電話號碼。此 WhatsApp 帳戶會接收本快速入門中傳送的文字和媒體訊息。針對本快速入門，此電話號碼可能是您的個人電話號碼。

收件者電話號碼不能是與 WhatsApp 頻道註冊相關聯的商務電話號碼 (傳送者識別碼)。傳送者識別碼會顯示為傳送給收件者之文字和媒體訊息的傳送者。

電話號碼應包含國碼 (地區碼)。如需電話號碼格式的詳細資訊，請參閱 whatsApp 文件中的電話號碼格式。

注意

收件者清單中目前僅支援一個電話號碼。

建立如下的收件者清單：

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

範例：

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

設定環境

若要設定傳送訊息的環境，請完成下列各節中的步驟。

必要條件

向 Azure 通訊服務資源註冊的 WhatsApp Business 帳戶。
要接收訊息的作用中 WhatsApp 電話號碼。
Java 開發套件 (JDK) 第 8 版或更新版本。
Apache Maven。

建立新的 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 檔案是專案的 Project 物件模型（POM）。

Install the package

在文字編輯器中開啟 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.
    }
}

程式碼範例

請遵循下列步驟，將必要的代碼段新增至檔案 App.java 的主要函式。

列出 Azure 入口網站中的 WhatsApp 範本。
使用本文中的文字參數傳送範本訊息。
使用標頭中的媒體參數傳送範本訊息。
使用快速回復按鈕傳送範本訊息。
傳送具有動作按鈕和動態連結呼叫的範本訊息。

列出 Azure 入口網站中的 WhatsApp 範本

若要在 Azure 入口網站中檢視範本，請移至 Azure 通訊服務資源>進階傳>訊範本。

選取範本以檢視範本詳細數據。

範本詳細資料的 [內容] 字段可以包含參數係結。參數繫結可以表示為：

"format"具有值的欄位，例如 IMAGE。
括住數字的雙括弧，例如 {{1}}。從 1 開始的數位索引表示必須提供系結值的順序，才能建立訊息範本。

或者，您可以在 WhatsApp Manager 帳戶工具>訊息範本中檢視和編輯所有 WhatsApp Business 帳戶範本。>

若要以程式設計方式列出範本，您可以使用下列程式代碼來擷取通道標識碼的所有範本：

public static void getMessageTemplateWithConnectionString() {
    MessageTemplateClient templateClient =
        new MessageTemplateClientBuilder()
            .connectionString(connectionString)
            .buildClient();

    PagedIterable<MessageTemplateItem> response = templateClient.listTemplates(channelRegistrationId);

    response.stream().forEach(t -> {
        WhatsAppMessageTemplateItem template = (WhatsAppMessageTemplateItem) t ;
        System.out.println("===============================");
        System.out.println("Template Name :: "+template.getName());
        System.out.println("Template Language :: "+template.getLanguage());
        System.out.println("Template Status :: "+template.getStatus());
        System.out.println("Template Content :: "+template.getContent());
        System.out.println("===============================");
    });
    }

使用本文中的文字參數傳送範本訊息

如果範本不採用任何參數，則不需要在建立 MessageTemplate時提供任何值或系結。

 /*
    * This sample shows how to send template message with below details
    * Name: sample_shipping_confirmation, Language: en_US
    *  [
          {
            "type": "BODY",
            "text": "Your package has been shipped. It will be delivered in {{1}} business days."
          },
          {
            "type": "FOOTER",
            "text": "This message is from an unverified business."
          }
        ]
* */
private static void sendTemplateMessage() {

    //Update Template Name and language according your template associate to your channel.
    MessageTemplate template = new MessageTemplate("sample_shipping_confirmation", "en_US");

    //Update template parameter type and value
    List<MessageTemplateValue> messageTemplateValues = new ArrayList<>();
    messageTemplateValues.add(new MessageTemplateText("Days", "5"));
    template.setValues(messageTemplateValues);

    //Update template parameter binding
    List<WhatsAppMessageTemplateBindingsComponent> components = new ArrayList<>();
    components.add(new WhatsAppMessageTemplateBindingsComponent("Days"));
    MessageTemplateBindings bindings =new WhatsAppMessageTemplateBindings()
        .setBody(components);
    template.setBindings(bindings);

    NotificationMessagesClient client = createClientWithTokenCredential();
    SendMessageResult result = client.send(
        new TemplateNotificationContent(CHANNEL_ID, recipients, template));

    result.getReceipts().forEach(r -> System.out.println("Message sent to:"+r.getTo() + " and message id:"+ r.getMessageId()));
    }

在標頭中使用媒體參數傳送範本訊息

使用 MessageTemplateImage、MessageTemplateVideo 或 MessageTemplateDocument 定義標頭中的媒體參數。

標頭中具有影像媒體參數的範本定義：

{
  "type": "HEADER",
  "format": "VIDEO"
},

"format"可以是 WhatsApp 支援的四種不同媒體類型。在 .NET SDK 中，每個媒體類型都會使用對應的 MessageTemplateValue 類型。

格式	MessageTemplateValue 類型	檔案類型
IMAGE	`MessageTemplateImage`	png、jpg
影片	`MessageTemplateVideo`	mp4
DOCUMENT	`MessageTemplateDocument`	PDF

如需支持媒體類型和大小限制的詳細資訊，請參閱 WhatsApp 的訊息媒體檔。

範例

sample_happy_hour_announcement 樣本：

在這裡，範本的標頭需要影片：

{
  "type": "HEADER",
  "format": "VIDEO"
},

影片必須是託管 mp4 視訊的 URL。

如需支持媒體類型和大小限制的詳細資訊，請參閱 WhatsApp 的訊息媒體檔。

樣本本文需要兩個文字參數：

{
  "type": "BODY",
  "text": "Happy hour is here! 🍺😀🍸\nPlease be merry and enjoy the day. 🎉\nVenue: {{1}}\nTime: {{2}}"
},

建立一個 MessageTemplateText 和四個 MessageTemplateVideo 變數。然後，以參數出現在範本內容中的順序提供參數，組合您的 MessageTemplateValue 清單和 MessageTemplateWhatsAppBindings。

 /*
    * This sample shows how to send template message with below details
    * Name: sample_happy_hour_announcement, Language: en_US
    *  [
          {
            "type": "HEADER",
            "format": "VIDEO"
          },
          {
            "type": "BODY",
            "text": "Happy hour is here! 🍺😀🍸\nPlease be merry and enjoy the day. 🎉\nVenue: {{1}}\nTime: {{2}}"
          },
          {
            "type": "FOOTER",
            "text": "This message is from an unverified business."
          }
        ]
* */
private static void sendTemplateMessageWithVideo() {

    //Update Template Name and language according your template associate to your channel.
    MessageTemplate template = new MessageTemplate("sample_happy_hour_announcement", "en_US");

    //Add template parameter type with value in a list
    List<MessageTemplateValue> messageTemplateValues = new ArrayList<>();
    messageTemplateValues.add(new MessageTemplateVideo("HeaderVideo", "https://sample-videos.com/video123/mp4/720/big_buck_bunny_720p_1mb.mp4"));
    messageTemplateValues.add(new MessageTemplateText("VenueInfoInBody", "Starbucks"));
    messageTemplateValues.add(new MessageTemplateText("TimeInfoInBody", "Today 2-4PM"));

    // Add parameter binding for template header in a list
    List<WhatsAppMessageTemplateBindingsComponent> templateHeaderBindings = new ArrayList<>();
    templateHeaderBindings.add(new WhatsAppMessageTemplateBindingsComponent("HeaderVideo"));

    // Add parameter binding for template body in a list
    List<WhatsAppMessageTemplateBindingsComponent> templateBodyBindings = new ArrayList<>();
    templateBodyBindings.add(new WhatsAppMessageTemplateBindingsComponent("VenueInfoInBody"));
    templateBodyBindings.add(new WhatsAppMessageTemplateBindingsComponent("TimeInfoInBody"));

    MessageTemplateBindings templateBindings = new WhatsAppMessageTemplateBindings()
        .setHeaderProperty(templateHeaderBindings) // Set the parameter binding for template header
        .setBody(templateBodyBindings); // Set the parameter binding for template body

    template
        .setBindings(templateBindings)
        .setValues(messageTemplateValues);

    NotificationMessagesClient client = createClientWithConnectionString();
    SendMessageResult result = client.send(
        new TemplateNotificationContent(CHANNEL_ID, recipients, template));

    result.getReceipts().forEach(r -> System.out.println("Message sent to:"+r.getTo() + " and message id:"+ r.getMessageId()));
}

使用快速回復按鈕傳送範本訊息

使用 MessageTemplateQuickAction 來定義快速回復按鈕和 MessageTemplateQuickAction 對象的承載，具有下列三個屬性。

屬性	描述	類型
名稱	`name`，用來查閱中的`MessageTemplateWhatsAppBindings`值。	字串
Text	選項快速動作 `text`。	字串
酬載	`payload`如果使用者選取按鈕，則指派給訊息回復中可用的按鈕。	字串

具有快速回覆按鈕的樣本定義：

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "QUICK_REPLY",
      "text": "Yes"
    },
    {
      "type": "QUICK_REPLY",
      "text": "No"
    }
  ]
}

按鈕出現在範本定義中的順序必須符合使用建立系結 MessageTemplateWhatsAppBindings時所定義按鈕的順序。

如需使用者快速回復響應中承載的詳細資訊，請參閱 WhatsApp 從快速回復按鈕接收回呼的檔。

範例

sample_issue_resolution 樣本：

樣本的本文需要一個文字參數：

/*
    * This sample shows how to send template message with below details
    * Name: sample_issue_resolution, Language: en_US
    *  [
          {
            "type": "BODY",
            "text": "Hi {{1}}, were we able to solve the issue that you were facing?"
          },
          {
            "type": "FOOTER",
            "text": "This message is from an unverified business."
          },
          {
            "type": "BUTTONS",
            "buttons": [
              {
                "type": "QUICK_REPLY",
                "text": "Yes"
              },
              {
                "type": "QUICK_REPLY",
                "text": "No"
              }
            ]
          }
        ]
* */
private static void sendTextTemplateMessageWithQuickReply() {

    //Add template parameter type with value in a list
    List<MessageTemplateValue> messageTemplateValues = new ArrayList<>();
    messageTemplateValues.add(new MessageTemplateText("Name", "Arif"));
    messageTemplateValues.add(new MessageTemplateQuickAction("Yes").setPayload("Yes"));
    messageTemplateValues.add(new MessageTemplateQuickAction("No").setPayload("No"));

    // Add parameter binding for template body in a list
    List<WhatsAppMessageTemplateBindingsComponent> templateBodyBindings = new ArrayList<>();
    templateBodyBindings.add(new WhatsAppMessageTemplateBindingsComponent("Name"));

    // Add parameter binding for template buttons in a list
    List<WhatsAppMessageTemplateBindingsButton> templateButtonBindings = new ArrayList<>();
    templateButtonBindings.add( new WhatsAppMessageTemplateBindingsButton(WhatsAppMessageButtonSubType.QUICK_REPLY, "Yes"));
    templateButtonBindings.add( new WhatsAppMessageTemplateBindingsButton(WhatsAppMessageButtonSubType.QUICK_REPLY, "No"));

    MessageTemplateBindings templateBindings = new WhatsAppMessageTemplateBindings()
        .setBody(templateBodyBindings) // Set the parameter binding for template body
        .setButtons(templateButtonBindings); // Set the parameter binding for template buttons

    MessageTemplate messageTemplate = new MessageTemplate("sample_issue_resolution", "en_US")
        .setBindings(templateBindings)
        .setValues(messageTemplateValues);

    NotificationMessagesClient client = createClientWithConnectionString();
    SendMessageResult result = client.send(
        new TemplateNotificationContent(CHANNEL_ID, recipients, messageTemplate));

    result.getReceipts().forEach(r -> System.out.println("Message sent to:"+r.getTo() + " and message id:"+ r.getMessageId()));
}

傳送具有動作按鈕和動態連結呼叫的範本訊息

使用 MessageTemplateQuickAction 來定義呼叫動作按鈕和 MessageTemplateQuickAction 物件的 URL 後綴，具有下列兩個屬性。

屬性	描述	類型
名稱	`name`，用來查閱中的`MessageTemplateWhatsAppBindings`值。	字串
Text	`text`附加至網址的。	字串

範本定義按鈕：

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "URL",
      "text": "Take Survey",
      "url": "https://www.example.com/{{1}}"
    }
  ]
}

按鈕出現在範本定義中的順序必須符合使用建立系結 MessageTemplateWhatsAppBindings時所定義按鈕的順序。

範例

sample_purchase_feedback 樣本：

此範例範本會將具有動態 URL 連結的按鈕新增至訊息。也會在標頭中使用影像，並在內文中使用文字參數。

在此範例中，範本的標頭需要影像：

{
  "type": "HEADER",
  "format": "IMAGE"
},

樣本的本文需要一個文字參數：

{
  "type": "BODY",
  "text": "Thank you for purchasing {{1}}! We value your feedback and would like to learn more about your experience."
},

此樣本包含具有一個參數的動態URL 按鈕：

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "URL",
      "text": "Take Survey",
      "url": "https://www.example.com/{{1}}"
    }
  ]
}

建立一個 MessageTemplateImage、一個 MessageTemplateText 和一個 MessageTemplateQuickAction 變數。然後，以參數出現在範本內容中的順序提供參數，組合您的 MessageTemplateValue 清單和 MessageTemplateWhatsAppBindings。定義系結按鈕時，順序也很重要。

/*
* This sample shows how to send template message with below details
* Name: sample_purchase_feedback, Language: en_US
*  [
        {
        "type": "HEADER",
        "format": "IMAGE"
        },
        {
        "type": "BODY",
        "text": "Thank you for purchasing {{1}}! We value your feedback and would like to learn more about your experience."
        },
        {
        "type": "FOOTER",
        "text": "This message is from an unverified business."
        },
        {
        "type": "BUTTONS",
        "buttons": [
            {
            "type": "URL",
            "text": "Take Survey",
            "url": "https://www.example.com/"
            }
        ]
        }
    ]
* */
private static void sendTemplateMessageWithImage() {

    //Update Template Name and language according your template associate to your channel.
    MessageTemplate template = new MessageTemplate("sample_purchase_feedback", "en_US");

    //Add template parameter type with value in a list
    List<MessageTemplateValue> messageTemplateValues = new ArrayList<>();
    messageTemplateValues.add(new MessageTemplateImage("HeaderImage", "https://upload.wikimedia.org/wikipedia/commons/3/30/Building92microsoft.jpg"));
    messageTemplateValues.add(new MessageTemplateText("ProductInfoInBody", "Microsoft Office"));

    // Add parameter binding for template header in a list
    List<WhatsAppMessageTemplateBindingsComponent> templateHeaderBindings = new ArrayList<>();
    templateHeaderBindings.add(new WhatsAppMessageTemplateBindingsComponent("HeaderImage"));

    // Add parameter binding for template body in a list
    List<WhatsAppMessageTemplateBindingsComponent> templateBodyBindings = new ArrayList<>();
    templateBodyBindings.add(new WhatsAppMessageTemplateBindingsComponent("ProductInfoInBody"));

    MessageTemplateBindings templateBindings = new WhatsAppMessageTemplateBindings()
        .setHeaderProperty(templateHeaderBindings) // Set the parameter binding for template header
        .setBody(templateBodyBindings); // Set the parameter binding for template body

    template
        .setBindings(templateBindings)
        .setValues(messageTemplateValues);

    NotificationMessagesClient client = createClientWithConnectionString();
    SendMessageResult result = client.send(
        new TemplateNotificationContent(CHANNEL_ID, recipients, template));

    result.getReceipts().forEach(r -> System.out.println("Message sent to:"+r.getTo() + " and message id:"+ r.getMessageId()));
}

執行程式碼

開啟包含檔案的 pom.xml 目錄，並使用 mvn 命令編譯專案。
```
mvn compile
```

藉由執行下列 mvn 命令來執行應用程式。

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

完整範例程式碼

在 GitHub 上尋找本快速入門的最終程式碼。

必要條件

向 Azure 通訊服務資源註冊 WhatsApp Business 帳戶。
建立 WhatsApp 範本訊息。
要接收訊息的作用中 WhatsApp 電話號碼。
Node.js Active LTS 和維護 LTS 版本（我們建議使用 8.11.1 和 10.14.1）。
Node.js建議使用中 LTS 和維護 LTS 版本（建議使用 8.11.1 和 10.14.1）
- 在終端機或命令視窗中執行 node --version，確認已安裝 Node.js

物件模型

下列類別和介面會處理適用於 Javascript 的 Azure 通訊服務 Messages SDK 的一些主要功能。

類別名稱	描述
`NotificationMessagesClient`	線上到您的 Azure 通訊服務資源。它會傳送訊息。
`MessageTemplate`	定義您使用的範本，以及訊息範本屬性的內容。
`TemplateNotificationContent`	定義您想要傳送之範本訊息的「誰」和「內容」。

注意

如需詳細資訊，請參閱適用於 JavaScript 的 Azure SDK 參考 @azure-rest/communication-messages 套件

支援的 WhatsApp 範本類型

範本類型	描述
以文字為基礎的訊息範本	WhatsApp 訊息範本是具有或不含參數的特定訊息格式。
以媒體為基礎的訊息範本	WhatsApp 訊息範本與標頭元件的媒體參數。
互動式訊息範本	互動式訊息範本會展開您可以傳送收件者的內容，方法是使用 components 物件來包含互動式按鈕。同時支援通話和快速回復。
以位置為基礎的訊息範本	WhatsApp 訊息範本，其位置參數在標頭元件的經度和緯度方面。

一般設定

請遵循下列步驟，將必要的代碼段新增至檔案 send-messages.js 的主要函式。

建立和管理 WhatsApp 範本訊息。
驗證用戶端。
設定通道註冊標識碼。
設定收件者清單。

建立和管理 WhatsApp 範本訊息

WhatsApp 訊息範本是企業用來將通知或客戶服務訊息傳送給加入通知的人員的特定訊息格式。訊息可以包含約會提醒、出貨資訊、問題解決或付款更新。 在開始使用進階傳訊 SDK 來傳送範本化訊息之前，用戶必須在 WhatsApp Business Platform 中建立必要的範本。

如需範本 WhatsApp 需求的詳細資訊，請參閱 WhatsApp Business Platform API 參考：

建立和管理範本。
檢視範本元件。
傳送範本訊息。
企業也必須遵守選擇加入要求，才能將訊息傳送給 WhatsApp 使用者。

開始在企業與 WhatsApp 使用者之間傳送訊息

WhatsApp Business 帳戶與 WhatsApp 使用者之間的交談可以透過下列兩種方式來開始：

企業將範本訊息傳送給 WhatsApp 使用者。
WhatsApp 使用者將任何訊息傳送給企業號碼。

不論交談如何開始，企業只能傳送範本訊息，直到使用者傳送訊息給企業為止。只有在使用者傳送訊息給企業之後，企業才能在作用中交談期間將文字或媒體訊息傳送給使用者。一旦 24 小時交談視窗過期，就必須重新開始交談。若要深入了解交談，請參閱 WhatsApp Business Platform 中的定義。

驗證用戶端

以下程式碼會使用 dotenv 套件從名為 COMMUNICATION_SERVICES_CONNECTION_STRING 的環境變數中，擷取資源的連接字串。

為了簡單起見，本快速入門會使用連接字串進行驗證。在實際執行環境中，我們建議服務主體。

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

如需如何為系統設定環境變數的詳細資訊，請遵循將連接字串儲存在環境變數中的步驟。

若要具現化 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 會嘗試透過 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 套件。
```
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>"

新增環境變數之後，您可能需要重新啟動任何需要讀取環境變數的執行中程式，包括主控台視窗。例如，如果您使用 Visual Studio 作為編輯器，請在執行範例前重新啟動 Visual Studio。

如需如何為系統設定環境變數的詳細資訊，請遵循將連接字串儲存在環境變數中的步驟。

若要具現化 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);

設定頻道註冊識別碼

頻道註冊識別碼 GUID 是在頻道註冊期間建立。您可以在入口網站中的 Azure 通訊服務資源 [頻道] 索引標籤上查閱。

將其指派給名為 channelRegistrationId 的變數。

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

設定收件者清單

您必須提供與 WhatsApp 帳戶相關聯的真實電話號碼。此 WhatsApp 帳戶會接收本快速入門中傳送的範本、文字和媒體訊息。針對本快速入門，此電話號碼可能是您的個人電話號碼。

收件者電話號碼不能是與 WhatsApp 頻道註冊相關聯的商務電話號碼 (傳送者識別碼)。傳送者識別碼會顯示為傳送給收件者之文字和媒體訊息的傳送者。

電話號碼應包含國碼 (地區碼)。如需電話號碼格式的詳細資訊，請參閱 whatsApp 文件中的電話號碼格式。

注意

收件者清單中目前僅支援一個電話號碼。

建立如下的收件者清單：

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

範例：

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

設定

若要設定傳送訊息的環境，請完成下列各節中的步驟。

建立新的 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 檔案。

Install the package

使用 npm install 命令，以安裝適用於 JavaScript 的 Azure 通訊服務進階傳訊 SDK。

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

--save 選項會在您的 package.json 檔案中，將程式庫列為相依性。

程式碼範例

請遵循下列步驟，將必要的代碼段新增至檔案 send-messages.js 的主要函式。

列出 Azure 入口網站中的 WhatsApp 範本。
使用本文中的文字參數傳送範本訊息。

列出 Azure 入口網站中的 WhatsApp 範本

若要在 Azure 入口網站中檢視您的範本，請移至 Azure 通訊服務資源>進階傳>訊範本。

選取範本以檢視範本詳細數據。

範本詳細資料的 [內容] 字段可以包含參數係結。參數繫結可以表示為：

"format"具有值的欄位，例如 IMAGE。
括住數字的雙括弧，例如 {{1}}。從 1 開始的數位索引表示必須提供系結值的順序，才能建立訊息範本。

或者，您可以在 WhatsApp Manager 帳戶工具>訊息範本中檢視和編輯所有 WhatsApp Business 帳戶範本。>

若要以程式設計方式列出範本，您可以使用下列程式代碼來擷取通道標識碼的所有範本：

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

/**
 * @summary Get Template list for a channel
 */

const MessageTemplateClient = require("@azure-rest/communication-messages").default,
  { isUnexpected } = require("@azure-rest/communication-messages");

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

async function main() {
  const connectionString = process.env.COMMUNICATION_LIVETEST_STATIC_CONNECTION_STRING || "";
  const client = MessageTemplateClient(connectionString);
  console.log("Fetch Templates...");
  const response = await client
    .path("/messages/channels/{channelId}/templates", process.env.CHANNEl_ID || "")
    .get({
      queryParameters: { maxPageSize: 2 },
    });

  if (isUnexpected(response)) {
    throw new Error("Failed to get template for the channel.");
  }

  // The paginate helper creates a paged async iterator using metadata from the first page.
  const items = paginate(client, response);

  // We get an PageableAsyncIterator so we need to do `for await`.
  for await (const item of items) {
    console.log(JSON.stringify(item, null, 2));
  }
}

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

使用本文中的文字參數傳送範本訊息

sample_shipping_confirmation 樣本：

在此範例中，範本的內文有一個參數：

{
  "type": "BODY",
  "text": "Your package has been shipped. It will be delivered in {{1}} business days."
},

參數會使用 values 值和 bindings 繫結來定義。使用值和系結來組合 template 物件。

 /*
    * This sample shows how to send template message with below details
    * Name: sample_shipping_confirmation, Language: en_US
    *  [
          {
            "type": "BODY",
            "text": "Your package has been shipped. It will be delivered in {{1}} business days."
          },
          {
            "type": "FOOTER",
            "text": "This message is from an unverified business."
          }
        ]
* */
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

/**
 * @summary Use AAD token credentials when sending a whatsapp template message.
 */

const { isNode } = require("@azure/core-util");
const { ClientSecretCredential, DefaultAzureCredential } = require("@azure/identity");
const NotificationClient = require("@azure-rest/communication-messages").default,
  { isUnexpected } = require("@azure-rest/communication-messages");

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

async function main() {
  // You will need to set this environment variable or edit the following values
  const endpoint = process.env.ACS_URL || "";

  // Azure AD Credential information is required to run this sample:
  if (
    !process.env.AZURE_TENANT_ID ||
    !process.env.AZURE_CLIENT_ID ||
    !process.env.AZURE_CLIENT_SECRET
  ) {
    console.error(
      "Azure AD authentication information not provided, but it is required to run this sample. Exiting.",
    );
    return;
  }

  // get credentials
  const credential = isNode
    ? new DefaultAzureCredential()
    : new ClientSecretCredential(
        process.env.AZURE_TENANT_ID,
        process.env.AZURE_CLIENT_ID,
        process.env.AZURE_CLIENT_SECRET,
      );

  const client = NotificationClient(endpoint, credential);

  const DaysTemplateValue = {
    kind: "text",
    name: "Days",
    text: "5",
  };

  const templateBindings = {
    kind: "whatsApp",
    body: [
      {
        refValue: "Days",
      },
    ],
  };

  const template = {
    name: "sample_shipping_confirmation",
    language: "en_US",
    bindings: templateBindings,
    values: [DaysTemplateValue],
  };

  const result = await client.path("/messages/notifications:send").post({
    contentType: "application/json",
    body: {
      channelRegistrationId: process.env.CHANNEL_ID || "",
      to: [process.env.RECIPIENT_PHONE_NUMBER || ""],
      kind: "template",
      template: template,
    },
  });

  console.log("Response: " + JSON.stringify(result, null, 2));

  if (isUnexpected(result)) {
    throw new Error("Failed to send message");
  }

  const response = result;
  response.body.receipts.forEach((receipt) => {
    console.log("Message sent to:" + receipt.to + " with message id:" + receipt.messageId);
  });
}

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

module.exports = { main };

執行程式碼

使用節點命令來執行您新增至 send-messages.js 檔案的程式碼。

node ./send-messages.js

完整範例程式碼

在 GitHub 上尋找此範例的完成程式代碼。

必要條件

向 Azure 通訊服務資源註冊 WhatsApp Business 帳戶。
建立 WhatsApp 範本訊息。
要接收訊息的作用中 WhatsApp 電話號碼。

物件模型

下列類別和介面會處理適用於 Python 的 Azure 通訊服務訊息 SDK 的一些主要功能。

類別名稱	描述
`NotificationMessagesClient`	線上到您的 Azure 通訊服務資源。它會傳送訊息。
`MessageTemplate`	定義您使用的範本，以及訊息範本屬性的內容。
`TemplateNotificationContent`	定義您想要傳送之範本訊息的「誰」和「內容」。

注意

如需詳細資訊，請參閱適用於 Python 的 Azure SDK 參考訊息套件。

支援的 WhatsApp 範本類型

範本類型	描述
以文字為基礎的訊息範本	WhatsApp 訊息範本是具有或不含參數的特定訊息格式。
以媒體為基礎的訊息範本	WhatsApp 訊息範本與標頭元件的媒體參數。
互動式訊息範本	互動式訊息範本會展開您可以傳送收件者的內容，方法是使用 components 物件來包含互動式按鈕。同時支援通話和快速回復。
以位置為基礎的訊息範本	WhatsApp 訊息範本，其位置參數在標頭元件的經度和緯度方面。

一般設定

請遵循下列步驟，將必要的代碼段新增至 messages-quickstart.py Python 程式。

建立和管理 WhatsApp 範本訊息。
驗證用戶端。
設定通道註冊標識碼。
設定收件者清單。

建立和管理 WhatsApp 範本訊息

WhatsApp 訊息範本是企業用來將通知或客戶服務訊息傳送給加入通知的人員的特定訊息格式。訊息可以包含約會提醒、出貨資訊、問題解決或付款更新。 在開始使用進階傳訊 SDK 來傳送範本化訊息之前，用戶必須在 WhatsApp Business Platform 中建立必要的範本。

如需範本 WhatsApp 需求的詳細資訊，請參閱 WhatsApp Business Platform API 參考：

建立和管理範本。
檢視範本元件。
傳送範本訊息。
企業也必須遵守選擇加入要求，才能將訊息傳送給 WhatsApp 使用者。

驗證用戶端

訊息傳送是使用 NotificationMessagesClient 完成。 NotificationMessagesClient 是使用在 Azure 入口網站中從 Azure 通訊服務資源取得的連接字串進行驗證。如需連接字串的詳細資訊，請參閱存取您的連接字串和服務端點 (部分機器翻譯)。

如螢幕快照所示，從 Azure 入口網站取得 Azure 通訊資源連接字串。在左側瀏覽至 Keys 索引標籤。複製主索引鍵的 Connection string 欄位。連接字串格式如下：endpoint=https://{your Azure Communication Services resource name}.communication.azure.com/;accesskey={secret key}。

顯示 Azure 入口網站中 Azure 通訊服務資源的螢幕擷取畫面，檢視 [索引鍵] 區段中的 [主索引鍵] 欄位。

將環境變數 COMMUNICATION_SERVICES_CONNECTION_STRING 設定為連接字串的值。
開啟主控台視窗並輸入下列命令：

setx COMMUNICATION_SERVICES_CONNECTION_STRING "<your connection string>"

新增環境變數之後，您可能需要重新啟動任何需要讀取環境變數的執行中程式，包括主控台視窗。例如，如果您使用 Visual Studio 作為編輯器，請在執行範例前重新啟動 Visual Studio。

如需如何為系統設定環境變數的詳細資訊，請遵循將連接字串儲存在環境變數中的步驟。

    # 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 會嘗試透過 several mechanisms 進行驗證，如果您已登入Visual Studio 或 Azure CLI，可能會取得其驗證認證。不過，此選項會逐步引導您使用環境變數進行設定。

若要建立 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>"

新增環境變數之後，您可能需要重新啟動任何需要讀取環境變數的執行中程式，包括主控台視窗。例如，如果您使用 Visual Studio 作為編輯器，請在執行範例前重新啟動 Visual Studio。

如需如何為系統設定環境變數的詳細資訊，請遵循將連接字串儲存在環境變數中的步驟。

若要具現化 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))

設定頻道註冊識別碼

您在通道註冊期間建立了通道註冊標識碼 GUID。在您的 Azure 通訊服務資源的 [通道] 索引標籤上，在入口網站中尋找它。

將其指派給名為 channelRegistrationId 的變數。

    channelRegistrationId = os.getenv("WHATSAPP_CHANNEL_ID_GUID")

設定收件者清單

您必須提供與 WhatsApp 帳戶相關聯的使用中電話號碼。此 WhatsApp 帳戶會接收本快速入門中傳送的範本、文字和媒體訊息。

在此範例中，您可以使用個人電話號碼。

收件者電話號碼不能是與 WhatsApp 頻道註冊相關聯的商務電話號碼 (傳送者識別碼)。傳送者識別碼會顯示為傳送給收件者之文字和媒體訊息的傳送者。

電話號碼必須包含國家/地區代碼。如需電話號碼格式的詳細資訊，請參閱 WhatsApp 檔中的電話號碼格式。

注意

收件者清單中目前僅支援一個電話號碼。

設定如下的收件者清單：

    phone_number = os.getenv("RECIPIENT_WHATSAPP_PHONE_NUMBER")

使用範例：

    # Example only
    to=[self.phone_number],

開始在企業與 WhatsApp 使用者之間傳送訊息

WhatsApp Business 帳戶與 WhatsApp 使用者之間的交談可以透過下列兩種方式來開始：

企業將範本訊息傳送給 WhatsApp 使用者。
WhatsApp 使用者將任何訊息傳送給企業號碼。

企業無法起始互動式交談。企業只能在收到來自使用者的訊息之後傳送互動式訊息。企業只能在作用中的交談期間傳送互動式訊息給使用者。一旦 24 小時交談視窗到期，只有使用者可以重新啟動互動式交談。如需交談的詳細資訊，請參閱 WhatsApp Business Platform 的定義。

若要從您的個人 WhatsApp 帳戶起始互動式交談，請將訊息傳送至您的商務號碼（寄件人標識符）。

設定環境

建立新的 Python 應用程式

在終端機或主控台視窗中，為您的應用程式建立新資料夾並加以開啟。

mkdir messages-quickstart && cd messages-quickstart

Install the package

使用適用於 Python 1.1.0 或更新版本之 Azure 通訊訊息用戶端連結庫。

從主控台提示字元中，執行下列命令：

pip install azure-communication-messages

針對 InteractiveMessages、反應和貼紙，請使用下列 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()

基本程式結構

import os

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

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

程式碼範例

請遵循下列步驟，將必要的代碼段新增至 messages-quickstart.py Python 程式。

列出 Azure 入口網站中的 WhatsApp 範本。
傳送沒有參數的範本訊息。
使用本文中的文字參數傳送範本訊息。
使用標頭中的媒體參數傳送範本訊息。
傳送標頭中位置的範本訊息。
使用快速回復按鈕傳送範本訊息。
使用動態連結來傳送具有動作按鈕呼叫的範本訊息。

列出 Azure 入口網站中的 WhatsApp 範本

您可以移至 Azure 通訊服務資源>進階傳訊>範本，以在 Azure 入口網站中檢視範本。

選取範本以檢視範本詳細數據。

content範本詳細數據的欄位可以包含參數係結。參數繫結可以表示為：

format具有值的欄位，例如 IMAGE。
括住數字的雙括弧，例如 {{1}}。從 1 開始的數位索引表示必須提供系結值的順序，才能建立訊息範本。

或者，您也可以在 [WhatsApp Manager] > [帳戶工具] > [訊息範本] 中檢視和編輯所有 WhatsApp Business 帳戶的範本。

若要以程序設計方式列出範本，您可以擷取通道標識碼的所有範本，如下所示：

def get_templates_list(self):

    from azure.communication.messages import MessageTemplateClient
    message_template_client = MessageTemplateClient.from_connection_string(self.connection_string)
    # calling send() with whatsapp message details
    template_list = message_template_client.list_templates(self.channel_id)
    count_templates = len(list(template_list))
    print("Successfully retrieved {} templates from channel_id {}.".format(count_templates, self.channel_id))

傳送沒有參數的範本訊息

如果範本不需要參數，則不需要在建立 MessageTemplate時提供值或系結。

範例

sample_template沒有參數。

MessageTemplate藉參考目標樣本名稱與語言來組合。

input_template: MessageTemplate = MessageTemplate(name="gathering_invitation", language="ca")  # Name of the WhatsApp Template

使用本文中的文字參數傳送範本訊息

使用 MessageTemplateText，定義內文中透過雙括弧括住數字來表示的參數，例如 {{1}}。從 1 開始的數位索引表示必須提供系結值的順序，才能建立訊息範本。嘗試在範本中不包含參數無效。

具有兩個參數的範本定義：

{
  "type": "BODY",
  "text": "Message with two parameters: {{1}} and {{2}}"
}

範例

sample_shipping_confirmation 樣本：

在此範例中，範本的內文有一個參數：

{
  "type": "BODY",
  "text": "Your package has been shipped. It will be delivered in {{1}} business days."
},

使用 MessageTemplateValue 值和 MessageTemplateWhatsAppBindings 系結定義參數。使用值與繫結來組合 MessageTemplate。

# Setting template options
templateName = "sample_shipping_confirmation"
templateLanguage = "en_us" 
shippingConfirmationTemplate: MessageTemplate = MessageTemplate(name=templateName, language=templateLanguage )
threeDays = MessageTemplateText(name="threeDays", text="3")
bindings = WhatsAppMessageTemplateBindings(body=[WhatsAppMessageTemplateBindingsComponent(ref_value=threeDays.name)])
shippingConfirmationTemplate.bindings = bindings
shippingConfirmationTemplate.template_values=[threeDays]
template_options = TemplateNotificationContent(
    channel_registration_id=self.channel_id, to=[self.phone_number], template=shippingConfirmationTemplate
)

在標頭中使用媒體參數傳送範本訊息

使用 MessageTemplateImage、MessageTemplateVideo 或 MessageTemplateDocument 定義標頭中的媒體參數。

標頭中具有影像媒體參數的範本定義：

{
  "type": "HEADER",
  "format": "IMAGE"
},

format可以有 WhatsApp 支援的不同媒體類型。在 .NET SDK 中，每個媒體類型都會使用對應的 MessageTemplateValue 類型。

格式	MessageTemplateValue 類型	檔案類型
IMAGE	`MessageTemplateImage`	png、jpg
影片	`MessageTemplateVideo`	mp4
DOCUMENT	`MessageTemplateDocument`	PDF

如需支持媒體類型和大小限制的詳細資訊，請參閱 WhatsApp 的訊息媒體檔。

範例

sample_movie_ticket_confirmation 樣本：

在此範例中，範本的標頭需要影像：

{
  "type": "HEADER",
  "format": "IMAGE"
},

樣本本文需要四個文字參數：

{
  "type": "BODY",
  "text": "Your ticket for *{{1}}*\n*Time* - {{2}}\n*Venue* - {{3}}\n*Seats* - {{4}}"
},

建立一個 MessageTemplateText 和四個 MessageTemplateImage 變數。然後，依照參數出現在範本內容中的順序提供參數，以組合您的清單 MessageTemplateValue 和您的 MessageTemplateWhatsAppBindings 。

 # Setting template options
templateName = "sample_movie_ticket_confirmation"
templateLanguage = "en_us" 
imageUrl = "https://aka.ms/acsicon1"
sample_movie_ticket_confirmation: MessageTemplate = MessageTemplate(name=templateName, language=templateLanguage )
image = MessageTemplateImage(name="image", url=imageUrl)
title = MessageTemplateText(name="title", text="Contoso")
time = MessageTemplateText(name="time", text="July 1st, 2023 12:30PM")
venue = MessageTemplateText(name="venue", text="Southridge Video")
seats = MessageTemplateText(name="seats", text="Seat 1A")

bindings = WhatsAppMessageTemplateBindings(header=[WhatsAppMessageTemplateBindingsComponent(ref_value=image.name)],
                                            body=[WhatsAppMessageTemplateBindingsComponent(ref_value=title.name),
                                                    WhatsAppMessageTemplateBindingsComponent(ref_value=time.name),
                                                    WhatsAppMessageTemplateBindingsComponent(ref_value=venue.name),
                                                    WhatsAppMessageTemplateBindingsComponent(ref_value=seats.name)])
sample_movie_ticket_confirmation.bindings = bindings
sample_movie_ticket_confirmation.template_values=[image,title,time,venue,seats]
template_options = TemplateNotificationContent(
    channel_registration_id=self.channel_id, to=[self.phone_number], template=sample_movie_ticket_confirmation)

使用快速回復按鈕傳送範本訊息

使用 MessageTemplateQuickAction 來定義快速回復按鈕和 MessageTemplateQuickAction 對象的承載，具有下列三個屬性。

屬性	描述	類型
名稱	`name`要查閱中值之的 `MessageTemplateWhatsAppBindings`。	字串
Text	選項快速動作 `text`。	字串
酬載	`payload`如果使用者選取按鈕，則指派給訊息回復中可用的按鈕。	字串

具有快速回覆按鈕的樣本定義：

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "QUICK_REPLY",
      "text": "Yes"
    },
    {
      "type": "QUICK_REPLY",
      "text": "No"
    }
  ]
}

按鈕出現在範本定義中的順序必須符合使用建立系結 MessageTemplateWhatsAppBindings時所定義按鈕的順序。

如需使用者快速回復響應中承載的詳細資訊，請參閱 WhatsApp 從快速回復按鈕接收回呼的檔。

範例

sample_issue_resolution 樣本：

樣本的本文需要一個文字參數：

{
  "type": "BODY",
  "text": "Hi {{1}}, were we able to solve the issue that you were facing?"
},

樣本包含兩個預先填入的回復按鈕， Yes 以及 No。

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "QUICK_REPLY",
      "text": "Yes"
    },
    {
      "type": "QUICK_REPLY",
      "text": "No"
    }
  ]
}

建立一個 MessageTemplateQuickAction 和兩個 MessageTemplateText 變數。然後，依照參數出現在範本內容中的順序提供參數，以組合您的清單 MessageTemplateValue 和您的 MessageTemplateWhatsAppBindings 。定義系結按鈕時，順序也很重要。

# Setting template options
templateName = "sample_issue_resolution"
templateLanguage = "en_us" 
shippingConfirmationTemplate: MessageTemplate = MessageTemplate(name=templateName, language=templateLanguage )
name = MessageTemplateText(name="first", text="Joe")
yes = MessageTemplateQuickAction(name="Yes", payload="Joe said yes")
no = MessageTemplateQuickAction(name="No", payload = "Joe said no")
bindings = WhatsAppMessageTemplateBindings(body=[WhatsAppMessageTemplateBindingsComponent(ref_value=name.name)])
bindings.buttons = [WhatsAppMessageTemplateBindingsButton(sub_type=WhatsAppMessageButtonSubType.QUICK_REPLY, ref_value=yes.name),
                    WhatsAppMessageTemplateBindingsButton(sub_type=WhatsAppMessageButtonSubType.QUICK_REPLY, ref_value=no.name)]
shippingConfirmationTemplate.bindings = bindings
shippingConfirmationTemplate.template_values=[name,yes,no]
template_options = TemplateNotificationContent(
    channel_registration_id=self.channel_id, to=[self.phone_number], template=shippingConfirmationTemplate
)

傳送標頭中位置的範本訊息

使用 MessageTemplateLocation 在標頭中定義location 參數。

標頭元件的範本定義，需要位置為：

{
  "type": "header",
  "parameters": [
    {
      "type": "location",
      "location": {
        "latitude": "<LATITUDE>",
        "longitude": "<LONGITUDE>",
        "name": "<NAME>",
        "address": "<ADDRESS>"
      }
    }
  ]
}

format可能需要不同的媒體類型。在 .NET SDK 中，每個媒體類型都會使用對應的 MessageTemplateValue 類型。

屬性	描述	類型
`ADDRESS`	出現在值之後 `NAME` 的位址，位於訊息頂端的泛型對應下方。	字串
`LATITUDE`	位置緯度。	double
`LONGITUDE`	位置經度。	double
`LOCATIONNAME`	出現在訊息頂端泛型對應下方的文字。	字串

如需位置型範本的詳細資訊，請參閱 WhatsApp 的訊息媒體檔。

範例

sample_movie_location 樣本：

以位置為基礎的訊息模組：

 # Setting template options
        templateName = "sample_movie_location"
        templateLanguage = "en_us" 
        sample_movie_location: MessageTemplate = MessageTemplate(name=templateName, language=templateLanguage )
        name = MessageTemplateText(name="first", text="Joe")
        location = MessageTemplateLocation(name="location", location_name="Pablo Morales",
                                            address="1 Hacker Way, Menlo Park, CA 94025",
                                            latitude=37.483307,longitude=122.148981)
        bindings = WhatsAppMessageTemplateBindings(body=[WhatsAppMessageTemplateBindingsComponent(ref_value=name.name)],
                                                    header=[WhatsAppMessageTemplateBindingsComponent(ref_value=location.name)])
        sample_movie_location.bindings = bindings
        sample_movie_location.template_values=[name,location]
        template_options = TemplateNotificationContent(
            channel_registration_id=self.channel_id, to=[self.phone_number], template=sample_movie_location)

使用動態連結傳送具有動作按鈕呼叫的範本訊息

使用 MessageTemplateQuickAction 來定義呼叫動作按鈕和 MessageTemplateQuickAction 物件的 URL 後綴，具有下列兩個屬性。

屬性	描述	類型
名稱	`name`，用來查閱中的`MessageTemplateWhatsAppBindings`值。	字串
Text	`text`附加至網址的。	字串

範本定義按鈕：

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "URL",
      "text": "Take Survey",
      "url": "https://www.example.com/{{1}}"
    }
  ]
}

按鈕出現在範本定義中的順序必須符合使用建立系結 MessageTemplateWhatsAppBindings時所定義按鈕的順序。

範例

sample_purchase_feedback 樣本：

此範例範本會將具有動態 URL 連結的按鈕新增至訊息。也會在標頭中使用影像，並在內文中使用文字參數。建立動作類型 URL Dynamic 類型的 View website 動作按鈕範本呼叫。

在此範例中，範本的標頭需要影像：

{
  "type": "HEADER",
  "format": "IMAGE"
},

樣本的本文需要一個文字參數：

{
  "type": "BODY",
  "text": "Thank you for purchasing {{1}}! We value your feedback and would like to learn more about your experience."
},

此樣本包含具有一個參數的動態URL 按鈕：

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "URL",
      "text": "Take Survey",
      "url": "https://www.example.com/{{1}}"
    }
  ]
}

建立一個 MessageTemplateImage、一個 MessageTemplateText 和一個 MessageTemplateQuickAction 變數。然後，依照參數出現在範本內容中的順序提供參數，以組合您的清單 MessageTemplateValue 和您的 MessageTemplateWhatsAppBindings 。定義系結按鈕時，順序也很重要。

# Setting template options
        templateName = "sample_purchase_feedback"
        templateLanguage = "en_us"
        imageUrl = "https://aka.ms/acsicon1" 
        sample_purchase_feedback: MessageTemplate = MessageTemplate(name=templateName, language=templateLanguage )
        name = MessageTemplateText(name="first", text="Joe")
        image = MessageTemplateImage(name="image", url=imageUrl)
        uri_to_click = MessageTemplateQuickAction(name="url", text="questions")

        bindings = WhatsAppMessageTemplateBindings(body=[WhatsAppMessageTemplateBindingsComponent(ref_value=name.name)],
                                                    header=[WhatsAppMessageTemplateBindingsComponent(ref_value=image.name)],
                                                    buttons=[WhatsAppMessageTemplateBindingsButton(sub_type=WhatsAppMessageButtonSubType.URL,
                                                    ref_value=uri_to_click.name)])
        sample_purchase_feedback.bindings = bindings
        sample_purchase_feedback.template_values=[name, image, uri_to_click]
        template_options = TemplateNotificationContent(
            channel_registration_id=self.channel_id, to=[self.phone_number], template=sample_purchase_feedback)

完整範例

import os
import sys

sys.path.append("..")

class SendWhatsAppTemplateMessageSample(object):

    connection_string = os.getenv("COMMUNICATION_SAMPLES_CONNECTION_STRING")
    phone_number = os.getenv("RECIPIENT_PHONE_NUMBER")
    channel_id = os.getenv("WHATSAPP_CHANNEL_ID")

    def send_template_message_without_parameters(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_template_message_with_parameters(self):

        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import (TemplateNotificationContent, MessageTemplate,
        MessageTemplateText, WhatsAppMessageTemplateBindings, WhatsAppMessageTemplateBindingsComponent)

        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)

        # Setting template options
        templateName = "sample_shipping_confirmation"
        templateLanguage = "en_us" 
        shippingConfirmationTemplate: MessageTemplate = MessageTemplate(name=templateName, language=templateLanguage )
        threeDays = MessageTemplateText(name="threeDays", text="3")
        bindings = WhatsAppMessageTemplateBindings(body=[WhatsAppMessageTemplateBindingsComponent(ref_value=threeDays.name)])
        shippingConfirmationTemplate.bindings = bindings
        shippingConfirmationTemplate.template_values=[threeDays]
        template_options = TemplateNotificationContent(
            channel_registration_id=self.channel_id, to=[self.phone_number], template=shippingConfirmationTemplate
        )

        # calling send() with whatsapp message details
        message_responses = messaging_client.send(template_options)
        response = message_responses.receipts[0]
        print("WhatsApp text parameters Templated Message with message id {} was successfully sent to {}"
            .format(response.message_id, response.to))

    def send_template_message_with_media(self):

        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import (TemplateNotificationContent, MessageTemplate,
        MessageTemplateText, WhatsAppMessageTemplateBindings, WhatsAppMessageTemplateBindingsComponent,
        MessageTemplateImage)

        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)

        # Setting template options
        templateName = "sample_movie_ticket_confirmation"
        templateLanguage = "en_us" 
        imageUrl = "https://aka.ms/acsicon1"
        sample_movie_ticket_confirmation: MessageTemplate = MessageTemplate(name=templateName, language=templateLanguage )
        image = MessageTemplateImage(name="image", url=imageUrl)
        title = MessageTemplateText(name="title", text="Contoso")
        time = MessageTemplateText(name="time", text="July 1st, 2023 12:30PM")
        venue = MessageTemplateText(name="venue", text="Southridge Video")
        seats = MessageTemplateText(name="seats", text="Seat 1A")

        bindings = WhatsAppMessageTemplateBindings(header=[WhatsAppMessageTemplateBindingsComponent(ref_value=image.name)],
                                                   body=[WhatsAppMessageTemplateBindingsComponent(ref_value=title.name),
                                                         WhatsAppMessageTemplateBindingsComponent(ref_value=time.name),
                                                         WhatsAppMessageTemplateBindingsComponent(ref_value=venue.name),
                                                         WhatsAppMessageTemplateBindingsComponent(ref_value=seats.name)])

        sample_movie_ticket_confirmation.bindings = bindings
        sample_movie_ticket_confirmation.template_values=[image,title,time,venue,seats]
        template_options = TemplateNotificationContent(
            channel_registration_id=self.channel_id, to=[self.phone_number], template=sample_movie_ticket_confirmation)

        # calling send() with whatsapp message details
        message_responses = messaging_client.send(template_options)
        response = message_responses.receipts[0]
        print("WhatsApp media parameters in templated message header with message id {} was successfully sent to {}"
            .format(response.message_id, response.to))

    def send_template_message_with_buttons(self):

        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import (TemplateNotificationContent, MessageTemplate,
        MessageTemplateText, WhatsAppMessageTemplateBindings, WhatsAppMessageTemplateBindingsComponent,
        MessageTemplateQuickAction, WhatsAppMessageTemplateBindingsButton, WhatsAppMessageButtonSubType)

        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)

        # Setting template options
        templateName = "sample_issue_resolution"
        templateLanguage = "en_us" 
        shippingConfirmationTemplate: MessageTemplate = MessageTemplate(name=templateName, language=templateLanguage )
        name = MessageTemplateText(name="first", text="Joe")
        yes = MessageTemplateQuickAction(name="Yes", payload="Joe said yes")
        no = MessageTemplateQuickAction(name="No", payload = "Joe said no")
        bindings = WhatsAppMessageTemplateBindings(body=[WhatsAppMessageTemplateBindingsComponent(ref_value=name.name)])
        bindings.buttons = [WhatsAppMessageTemplateBindingsButton(sub_type=WhatsAppMessageButtonSubType.QUICK_REPLY, ref_value=yes.name),
                            WhatsAppMessageTemplateBindingsButton(sub_type=WhatsAppMessageButtonSubType.QUICK_REPLY, ref_value=no.name)]
        shippingConfirmationTemplate.bindings = bindings
        shippingConfirmationTemplate.template_values=[name,yes,no]
        template_options = TemplateNotificationContent(
            channel_registration_id=self.channel_id, to=[self.phone_number], template=shippingConfirmationTemplate
        )

        # calling send() with whatsapp message details
        message_responses = messaging_client.send(template_options)
        response = message_responses.receipts[0]
        print("WhatsApp Quick Button Templated Message with message id {} was successfully sent to {}"
            .format(response.message_id, response.to))

    def send_template_message_with_location(self):

        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import (TemplateNotificationContent, MessageTemplate,
        MessageTemplateText, WhatsAppMessageTemplateBindings, WhatsAppMessageTemplateBindingsComponent,
        MessageTemplateLocation)

        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)

        # Setting template options
        templateName = "sample_movie_location"
        templateLanguage = "en_us" 
        sample_movie_location: MessageTemplate = MessageTemplate(name=templateName, language=templateLanguage )
        name = MessageTemplateText(name="first", text="Joe")
        location = MessageTemplateLocation(name="location", location_name="Pablo Morales",
                                            address="1 Hacker Way, Menlo Park, CA 94025",
                                            latitude=37.483307,longitude=122.148981)
        bindings = WhatsAppMessageTemplateBindings(body=[WhatsAppMessageTemplateBindingsComponent(ref_value=name.name)],
                                                    header=[WhatsAppMessageTemplateBindingsComponent(ref_value=location.name)])
        sample_movie_location.bindings = bindings
        sample_movie_location.template_values=[name,location]
        template_options = TemplateNotificationContent(
            channel_registration_id=self.channel_id, to=[self.phone_number], template=sample_movie_location)

        # calling send() with whatsapp message details
        message_responses = messaging_client.send(template_options)
        response = message_responses.receipts[0]
        print("WhatsApp Location Templated Message with message id {} was successfully sent to {}"
            .format(response.message_id, response.to))

    def send_template_message_with_call_to_action(self):

        from azure.communication.messages import NotificationMessagesClient
        from azure.communication.messages.models import (TemplateNotificationContent, MessageTemplate,
        MessageTemplateText, WhatsAppMessageTemplateBindings, WhatsAppMessageTemplateBindingsComponent,
        MessageTemplateQuickAction, MessageTemplateImage, WhatsAppMessageTemplateBindingsButton,
        WhatsAppMessageButtonSubType)

        messaging_client = NotificationMessagesClient.from_connection_string(self.connection_string)

        # Setting template options
        templateName = "sample_purchase_feedback"
        templateLanguage = "en_us"
        imageUrl = "https://aka.ms/acsicon1" 
        sample_purchase_feedback: MessageTemplate = MessageTemplate(name=templateName, language=templateLanguage )
        name = MessageTemplateText(name="first", text="Joe")
        image = MessageTemplateImage(name="image", url=imageUrl)
        uri_to_click = MessageTemplateQuickAction(name="url", text="questions")

        bindings = WhatsAppMessageTemplateBindings(body=[WhatsAppMessageTemplateBindingsComponent(ref_value=name.name)],
                                                    header=[WhatsAppMessageTemplateBindingsComponent(ref_value=image.name)],
                                                    buttons=[WhatsAppMessageTemplateBindingsButton(sub_type=WhatsAppMessageButtonSubType.URL,
                                                                                                    ref_value=uri_to_click.name)])
        sample_purchase_feedback.bindings = bindings
        sample_purchase_feedback.template_values=[name, image, uri_to_click]
        template_options = TemplateNotificationContent(
            channel_registration_id=self.channel_id, to=[self.phone_number], template=sample_purchase_feedback)

        # calling send() with whatsapp message details
        message_responses = messaging_client.send(template_options)
        response = message_responses.receipts[0]
        print("WhatsApp Call To Action Templated Message with message id {} was successfully sent to {}"
        .format(response.message_id, response.to))

if __name__ == "__main__":
    sample = SendWhatsAppTemplateMessageSample()
    sample.send_template_message_without_parameters()
    sample.send_template_message_with_parameters()
    sample.send_template_message_with_buttons()
    sample.send_template_message_with_location()
    sample.send_template_message_with_call_to_action()

執行程式碼

若要執行程式碼，請確定您位於 messages-quickstart.py 檔案所在的目錄中。

python messages-quickstart.py

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

共用方式為

必要條件

物件模型

支援的 WhatsApp 範本類型

一般設定

建立和管理 WhatsApp 範本訊息

驗證用戶端

設定頻道註冊識別碼

設定收件者清單

開始在企業與 WhatsApp 使用者之間傳送訊息

設定環境

建立 .NET 專案

Install the package

設定應用程式架構

程式碼範例

列出 Azure 入口網站 中的 WhatsApp 範本

傳送沒有參數的範本訊息

範例

使用本文中的文字參數傳送範本訊息

範例

在標頭中使用媒體參數傳送範本訊息

範例

更多範例

傳送標頭中位置的範本訊息

範例

使用快速回復按鈕傳送範本訊息

範例

使用動態連結傳送具有動作按鈕呼叫的範本訊息

範例

使用靜態連結傳送具有動作按鈕呼叫的範本訊息

範例

執行程式碼

完整的程式碼範例

更多範例

使用範例範本 sample_happy_hour_announcement

使用範例範本 sample_flight_confirmation

必要條件

物件模型

支援的 WhatsApp 範本類型

一般設定

建立和管理 WhatsApp 範本訊息

開始在企業與 WhatsApp 使用者之間傳送訊息

驗證用戶端

設定頻道註冊識別碼

設定收件者清單

設定環境

必要條件

建立新的 Java 應用程式

Install the package

設定應用程式架構

程式碼範例

列出 Azure 入口網站 中的 WhatsApp 範本

使用本文中的文字參數傳送範本訊息

在標頭中使用媒體參數傳送範本訊息

範例

使用快速回復按鈕傳送範本訊息

範例

傳送具有動作按鈕和動態連結呼叫的範本訊息

範例

執行程式碼

完整範例程式碼

必要條件

物件模型

支援的 WhatsApp 範本類型

一般設定

建立和管理 WhatsApp 範本訊息

開始在企業與 WhatsApp 使用者之間傳送訊息

驗證用戶端

設定頻道註冊識別碼

設定收件者清單

設定

建立新的 Node.js 應用程式

Install the package

程式碼範例

列出 Azure 入口網站 中的 WhatsApp 範本

使用本文中的文字參數傳送範本訊息

執行程式碼

完整範例程式碼

必要條件

列出 Azure 入口網站中的 WhatsApp 範本

列出 Azure 入口網站中的 WhatsApp 範本

列出 Azure 入口網站中的 WhatsApp 範本

列出 Azure 入口網站中的 WhatsApp 範本