範本訊息

WhatsApp 訊息範本是特定的訊息格式，可供商家用來向選擇接收通知的用戶傳送通知或顧客服務訊息。訊息內容可包括預約提醒、送貨資訊、問題解決辦法或付款更新資訊。

如要傳送範本訊息，您需要先建立範本。詳情請參閱「為您的 WhatsApp Business 帳戶建立訊息範本」一文。如果您的帳戶尚未通過驗證，您可以使用我們預先批准的範本。

目前，您可以傳送以下類型的範本：

本指南提及的所有 API 呼叫都必須以存取憑證驗證。開發人員可以使用在應用程式管理中心 > WhatsApp > API 設定面板中產生的存取憑證，來驗證其 API 呼叫。解決方案合作夥伴必須以具有 whatsapp_business_messaging 權限的存取憑證進行自我驗證。

調節程序

新建立的範本或恢復使用的營銷範本都須經過調節程序。請參閱範本調節。

文字訊息範本

如要傳送文字訊息範本，請對 /PHONE_NUMBER_ID/messages 發出 POST 呼叫，並附加包含 type=template 的 message 物件。然後，加入 template 物件。

要求範例：

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": "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": "DATE"
            }
          }
        ]
      }
    ]
  }
}'

成功的回應會傳回以 wamid 為識別資料前綴的物件。您可使用列於 wamid 之後的編號追蹤訊息狀態。

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.ID",
    }]
}

媒體訊息範本

如要傳送媒體訊息範本，請對 /PHONE_NUMBER_ID/messages 發出 POST 呼叫，並附加包含 type=template 的 message 物件。然後，加入 template 物件。支援媒體 HTTP 快取。

使用 POST WhatsApp Business 手機號碼 > 訊息端點，傳送媒體型範本訊息。將 type 屬性設為 template，然後使用 template 屬性定義範本物件及其媒體物件。

定義媒體物件時，您可以向我們的伺服器上載媒體資產，然後使用資產的媒體編號（使用 id 屬性）；或者在您的伺服器上託管資產，然後使用資產的網址（使用 link 屬性）。如果使用 link，資產必須位於可公開存取的伺服器上，否則訊息無法傳送。

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

媒體資產亦可快取。查閱媒體 HTTP 快取。

要求範例：

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": "https://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"
            }
          }
        ]
      }
    ]
  }
}'

成功的回應會傳回以 wamid 為識別資料前綴的物件。您可使用列於 wamid 之後的編號追蹤訊息狀態。

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.ID",
    }]
}

互動式訊息範本

互動式訊息範本在標準訊息範本和媒體訊息範本類型的基礎上，增加了允許向傳送對象傳送的內容，其中包括使用元件物件的互動式按鈕。預先定義的按鈕有兩種：

呼籲字句：您的顧客可藉此撥打電話和瀏覽網站。
快速回覆：您的顧客可藉此回覆簡單的文字訊息。

此類按鈕可附加至文字訊息或媒體訊息。您建立的互動式訊息範本獲得批准後，即可在通知訊息和顧客服務訊息中使用。

如要傳送互動式訊息範本，請對 /PHONE_NUMBER_ID/messages 發出 POST 呼叫，並附加包含 type=template 的 message 物件。然後，新增一個包含所選 button 的 template 物件。

要求範例：

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"
          }
        ]
      }
    ]
  }
}'

成功的回應會傳回以 wamid 為識別資料前綴的物件。您可使用列於 wamid 之後的編號追蹤訊息狀態。

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.ID",
    }]
}

位置訊息範本

如要傳送使用位置標題的範本，您的要求必須包含位置標題物件。

語法

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

屬性

預留位置	說明	值範例
`<ADDRESS>`	在 `<NAME>` 值後顯示的地址，位於訊息頂部的一般地圖下方。	`1 Hacker Way, Menlo Park, CA 94025`
`<LATITUDE>`	位置的緯度。	`37.483307`
`<LONGITUDE>`	位置的經度。	`122.148981`
`<NAME>`	這種文字將會立即出現在訊息頂部的一般地圖下方。	`Pablo Morales`

要求範例

此要求範例可以傳送使用以下元素的現有範本：

1 個位置標題
1 個包含變數的內文
1 個頁尾
1 個快速回覆按鈕

curl -L 'https://graph.facebook.com/v16.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "12245554792",
  "type": "template",
  "template": {
    "name": "order_delivery_update",
    "language": {
      "code": "en_US"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "location",
            "location": {
              "latitude": "37.483307",
              "longitude": "122.148981",
              "name": "Pablo Morales",
              "address": "1 Hacker Way, Menlo Park, CA 94025"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Pablo"
          },
          {
            "type": "text",
            "text": "566701"
          }
        ]
      }
    ]
  }
}'

驗證類別範本

如果變數值超過 15 個字元、包含連結或表情符號，或者範本正文元件包含連結，此時嘗試傳送舊驗證類別範本（未設有單次密碼按鈕的範本）將會傳回錯誤代碼 100。請改為建立和使用設有單次密碼按鈕的驗證類別範本。

請參閱驗證類別範本和傳送驗證類別範本。

多則訊息的送達順序

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

每位用戶的營銷範本訊息限制

由 2024 年 2 月 6 日起，每位用戶的營銷範本訊息限制會適用於向小部分印度 WhatsApp 用戶傳送的範本訊息，而由 2024 年 2 月 13 日起，此措施將適用於所有使用印度手機號碼的 WhatsApp 用戶。

我們正在推出新措施，旨在建立高質素的用戶體驗並發揮營銷範本訊息互動的最大效益，其中先由印度消費者開始，當中可能包括限制用戶在特定時間內從任何企業接收到的營銷範本訊息數量，首先針對一小部分較不可能看到的對話。請注意，相關限制是根據用戶已從任何企業接收到的營銷範本訊息數量而定，與您的企業並無特定關係。

此限制僅適用於在一般情況下會開啟新營銷對話的營銷範本訊息。如果您和 WhatsApp 用戶之間有已開啟的營銷對話，向用戶傳送的營銷範本訊息將不會受到影響。

如果營銷範本訊息因為相關限制而未能送達至特定用戶，雲端 API 會傳回錯誤代碼 131026，而內部部署 API 會傳回錯誤代碼 1026。請注意，雖然這些錯誤代碼涵蓋許多可能會導致訊息未能送達的問題，但出於私隱原因，我們不會披露訊息實際上是否因相關限制而未能送達。請參考雲端 API 的疑難排解文件和內部部署 API 的「為什麼我的送達率不是 100%？」常見問題，以了解訊息未送達的原因說明，以及您就判斷根本原因可採取的操作。

如果您確實收到以上其中一個錯誤代碼，並懷疑錯誤是由相關限制所致，請避免即時再次傳送範本訊息，因為這樣做只會導致傳回另一個錯誤回應。限制可能會在不同時段生效，因此您可拉長重試時間的間隔，直至訊息送達為止。

我們會繼續完善措施，同時亦感謝您與我們合作，致力為您的企業和顧客打造最佳的 WhatsApp 體驗。

解決疑難

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

WhatsApp Business 平台 | 雲端 API | 企業管理 API