中文(香港) 的翻譯尚未完成。
訊息
使用 /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 來追蹤訊息狀態。您亦可以透過訊息端點，將收到的訊息標記為已讀。此 WAMID 的長度上限可達 128 個字元。
message 物件
若要傳送訊息，您必須首先以您要傳送的內容組裝 message 物件。以下是用於 message 物件的參數：
| 名稱 | 說明（點擊左欄的箭咀以了解支援選項。） |
|---|---|
|
包含音訊的 |
| 此為選用項目。 任何字串，有助追蹤。 舉例來說，您可以在此欄位輸入訊息範本編號，以從您傳送的第一則訊息開始追蹤顧客體驗歷程。然後，您可以追蹤不同訊息範本類型的投資回報率，以找出哪個類型最有效。 此字串包含在 Webhook 裝載的 雲端 API 不會處理此欄位，只會將其作為已傳送／已送達／已讀訊息 Webhooks 的一部分傳回。 最多 512 個字元。 |
|
|
| 回覆對話中任何訊息時，此為必要項目。 此物件包含您所回覆的之前訊息其編號。例如：
|
|
包含文件的 |
| 包含 僅限內部部署 API。 |
|
包含圖像的 |
|
|
|
|
| 此為必要項目 要求所用的訊息往來服務。使用 |
|
允許在文字訊息中顯示網址預覽。請參閱在文字訊息中傳送網址。如不在訊息中加入網址，此為可選欄位。值： |
| 此為選用項目。 您目前僅可向個人用戶傳送訊息。請將此設定為 預設： |
| 訊息狀態。您可使用此欄位將訊息標記為 |
|
包含貼圖的 雲端 API：除了所有傳入訊息的貼圖類型外，亦支援傳出訊息的第三方靜態和動態貼圖。靜態貼圖須為 512x512 像素，不得超過 100 KB。動態貼圖須為 512x512 像素，不得超過 500 KB。 內部部署 API：除了所有傳入訊息的貼圖類型外，僅支援傳出訊息的第三方靜態貼圖。靜態貼圖須為 512x512 像素，不得超過 100 KB。不支援動態貼圖。 |
|
|
| 此為文字訊息的必要項目。 |
| 此為必要項目。 作為訊息傳送對象的顧客之 WhatsApp 編號或手機號碼。請參閱手機號碼格式。 如有需要，內部部署 API 用戶可呼叫 |
| 此為選用項目。 要傳送的訊息類型。如略過，則預設為 |
以下物件已嵌套至 message 物件：
contacts 物件
| 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 物件
| 名稱 | 說明 |
|---|---|
| 此為必要項目。 您想用戶在閱讀訊息後執行的動作。 |
|
含有訊息內文的物件。
|
| 此為選用項目。含有訊息頁尾的物件。
|
|
在訊息頂部顯示的標題內容。如果您的 interactive 物件為 |
| 此為必要項目。 要傳送的互動式訊息類型。支援的值：
|
以下物件已嵌套至 interactive 物件：
action 物件
| 名稱 | 說明 |
|---|---|
| 清單訊息的必要項目。 按鈕內容。不能是空白字串，且在訊息中不得重複。支援表情符號，不支援 Markdown。 長度上限：20 個字元。 |
| 「回覆」按鈕的必要項目。 按鈕物件可包含以下參數：
最多可有 3 個按鈕。設定編號時，頭尾不可留有空格。 |
| 單一商品訊息和多商品訊息的必要項目。 與 WhatsApp Business 帳戶連結的 Facebook 目錄之不重複識別資料。此編號可經由 Meta 商務管理工具檢索。 |
| 單一商品訊息和多商品訊息的必要項目。 目錄中產品的不重複識別資料。 若要取得此編號，請前往 Meta 商務管理工具並選擇您的 Meta 商業帳戶。您會看到連結至您帳戶的商店清單。點擊您想使用的商店。在左側面板上，點擊目錄 > 商品，然後找出您想提及的商品。商品的編號會顯示在商品名稱下方。 |
| 清單訊息和多商品訊息的必要項目。
|
| 流程訊息的選用項目。 流程的現有模式，可為 預設： |
| 流程訊息的必要項目。 必須為 |
| 流程訊息的必要項目。 由商家產生的憑證，用作識別碼。 |
| 流程訊息的必要項目。 由 WhatsApp 提供的流程不重複識別資料。 |
| 流程訊息的必要項目。 CTA 按鈕上的文字，例如「註冊」。 長度上限：20 個字元（不含表情符號）。 |
| 流程訊息的選用項目。
預設： |
| 流程訊息的選用項目。 只有當
|
header 物件
| 名稱 | 說明 |
|---|---|
| 如果 含有這個文件的 media 物件。 |
| 如果 含有這張圖片的 media 物件。 |
| 如果 標題文字。格式接受表情符號，但不接受 Markdown。 長度上限：60 個字元。 |
| 此為必要項目。 您想使用的標題類型。支援的值：
|
| 如果 含有這段影片的 media 物件。 |
section 物件
| 名稱 | 說明 |
|---|---|
| 多商品訊息的必要項目。
每個
|
| 清單訊息的必要項目。 含有多行清單。您可在所有區塊合共有 10 行。 每行都必須有標題（長度上限：24 個字元）和編號（長度上限：200 個字元）。您可選擇加入說明（長度上限：72 個字元）。 範例： "rows": [
{
"id":"unique-row-identifier-here",
"title": "row-title-content-here",
"description": "row-description-content-here",
}
] |
| 如果訊息有多於一個區塊，此為必要項目。 區塊標題。 長度上限：24 個字元。 |
location 物件
| Name | Description |
|---|---|
| Required. Location latitude in decimal degrees. |
| Required. Location longitude in decimal degrees. |
| Required. Name of the location. |
| Required. Address of the location. |
media 物件
若要了解如何取得 media 物件的編號，請查看取得 media 編號。若要了解雲端 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 |
template 物件
| 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 物件：
button parameter 物件
| 名稱 | 說明（點擊左欄的箭咀以了解支援選項。） |
|---|---|
| 此為必要項目。 指明按鈕的參數類型。 |
|
用戶點擊按鈕後，系統除了按鈕上顯示的文字以外，所傳回的開發人員定義裝載。 請參閱點擊快速回覆按鈕所觸發的回呼，了解相關範例。 |
| 「網址」按鈕的必要項目。 由開發人員提供的尾碼，附加於範本中預先定義的前綴網址。 |
components 物件
| 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. |
currency 物件
| 名稱 | 說明 |
|---|---|
| 此為必要項目。 本地化失敗時所顯示的預設文字。 |
| 此為必要項目。
|
| 此為必要項目。 貨幣金額，以 1,000 作為倍數。 |
date_time 物件
| 名稱 | 說明 |
|---|---|
| 此為必要項目。 預設文字。在雲端 API 中，我們一律使用遞補值，而不會嘗試以其他選用欄位作本地化。 |
parameter 物件
| 名稱 | 說明 |
|---|---|
| 此為必要項目。 說明參數類型。支援的值：
文字型範本支援的參數類型僅限 |
|
訊息的文字。字元上限取決於以下包含的元件類型。
|
|
|
|
|
|
|
|
|
|
|
text 物件
| 名稱 | 說明 |
|---|---|
| 文字訊息的必要項目。 文字訊息的文字，可包含以 http:// 或 https:// 開頭的網址和格式。在此查看適用的格式選項。 如您在文字中包含網址，並想在文字訊息中包含預覽框（ 長度上限：4096 個字元 |
| 此為選用項目。僅適用於雲端 API。 設為 如省略 內部部署 API 用戶可在最高級別訊息裝載改為使用 |
reaction 物件
| 名稱 | 說明 |
|---|---|
| 此為必要項目。 應要顯示心情回應的訊息之 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",
}
]
}