中文(台灣) 的翻譯尚未完成。
訊息
使用 /PHONE_NUMBER_ID/messages 端點傳送文字、多媒體、聯絡人、地點、互動式訊息以及訊息範本給顧客。深入瞭解您可以傳送的訊息。
| 端點 | 驗證 |
|---|---|
（請參閱取得手機號碼編號） | Developers can authenticate their API calls with the access token generated in the App Dashboard > WhatsApp > API Setup.
Solution Partners must authenticate themselves with an access token with the |
訊息是由不重複的編號（WAMID）所識別。您可以透過 Webhooks 的 WAMID 來追蹤 Webhooks 中的訊息狀態，也可以透過訊息端點將傳入訊息標記為已讀。此 WAMID 的最大長度為 128 個字元。
訊息物件
若要傳送訊息，必須先將訊息物件與要傳送的內容組合在一起。以下是 message 物件中使用的參數：
| 名稱 | 說明（點擊左欄中的箭頭可查看支援的選項。） |
|---|---|
|
包含音訊的 |
| 選用項目。 任意字串，適用於追蹤。 例如，您可以在此欄位中傳遞訊息範本編號，以追蹤從您傳送第一則訊息開始的顧客歷程。您後續可以追蹤不同訊息範本類型的 ROI，以決定最有效的訊息範本類型。 任何已訂閱 WhatsApp Business 帳號之 雲端 API 不會處理此欄位，僅將其作為已傳送／已送達／已讀取訊息 Webhooks 的一部分傳回。 最多 512 個字元。 僅適用於雲端 API。 |
|
|
| 如果回覆對話中的任何訊息，則為必要項目。 物件，其中包含您要回覆之上一則訊息的編號。例如：
僅適用於雲端 API。 |
|
包含文件的 |
| 包含 僅適用於內部部署 API。 |
|
包含圖像的 |
|
|
|
|
| 必要項目 用於要求的傳訊服務。使用 僅適用於雲端 API。 |
|
允許在簡訊中預覽網址 - 請參閱在簡訊中傳送網址。如果訊息中不包含網址，此欄位為選用項目。值： |
| 選用項目。 目前只能向個人傳送訊息。請將此值設為 預設值： |
| 訊息的狀態。您可以使用此欄位將訊息標記為 |
|
包含貼圖的 雲端 API：除了支援所有類型的入站貼圖外，亦支援靜態和動畫第三方出站貼圖。靜態貼圖必須為 512x512 像素，且大小不得超過 100 KB。動畫貼圖必須為 512x512 像素，且大小不得超過 500 KB。 內部部署 API：除了支援所有類型的入站貼圖外，僅支援靜態第三方出站貼圖。靜態貼圖必須為 512x512 像素，且大小不得超過 100 KB。不支援動畫貼圖。 |
|
|
| 簡訊的必要項目。 |
| 必要項目。 接收訊息之顧客的 WhatsApp 編號或電話號碼。請參閱電話號碼格式。 如有需要，內部部署 API 用戶可以呼叫 |
| 選用項目。 您想要傳送的訊息類型。如果省略，預設值為 |
以下物件會以巢狀方式包含在訊息物件內：
聯絡人物件
| Name | Description |
|---|---|
| Optional. Full contact address(es) formatted as an
|
| Optional.
|
| Optional. Contact email address(es) formatted as an
|
| Required. Full contact name formatted as a
*At least one of the optional parameters needs to be included along with the |
| Optional. Contact organization information formatted as an
|
| Optional. Contact phone number(s) formatted as a
|
| Optional. Contact URL(s) formatted as a
|
互動式物件
| 名稱 | 說明 |
|---|---|
| 必要項目。 您希望用戶在讀取訊息後執行的動作。 |
|
包含訊息內文的物件。
|
| 選用項目。包含訊息頁尾的物件。
|
|
顯示於訊息頂端的標頭內容。如果互動式物件的類型為 |
| 必要項目。 您想要傳送的互動式訊息類型。支援的值：
|
以下物件會以巢狀方式包含在 interactive 物件內：
動作物件
| 名稱 | 說明 |
|---|---|
| 清單訊息時為必要項目。 按鈕內容。不得為空白字串，而且在訊息內必須是唯一的。支援表情符號但不支援 Markdown。 最大長度：20 個字元。 |
| 回覆按鈕時為必要項目。 按鈕物件可以包含下列參數：
最多可有 3 個按鈕。設定編號時不能有前置空格或結束空格。 |
| 單一產品訊息和多個產品訊息時為必要項目。 連結至 WhatsApp Business 帳號之 Facebook 目錄的不重複識別資料。您可透過 Meta 商業管理工具擷取此編號。 |
| 單一產品訊息和多個產品訊息時為必要項目。 產品在目錄中的不重複識別資料。 若要取得此編號，請前往 Meta 商業管理工具，然後選擇您的 Meta 商業帳號。您將看到與帳號連結的商店清單。點擊要使用的商店。在左側面板上，點擊「目錄」>「項目」，然後找到要提及的項目。該項目的編號顯示在項目名稱下方。 |
| 清單訊息和多個產品訊息時為必要項目。
|
| 流程訊息時為選用項目。 目前的流程模式，可為 預設： |
| 流程訊息時為必要項目。 必須為 |
| 流程訊息時為必要項目。 商家產生的權杖，用作識別碼。 |
| 流程訊息時為必要項目。 WhatsApp 提供的流程唯一識別碼。 |
| 流程訊息時為必要項目。 CTA 按鈕上的文字，例如：「Signup」。 最大長度：20 個字元（非表情符號）。 |
| 流程訊息時為選用項目。
預設： |
| 流程訊息時為選用項目。 僅當
|
標頭物件
| 名稱 | 說明 |
|---|---|
| 如果 包含本文件的多媒體物件。 |
| 如果 包含本圖像的多媒體物件。 |
| 如果 標頭文字。格式設定允許使用表情符號，但不允許使用 Markdown。 最大長度：60 個字元。 |
| 必要項目。 您想要用的標頭類型。支援的值：
|
| 如果 包含本影片的多媒體物件。 |
區塊物件
| 名稱 | 說明 |
|---|---|
| 多個產品訊息時為必要項目。
每個
|
| 清單訊息時為必要項目。 包含橫列清單。各區塊總共可以有 10 個橫列。 每個橫列必須有一個標題（最大長度：24 個字元）和一個編號（最大長度：200 個字元）。您可以新增說明（最大長度：72 個字元），但此為選用項目。 範例： "rows": [
{
"id":"unique-row-identifier-here",
"title": "row-title-content-here",
"description": "row-description-content-here",
}
] |
| 如果訊息有多個區塊，則為必要項目。 區塊的標題。 最大長度：24 個字元。 |
地點物件
| Name | Description |
|---|---|
| Required. Location latitude in decimal degrees. |
| Required. Location longitude in decimal degrees. |
| Required. Name of the location. |
| Required. Address of the location. |
多媒體物件
請參閱取得多媒體編號，瞭解如何取得多媒體物件編號的資訊。如需瞭解雲端 API 支援的多媒體類型，請參閱支援的多媒體類型。
| Name | Description |
|---|---|
| Required when The media object ID. Do not use this field when message |
| Required when The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs. Do not use this field when message Cloud API users only:
|
| Optional. Media asset caption. Do not use with On-Premises API users:
|
| Optional. Describes the filename for the specific document. Use only with The extension of the filename will specify what format the document is displayed as in WhatsApp. |
| Optional. On-Premises API only. This path is optionally used with a |
範本物件
| Name | Description |
|---|---|
| Required. Name of the template. |
| Required. Contains a The
|
| Optional. Array of |
| Optional. Only used for On-Premises API. Namespace of the template. |
以下物件會以巢狀方式包含在 template 物件內：
按鈕參數物件
| 名稱 | 說明（點擊左欄中的箭頭可查看支援的選項。） |
|---|---|
| 必要項目。 指示按鈕的參數類型。 |
|
除了顯示在按鈕上的文字，點擊按鈕時，系統將傳回開發人員所定義的承載。 請參閱快速回覆按鈕點擊次數的回呼以取得範例。 |
| 網址按鈕時為必要項目。 開發人員提供的後綴，其附加至範本中之預先定義的前綴網址。 |
元件物件
| Name | Description (Click the arrow in the left column for supported options.) |
|---|---|
| Required. Describes the Example of a
"components": [{
"type": "body",
"parameters": [{
"type": "text",
"text": "name"
},
{
"type": "text",
"text": "Hi there"
}]
}] |
| Required when Type of button to create. |
| Required when Array of For components of type=button, see the |
| Required when Position index of the button. You can have up to 10 buttons using index values of 0 to 9. |
幣別物件
| 名稱 | 說明 |
|---|---|
| 必要項目。 本地化失敗時的預設文字。 |
| 必要項目。
|
| 必要項目。 乘以 1,000 的金額。 |
Date_Time 物件
| 名稱 | 說明 |
|---|---|
| 必要項目。 預設文字。針對雲端 API，我們一律使用遞補值，且不會嘗試使用其他選用欄位進行本地化。 |
參數物件
| 名稱 | 說明 |
|---|---|
| 必要項目。 說明參數類型。支援的值：
若是文字型範本，唯一支援的參數類型為 |
|
訊息的文字。字元限制因以下包含的元件類型而異。 若是
若是
|
|
|
|
|
|
|
|
|
|
|
文字物件
| 名稱 | 說明 |
|---|---|
| 文字訊息時為必要項目。 文字訊息的文字，可包含以 http:// 或 https:// 開頭的網址和格式。請前往這裡查看可用的格式選項。 如果您在文字中包含網址，且想要在文字訊息中包含預覽方塊（ 最大長度：4096 個字元 |
| 選用項目。僅適用於雲端 API。 設定為 如果省略 內部部署 API 用戶請改用最上層訊息承載中的 |
心情物件
| 名稱 | 說明 |
|---|---|
| 必要項目。 應顯示心情之訊息的 WhatsApp 訊息編號（wamid）。如果出現以下狀況，系統將不會傳送心情回應：
如果編號是已刪除訊息的編號，系統將不會傳遞該訊息。 |
| 必要項目。 出現在訊息中的表情符號。
|
總覽
範例
文字訊息
curl -X POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE_NUMBER",
"type": "text",
"text": { // the text object
"preview_url": false,
"body": "MESSAGE_CONTENT"
}
}'
心情訊息
curl -X POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE_NUMBER",
"type": "reaction",
"reaction": {
"message_id": "wamid.HBgLM...",
"emoji": "\uD83D\uDE00"
}
}'
多媒體訊息
curl -X POST \
'https://graph.facebook.com/v19.0/FROM-PHONE-NUMBER-ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE-NUMBER",
"type": "image",
"image": {
"id" : "MEDIA-OBJECT-ID"
}
}'
地點訊息
curl -X POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"to": "PHONE_NUMBER",
"type": "location",
"location": {
"longitude": LONG_NUMBER,
"latitude": LAT_NUMBER,
"name": LOCATION_NAME,
"address": LOCATION_ADDRESS
}
}'
聯絡人訊息
curl -X POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"to": "PHONE_NUMBER",
"type": "contacts",
"contacts": [{
"addresses": [{
"street": "STREET",
"city": "CITY",
"state": "STATE",
"zip": "ZIP",
"country": "COUNTRY",
"country_code": "COUNTRY_CODE",
"type": "HOME"
},
{
"street": "STREET",
"city": "CITY",
"state": "STATE",
"zip": "ZIP",
"country": "COUNTRY",
"country_code": "COUNTRY_CODE",
"type": "WORK"
}],
"birthday": "YEAR_MONTH_DAY",
"emails": [{
"email": "EMAIL",
"type": "WORK"
},
{
"email": "EMAIL",
"type": "HOME"
}],
"name": {
"formatted_name": "NAME",
"first_name": "FIRST_NAME",
"last_name": "LAST_NAME",
"middle_name": "MIDDLE_NAME",
"suffix": "SUFFIX",
"prefix": "PREFIX"
},
"org": {
"company": "COMPANY",
"department": "DEPARTMENT",
"title": "TITLE"
},
"phones": [{
"phone": "PHONE_NUMBER",
"type": "HOME"
},
{
"phone": "PHONE_NUMBER",
"type": "WORK",
"wa_id": "PHONE_OR_WA_ID"
}],
"urls": [{
"url": "URL",
"type": "WORK"
},
{
"url": "URL",
"type": "HOME"
}]
}]
}'
互動式訊息
單一產品訊息
curl -X POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE_NUMBER",
"type": "interactive",
"interactive": {
"type": "product",
"body": {
"text": "optional body text"
},
"footer": {
"text": "optional footer text"
},
"action": {
"catalog_id": "CATALOG_ID",
"product_retailer_id": "ID_TEST_ITEM_1"
}
}
}'
多個產品訊息
curl -X POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE_NUMBER",
"type": "interactive",
"interactive": {
"type": "product_list",
"header":{
"type": "text",
"text": "header-content"
},
"body": {
"text": "body-content"
},
"footer": {
"text": "footer-content"
},
"action": {
"catalog_id": "CATALOG_ID",
"sections": [
{
"title": "section-title",
"product_items": [
{ "product_retailer_id": "product-SKU-in-catalog" },
{ "product_retailer_id": "product-SKU-in-catalog" },
...
]
},
{
"title": "section-title",
"product_items": [
{ "product_retailer_id": "product-SKU-in-catalog" },
{ "product_retailer_id": "product-SKU-in-catalog" },
...
]
}
]
}
}
}
目錄訊息
curl -X POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE_NUMBER",
"type": "interactive",
"interactive" : {
"type" : "catalog_message",
"body" : {
"text": "Thanks for your order! Tell us what address you’d like this order delivered to."
},
"action": {
"name": "catalog_message",
"parameters": {
"thumbnail_product_retailer_id": "<Product-retailer-id>"
}
}
}
}'
流程訊息
curl -X POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE_NUMBER",
"type": "interactive",
"interactive" : {
"type": "flow",
"header": {
"type": "text",
"text": "Flow message header"
},
"body": {
"text": "Flow message body"
},
"footer": {
"text": "Flow message footer"
},
"action": {
"name": "flow",
"parameters": {
"flow_message_version": "3",
"flow_token": "AQAAAAACS5FpgQ_cAAAAAD0QI3s",
"flow_id": "<FLOW_ID>",
"flow_cta": "Book!",
"flow_action": "navigate",
"flow_action_payload": {
"screen": "<SCREEN_ID>",
"data": {
"user_name": "name",
"user_age": 25
}
}
}
}
}
}'
清單訊息
curl -X POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE_NUMBER",
"type": "interactive",
"interactive": {
"type": "list",
"header": {
"type": "text",
"text": "HEADER_TEXT"
},
"body": {
"text": "BODY_TEXT"
},
"footer": {
"text": "FOOTER_TEXT"
},
"action": {
"button": "BUTTON_TEXT",
"sections": [
{
"title": "SECTION_1_TITLE",
"rows": [
{
"id": "SECTION_1_ROW_1_ID",
"title": "SECTION_1_ROW_1_TITLE",
"description": "SECTION_1_ROW_1_DESCRIPTION"
},
{
"id": "SECTION_1_ROW_2_ID",
"title": "SECTION_1_ROW_2_TITLE",
"description": "SECTION_1_ROW_2_DESCRIPTION"
}
]
},
{
"title": "SECTION_2_TITLE",
"rows": [
{
"id": "SECTION_2_ROW_1_ID",
"title": "SECTION_2_ROW_1_TITLE",
"description": "SECTION_2_ROW_1_DESCRIPTION"
},
{
"id": "SECTION_2_ROW_2_ID",
"title": "SECTION_2_ROW_2_TITLE",
"description": "SECTION_2_ROW_2_DESCRIPTION"
}
]
}
]
}
}
}'
回覆按鈕
curl -X POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE_NUMBER",
"type": "interactive",
"interactive": {
"type": "button",
"body": {
"text": "BUTTON_TEXT"
},
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"id": "UNIQUE_BUTTON_ID_1",
"title": "BUTTON_TITLE_1"
}
},
{
"type": "reply",
"reply": {
"id": "UNIQUE_BUTTON_ID_2",
"title": "BUTTON_TITLE_2"
}
}
]
}
}
}'
範本訊息
curl -X POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE_NUMBER",
"type": "template",
"template": {
"name": "TEMPLATE_NAME",
"language": {
"code": "LANGUAGE_AND_LOCALE_CODE"
},
"components": [
{
"type": "header",
"parameters": [
{
"type": "image",
"image": {
"link": "http(s)://URL"
}
}
]
},
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "TEXT_STRING"
},
{
"type": "currency",
"currency": {
"fallback_value": "VALUE",
"code": "USD",
"amount_1000": NUMBER
}
},
{
"type": "date_time",
"date_time": {
"fallback_value": "MONTH DAY, YEAR"
}
}
]
},
{
"type": "button",
"sub_type": "quick_reply",
"index": "0",
"parameters": [
{
"type": "payload",
"payload": "PAYLOAD"
}
]
},
{
"type": "button",
"sub_type": "quick_reply",
"index": "1",
"parameters": [
{
"type": "payload",
"payload": "PAYLOAD"
}
]
}
]
}
}'
回覆訊息
curl -X POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"context": {
"message_id": "MESSAGE_ID"
},
"to": "PHONE_NUMBER",
"type": "text",
"text": {
"preview_url": false,
"body": "your-text-message-content"
}
}’
成功回覆
{
"messaging_product": "whatsapp",
"contacts": [
{
"input": "16505555555",
"wa_id": "16505555555"
}
],
"messages": [
{
"id": "wamid.HBgLMTY1MDUwNzY1MjAVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA"
}
]
}
Applies to businesses in Brazil, Colombia, and Singapore, starting September 12, 2023. Applies to all businesses starting October 12, 2023.
Messages will have one of the following statuses which will be returned in each of the messages objects
"message_status":"accepted": means the message was sent to the intended recipient"message_status":"held_for_quality_assessment": means the message send was delayed until quality can be validated and it will either be sent or dropped at this point
{
"messaging_product": "whatsapp",
"contacts": [
{
"input": "16505555555",
"wa_id": "16505555555"
}
],
"messages": [
{
"id": "wamid.HBgLMTY1MDUwNzY1MjAVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA",
"message_status": "accepted",
}
]
}