傳送訊息

本文件介紹如何使用 API 向 WhatsApp 用戶傳送訊息。

訊息類型

您可以使用 API 傳送下列類型的訊息。除心情回應訊息以外，其他所有訊息類型均可作為對之前訊息的回覆來傳送。

地址訊息讓您輕鬆地向 WhatsApp 用戶要求送貨地址。
語音訊息顯示一個語音圖示和一個語音檔案連結。如果 WhatsApp 用戶點按該圖示，WhatsApp 用戶端就會載入並播放該語音檔案。
聯絡人訊息讓您向 WhatsApp 用戶直接傳送豐富的聯絡資料，例如姓名、電話號碼、實體地址和電郵地址。
文件訊息顯示一個文件圖示，該圖示連結至一個文件，WhatsApp 用戶點按圖示即可下載該文件。
圖片訊息顯示一張圖片和可選說明文字。
互動式 CTA 網址按鈕訊息讓您可以將任何網址對照到按鈕，這樣就不需要在訊息內文中包含冗長或令人費解的原始網址。
互動式 Flow 訊息讓您可以向顧客傳送更自然舒適的結構化訊息。例如，您可以使用 WhatsApp Flows 進行預約、瀏覽商品、收集顧客意見、開發新的銷售潛在顧客等執行其他操作。
互動式清單訊息讓您可以向 WhatsApp 用戶展示可供選擇的選項清單。
互動式位置要求訊息顯示正文和一個傳送位置按鈕。如果 WhatsApp 用戶點按此按鈕，系統便會顯示一個位置分享畫面，用戶可用來分享自己的位置。
互動式回覆按鈕訊息讓您可以傳送最多三個可供用戶選擇的預先定義回覆。
位置訊息讓您可以將位置的經緯坐標傳送給 WhatsApp 用戶。
貼圖訊息在 WhatsApp 訊息中顯示動畫或���態貼圖。
文字訊息是僅含文字內容和可選連結預覽的訊息。
範本訊息讓您可以向 WhatsApp 用戶傳送營銷、工具和驗證類別範本。範本訊息與其他所有的訊息類型不同，在傳送訊息前，您和訊息傳送對象之間無需啟動 24 小時顧客服務時段。
影片訊息顯示影片圖像縮圖預覽，當中附有可選說明文字。如果 WhatsApp 用戶點按該預覽，系統就會載入影片並向用戶展示。
心情回應訊息是指您可在先前收到的 WhatsApp 用戶訊息上套用的表情符號回應。

顧客服務時段

當 WhatsApp 用戶向您傳送訊息時，名為「顧客服務時段」的 24 小時計時器便會隨即開始計時或重新計時。

除了範本訊息外，所有其他訊息類型只能在您與用戶之間的顧客服務時段生效時傳送給用戶。

只要用戶選擇接收您的訊息，您便可隨時向用戶傳送範本訊息。

要求

所有傳送訊息要求都使用 POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID/messages 端點：

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages

Post 內文會因應您想傳送的訊息類型而有不同，但裝載會使用以下常見語法：

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<WHATSAPP_USER_PHONE_NUMBER>",
  "type": "<MESSAGE_TYPE>",
  "<MESSAGE_TYPE>": {<MESSAGE_CONTENTS>}
}

Post 內文裝載的 type 屬性值表示要傳送的訊息類型，您必須加入與該類型相符的屬性，以說明訊息內容。

例如，以下是向 WhatsApp 用戶傳送文字訊息的要求。您可以看到 type 已設為 text，其後是說明訊息內容的 text 物件：

curl 'https://graph.facebook.com/v20.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "As requested, here'\''s the link to our latest product: https://www.meta.com/quest/quest-3/"
  }
}'

如果文字訊息成功送達 WhatsApp 用戶，WhatsApp 用戶端中相關訊息會如下顯示：

回應

如果 API 成功接受傳送訊息要求，而且在要求本身未有遇到任何錯誤，便會傳送以下回應：

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "<WHATSAPP_USER_PHONE_NUMBER>",
      "wa_id": "<WHATSAPP_USER_ID>"
    }
  ],
  "messages": [
    {
      "id": "<WHATSAPP_MESSAGE_ID>"
      "message_status": "<PACING_STATUS>"
    }
  ]
}

請注意，此回應僅表示 API 成功接受要求，但不代表訊息成功傳送。訊息傳送狀態是經由訊息 Webhooks 傳達。

只有在傳送使用已調節範本的範本訊息時，message_status 屬性才會包含其中。

Webhooks

已傳送給 WhatsApp 用戶的訊息會觸發訊息 Webhooks，因此請確保您已訂閱此主題，以接收訊息狀態通知。

商務訊息

商務訊息為互動式訊息，可配合商品目錄一同使用。請參閱與顧客分享商品，了解如何使用這類訊息。

回覆次數

您可以傳送任何類型的訊息以回覆之前的訊息。之前的訊息會以引用對話框形式顯示在新訊息的上方。

限制

如果符合以下情況，作為回覆送達的訊息上方不會顯示回顧對話框：

• 之前的訊息已被刪除或移至長期儲存空間（除非您已啟用本機儲存空間，否則訊息通常會在 30 天後移至長期儲存空間）。
• 您以音訊、圖像或影片訊息回覆，且相關 WhatsApp 用戶正在運行 KaiOS。
• 您透過 WhatsApp 用戶端使用「按住即可聊天」訊息回覆，且相關 WhatsApp 用戶正在運行 KaiOS。
• 您以範本訊息回覆。

要求語法

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages

帖子內文

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<WHATSAPP_USER_PHONE_NUMBER>",
  "context": {
    "message_id": "WAMID_TO_REPLY_TO"
  },

  /* Message type and type contents goes here */

}

Post 內文參數

要求範例

傳送文字訊息以回覆之前訊息的範例。

curl 'https://graph.facebook.com/v19.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "context": {
    "message_id": "wamid.HBgLMTY0NjcwNDM1OTUVAgASGBQzQTdCNTg5RjY1MEMyRjlGMjRGNgA="
  },
  "type": "text",
  "text": {
    "body": "You'\''re welcome, Pablo!"
  }
}'

媒體資產

透過訊息傳送的媒體資產必須上載至將傳送訊息的商家電話號碼，或者您必須將資產託管到公開伺服器上並在訊息傳送要求中加入資產網址。

如要降低發生錯誤的可能性，以及避免向您的公開伺服器傳送不必要的要求，建議您上載媒體資產並在傳送訊息時使用其編號。

媒體 HTTP 快取

WhatsApp 雲端 API 支援媒體 HTTP 快取。如果您在自家伺服器上使用指向媒體資產的連結（link），而不是您上載至我們伺服器的資產編號（id），���我們要求資產時，您可以透過在伺服器回應中包含以下標頭，指示我們快取您的資產以供將來的訊息重用。如果未加入任何此類標頭，我們將無法快取您的資產。

Cache-Control: <CACHE_CONTROL>
Last-Modified: <LAST_MODIFIED>
ETag: <ETAG>

Cache-Control

Cache-Control 標頭告知我們資產快取的處理方式。我們支援以下指令：

• max-age=n：表示快取資產的秒數（n）。我們會在後續訊息中重用已快取的資產，直到超過此處指定的時間，之後我們會視乎需要再次要求該資產。範例：Cache-Control: max-age=604800。
• no-cache：表示資產可以快取，但如 Last-Modified 標頭值與上一個回應不同，則應更新資產。需要 Last-Modified 標頭。範例：Cache-Control: no-cache。
• no-store：表示不應快取資產。範例：Cache-Control: no-store。
• private：表示資產已針對傳送對象進行個人化設定，不應快取。

Last-Modified

表示最近一次修改資產的時間。與 Cache-Control: no-cache 結合使用。如果 Last-Modified 值與上一個回應不同，且 Cache-Control: no-cache 已加到該回應，我們會使用回應中的資產更新資產的快取版本。範例：Date: Tue, 22 Feb 2022 22:22:22 GMT。

ETag

ETag 標頭是一個不重複字串，用於識別資產的特定版本。範例：ETag: "33a64df5"。除非回應中沒有包含 Cache-Control 和 Last-Modified 標頭，否則系統會略過此標頭。在這種情況下，我們會根據自己的內部邏輯（非公開）快取資產。

帶有標頭的回應範例

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 1024
Date: Tue, 22 Feb 2022 22:22:22 GMT
ETag: "33a64df5"
Cache-Control: max-age=604800

<IMAGE_PAYLOAD>

多則訊息的送達順序

在傳送一系列訊息時，我們無法保證按您 API 要求的順序送達各訊息。如需確保按照順序送達訊息，請先在訊息 Webhook 中確認收到 delivered 狀態，然後才傳送訊息序列中的下一則訊息。

存留時間

如果訊息無法成功傳送至 WhatsApp 用戶，我們會在一段時間內繼續嘗試傳送此訊息。這段時間稱為「存留時間」，或訊息有效期限。如訊息超過存留時間仍無法送達，我們會停止重試並放棄此訊息。

• 除了使用驗證範本的範本訊息外，所有訊息的存留時間均為 30 天。
• 使用驗證範本的範本訊息預設存留時間為 10 分鐘。

您可設定驗證範本和工具範本的自訂存留時間，以自訂這些預設設定。請參閱自訂存留時間。

如果您傳送了訊息，但沒有收到相應的訊息 Webhook 表明相關訊息在超過存留時間前已送達，則可假定系統已放棄該訊息。

請注意，如果訊息因某個無關原因而失敗，並觸發了傳送失敗訊息 Webhook，您可能略有延遲才收到該 Webhook。因此，您可能需要預留一小段緩衝時間，才假定系統已放棄訊息。

疑難排解

如果您在訊息送達方面遇到問題，請參閱訊息未能送達。