無論是哪種訊息類型,您都會透過向 /messages
節點發出 POST
呼叫來傳送訊息。每個訊息類型(文字、影像等)的 JSON 訊息內文各不相同。
以下是用於 /messages
POST 要求的主要參數:
名稱 | 說明(點擊左欄中的箭頭可查看支援的選項。) |
---|---|
|
包含音訊的 |
| 選用項目。 任意字串,適用於追蹤。 例如,您可以在此欄位中傳遞訊息範本編號,以追蹤從您傳送第一則訊息開始的顧客歷程。您後續可以追蹤不同訊息範本類型的 ROI,以決定最有效的訊息範本類型。 任何已訂閱 WhatsApp Business 帳號之 雲端 API 不會處理此欄位,僅將其作為已傳送/已送達/已讀取訊息 Webhooks 的一部分傳回。 最多 512 個字元。 僅適用於雲端 API。 |
|
|
| 如果回覆對話中的任何訊息,則為必要項目。 物件,其中包含您要回覆之上一則訊息的編號。例如:
僅適用於雲端 API。 |
|
包含文件的 |
| 包含 僅適用於內部部署 API。 |
|
包含圖像的 |
|
|
|
|
| 必要項目 用於要求的傳訊服務。使用 僅適用於雲端 API。 |
|
允許在簡訊中預覽網址 - 請參閱在簡訊中傳送網址。如果訊息中不包含網址,此欄位為選用項目。值: |
| 選用項目。 目前只能向個人傳送訊息。請將此值設為 預設值: |
| 訊息的狀態。您可以使用此欄位將訊息標記為 |
|
包含貼圖的 雲端 API:除了支援所有類型的入站貼圖外,亦支援靜態和動畫第三方出站貼圖。靜態貼圖必須為 512x512 像素,且大小不得超過 100 KB。動畫貼圖必須為 512x512 像素,且大小不得超過 500 KB。 內部部署 API:除了支援所有類型的入站貼圖外,僅支援靜態第三方出站貼圖。靜態貼圖必須為 512x512 像素,且大小不得超過 100 KB。不支援動畫貼圖。 |
|
|
| 簡訊的必要項目。 |
| 必要項目。 接收訊息之顧客的 WhatsApp 編號或電話號碼。請參閱電話號碼格式。 如有需要,內部部署 API 用戶可以呼叫 |
| 選用項目。 您想要傳送的訊息類型。如果省略,預設值為 |
名稱 | 說明 |
---|---|
| 必要項目。 包含訊息的文字,可包含網址和加入格式。 |
若使用內部部署 API,當媒體成功透過 media
端點上傳至 WhatsApp Business 內部部署/參考資料用戶端時,系統會傳回媒體物件編號。
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 |
在 contacts
內部,您可以巢狀方式包含下列物件:addresses
、emails
、name
、org
、phone
和 urls
。陣列中會包含複數物件,如以下範例所示。
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
|
內部以巢狀方式包含複數物件的 contacts
物件範例:
"contacts": [ { "addresses": [ { "city": "city name", "country": "country name", "country_code": "code", "state": "Contact's State", "street": "Contact's Street", "type": "Contact's Address Type", "zip": "Contact's Zip Code" } ], "birthday": "birthday", "emails": [ { "email": "email", "type": "HOME" }, { "email": "email", "type": "WORK" } ], "name": { "first_name": "first name value", "formatted_name": "formatted name value", "last_name": "last name value", "suffix": "suffix value" }, "org": { "company": "company name", "department": "dep name", "title": "title" }, "phones": [ { "phone": "Phone number", "wa-id": "WA-ID value", "type": "MAIN" }, { "phone": "Phone number", "type": "HOME" }, { "phone": "Phone number", "type": "WORK" } ], "urls": [{ "url": "some url", "type": "WORK" }] } ]
Name | Description |
---|---|
| Required. Location latitude in decimal degrees. |
| Required. Location longitude in decimal degrees. |
| Required. Name of the location. |
| Required. Address of the location. |
在 template
內,您可以巢狀方式包含 components
和 language
物件。
自 v2.27.8
開始,範本的 namespace
必須是與 WABA 相關聯的命名空間,且該帳號擁有目前 WhatsApp Business 內部部署用戶端的電話號碼,否則訊息將無法傳送。
此外,從 v2.41
及後續版本開始,namespace
將為選填欄位。
名稱 | 說明 |
---|---|
| 必填。 範本的命名空間。 從 |
| 必填。 範本的名稱。 |
| 必填。 指定可在範本中轉譯的語言。只有 |
| 選用。 包含訊息參數的陣列。 |
在 components
內部,您可以巢狀方式包含 parameters
物件。此外,您可以將 type
設為 button
。
名稱 | 說明 |
---|---|
| 必填。 說明 |
| 選用。 包含訊息內容的陣列。 |
在 components
物件內部,您可以將 type
設為 button
。以下為按鈕參數:
名稱 | 說明 |
---|---|
| 必要項目。 所要建立的按鈕類型。 |
| 必要項目。 按鈕的位置索引。最多可以使用 10 個按鈕,索引值為 |
| 必要項目。 按鈕的參數,在企業管理平台中建立按鈕時設定。包含下列參數:
|
使用 quick_reply
sub_type 的 button
類型範例:
{ "type": "button", "sub_type": "quick_reply", "index": 0, "parameters": [{ "type": "payload", "payload": "Yes-Button-Payload" }] }
使用 copy_code
sub_type 的 button
類型範例
{ "type": "button", "sub_type": "copy_code", "index": 0, "parameters": [{ "type": "coupon_code", "coupon_code": "DISCOUNT20" }] }
hsm
物件自 WhatsApp Business 內部部署/參考資料 v2.39
開始已停用。請改用 template
物件。
名稱 | 說明 |
---|---|
| 必要項目。 將使用的命名空間。從 |
| 必要項目。 元素名稱,註明在命名空間中使用的範本。從 |
| 必要項目。 可用於指定決定性語言。如需詳細資訊,請參閱語言一節。 此欄位用於允許 |
| 必要項目。 這個欄位包含值陣列,要套用於範本中的變數。如需詳細資訊,請參閱可本地化的參數一節。 |
The interactive
object generally contains 4 main components: header
, body
, footer
, and action
. Additionally, some of those components can contain one or more different objects:
header
, you can nest media
objects.action
, you can nest section
and button
objects.Name | Description |
---|---|
| Required. The type of interactive message you want to send. Supported values:
|
| Required for type Header content displayed on top of a message. You cannot set a The
|
| Optional for type An object with the body of the message. The
|
| Optional. An object with the footer of the message. The
|
| Required. An |
Name | Description |
---|---|
| Required for List Messages. Button content. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not. Maximum length: 20 characters. |
| Required for Reply Button Messages. A
設定編號時不能有前置或後置空格。 |
| Required for List Messages and Multi-Product Messages. Array of |
| Required for Single-Product Messages and Multi-Product Messages. Unique identifier of the Facebook catalog linked to your WhatsApp Business Account. This ID can be retrieved via Commerce Manager. |
| Required for Single-Product Messages and Multi-Product Messages. Unique identifier of the product in a catalog. Maximum 100 characters for both Single-Product and Multi-Product messages. To get this ID, go to Commerce Manager, select your Facebook Business account, and you will see a list of shops connected to your account. Click the shop you want to use. On the left-side panel, click Catalog > Items, and find the item you want to mention. The ID for that item is displayed under the item's name. |
| Optional for Flows Messages. The current mode of the Flow, either Default: |
| Required for Flows Messages. Must be |
| Required for Flows Messages. A token that is generated by the business to serve as an identifier. |
| Required for Flows Messages. Unique identifier of the Flow provided by WhatsApp. |
| Required for Flows Messages. Text on the CTA button, eg. "Signup". Maximum length: 20 characters (no emoji). |
| Optional for Flows Messages.
Default: |
| Optional for Flows Messages. Required only if
|
Name | Description |
---|---|
| Required if the message has more than one Title of the section. Maximum length: 24 characters. |
| Required for List Messages. Contains a list of row objects. Limited to 10 rows across all sections. Each
|
| Required for Multi-Product Messages. Array of Each
|
音訊訊息:
POST /v1/messages { "recipient_type": "individual", "to": "whatsapp-id", "type": "audio", "audio": { "id": "your-media-id", } }
文件訊息,使用 filename
:
POST /v1/messages { "recipient_type": "individual", "to": "whatsapp-id", "type": "document", "document": { "id": "your-media-id", "filename": "your-document-filename" } }
文件訊息,使用 link
:
POST /v1/messages { "recipient_type": "individual", "to": "whatsapp-id", "type": "document", "document": { "link": "http(s)://the-url" "provider": { "name" : "provider-name" } } }
影片訊息,使用 link
:
POST /v1/messages { "recipient_type": "individual", "to": "whatsapp-id", "type": "video", "video": { "link": "http(s)://the-url" "provider": { "name" : "provider-name" } } } }
文字訊息:
POST /v1/messages { "recipient_type": "individual", "to": "whatsapp-id", "type": "text", "text": { "body": "your-message-content" } }
互動式訊息(清單):
POST /v1/messages { "recipient_type": "individual", "to": "whatsapp-id", "type": "interactive", "interactive":{ "type": "list", "header": { "type": "text", "text": "your-header-content-here" }, "body": { "text": "your-text-message-content-here" }, "footer": { "text": "your-footer-content-here" }, "action": { "button": "cta-button-content-here", "sections":[ { "title":"your-section-title-content-here", "rows": [ { "id":"unique-row-identifier-here", "title": "row-title-content-here", "description": "row-description-content-here", } ] }, { "title":"your-section-title-content-here", "rows": [ { "id":"unique-row-identifier-here", "title": "row-title-content-here", "description": "row-description-content-here", } ] }, ... ] } } }
互動式訊息(回覆按鈕):
POST /v1/messages { "recipient_type": "individual", "to": "whatsapp-id", "type": "interactive", "interactive": { "type": "button", "header": { # optional "type": "text" | "image" | "video" | "document", "text": "your text" # OR "document": { "id": "your-media-id", "filename": "some-file-name" } # OR "document": { "link": "the-provider-name/protocol://the-url", "provider": { "name": "provider-name", }, "filename": "some-file-name" }, # OR "video": { "id": "your-media-id" } # OR "video": { "link": "the-provider-name/protocol://the-url", "provider": { "name": "provider-name" } } # OR "image": { "id": "your-media-id" } # OR "image": { "link": "http(s)://the-url", "provider": { "name": "provider-name" } } }, # end header "body": { "text": "your-text-body-content" }, "footer": { # optional "text": "your-text-footer-content" }, "action": { "buttons": [ { "type": "reply", "reply": { "id": "unique-postback-id", "title": "First Button’s Title" } }, { "type": "reply", "reply": { "id": "unique-postback-id", "title": "Second Button’s Title" } } ] } # end action } # end interactive }
互動式訊息(多個和單一產品訊息):
{ "recipient_type": "individual", "to" : "{{Recipient-WA-ID}}", "type": "interactive", "interactive": { "type": "product", "body": { "text": "body text" }, "footer": { "text": "footer text" }, "action": { " _id": "catalog-ID", "product_retailer_id": "product-ID" } } }
互動式訊息(多個產品訊息):
{ "recipient_type": "individual", "to" : "whatsapp-id", "type": "interactive", "interactive": { "type": "product_list", "Header":{ "type": "text", "text": "text-header-content" }, "body":{ "text": "text-body-content" }, "footer":{ "text":"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": "the-section-title", "product_items": [ { "product_retailer_id": "product-SKU-in-catalog" } ... ]}, ... ] }, } }
互動式訊息(目錄訊息):
{ "recipient_type": "individual", "to" : "whatsapp-id", "type": "interactive", "interactive": { "type": "catalog_message", "body":{ "text": "text-body-content" }, "footer":{ "text":"text-footer-content" }, "action":{ "name": "catalog_message", "parameters":{ "thumbnail_product_retailer_id": "product-SKU-in-catalog" } }, } }
互動式訊息(流程):
{ "recipient_type": "individual", "to": "{{Recipient-WA-ID}}", "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": { # optional "user_name": "name", "user_age": 25 } } } } } }
以下顯示回應中 payload
的範例;為求簡潔,省略了中繼和錯誤物件。
{ "messages": [{ "id": "message-id" }] }
若要求成功,您會收到具有訊息編號的回應。若要求傳回 errors
區段,請檢查來源訊息並更正錯誤之後,再重新傳送要求。如需錯誤的詳細資訊,請參閱 WhatsApp Business API 內部部署/參考資料用戶端錯誤代碼和 HTTP 狀態代碼。
自 2023 年 9 月 12 日起,適用於巴西、哥倫比亞和新加坡的商家。自 2023 年 10 月 12 日起,適用於所有商家。
如果系統保留要求以進行品質評估,則回應將包含 message_status
屬性並附加一則訊息,指示系統未立即傳送訊息,將在驗證品質後傳送或將其刪除。只有當系統保留訊息時,此屬性才會存在。
{ "messages": [{ "id": "message-id", "message_status": "Message has been held because quality assessment is pending", }] }
WhatsApp 允許在訊息中加入一些格式若要對訊息進行全部或部分格式化,請使用以下格式符號:
格式 | 符號 | 範例 |
---|---|---|
粗體 | 星號(*) | 總共是 * 10.50 美元 *。 |
斜體 | 底線(_) | 歡迎使用 _WhatsApp_! |
波狀符號(~) | 這是 ~ 更加 ~ 最棒的! | |
| 三個反引號(```) | ```print 'Hello World';``` |
在本文中,成效代表使用 WhatsApp Business 內部部署/參考資料用戶端在任何指定秒數內可以傳送的訊息數量。可達成的最大成效取決於多種因素,最重要的因素是用戶端設定選擇,以及訊息是傳送給新用戶還是現有用戶。若是傳送訊息給新用戶,加密工作階段設定需要較長的時間。
用戶端設定 | 每秒支援的文字訊息數量 |
---|---|
單一分片 | 70 |
多個分片(32 個分片) | 250 |
注意:請勿使用 WhatsApp Business API 向相同收件人重複傳送相同訊息。
造成投遞率不是 100% 的原因很多。一些常見案例包括用戶偶爾上網、停用一段時間,或者建立 優質用戶體驗。
能夠透過 WhatsApp 傳遞的訊息將具有非常高的投遞率。但是,無法傳遞訊息的原因很多。透過監控回呼,您可以存取訊息的確切狀態。這與使用簡訊傳送訊息有所不同,舉例來說,您無法存取最終傳遞狀態,重新傳送訊息可能在實際上產生不同的結果。
用戶手機暫停服務、沒電,或是遺失且準備購買新機並停用 SIM 卡,都可能造成訊息無法傳遞。企業用戶端的網路連線能力可能發生錯誤,也有可能系統未傳遞回呼(Webhooks)。您可以使用 health
節點監控這些情況。您可以開啟伺服器回條回呼,以瞭解該訊息已進入 WhatsApp 伺服器雲端。
如果用戶重新連線到網路,系統會將您已傳送的所有訊息傳遞給他們。對用戶來說,接收多則相同內容的訊息是一項糟糕的體驗。他們較可能封鎖您或提出抱怨,而您遭到禁用的機率會提高。
如果您傳送訊息並從 API 收到訊息編號,表示已執行可傳送該訊息的作業。請勿將相同內容重新傳送給相同收件人。
如果您在很長一段時間內發現投遞率較低,請透過以下方式提交支援案件: 直接支援。
當您傳送訊息時,一旦傳回訊息編號,即表示訊息要求已儲存在資料庫中。WhatsApp Business API 用戶端將繼續嘗試傳送該訊息,直到 WhatsApp 伺服器確認為止。這項流程沒有結束時間表。接著,WhatsApp 伺服器會嘗試將該訊息傳遞到用戶的手機。如果用戶的手機未在線上,WhatsApp 伺服器會將訊息儲存 30 天後捨棄。
否,訊息抵達的順序不保證與傳送的順序相同。如果順序對您的使用案例至關重要,建議先接聽第一則訊息已傳遞的回呼,然後再觸發第二則訊息。
在某些情況中,您可能需要更多時間來處理顧客查詢,並且只能在 24 小時後回覆。我們建議建立訊息範本來執行下列步驟:
在上述兩種情況中,請務必盡可能為訊息範本提供更多內容。例如: