雲端 API

對話元件

對話元件是您可以為商家電話號碼啟用的聊天功能，可讓 WhatsApp 用戶更輕鬆地與您的商家互動。您可以配置易於使用的指令、提供預先編寫的破冰對話供用戶點擊，以及顯示歡迎訊息來問候第一次使用的用戶。

限制

如果 WhatsApp 用戶點擊已配置預先填妥文字的通用連結（即 wa.me 連結），系統會自動關閉破冰對話的用戶介面。

經由 WhatsApp 管理工具（WAM）配置

您可以前往 WhatsApp 管理工具，在選擇的特定號碼中配置所有這些功能：

  1. 導覽至 Meta for Developers 網站中的「我的應用程式」主控板。
  2. 選擇您的應用程式，然後在左側面板中，選擇 WhatsApp 下方的配置。
  3. 在電話號碼下方，選擇管理電話號碼。
  4. 在要配置之電話號碼的最右側，選擇設定下方的齒輪圖示。
  5. 選擇自動化。
  6. 存取和配置對話元件。

如果解決方案合作夥伴有權限在 WhatsApp 管理工具中存取顧客的 WhatsApp Business 帳號，則也可以為顧客配置這些功能。

歡迎訊息

每當 WhatsApp 用戶第一次與您開啟對話時，您都會收到 Webhook 通知。如果您想使用自己設計的特殊歡迎訊息回覆這些用戶，此方式將非常有用。

歡迎訊息非常適用於服務互動，例如客戶支援或帳號服務。例如，您可以在應用程式或網站中內嵌 WhatsApp 按鈕。當用戶點擊按鈕時，系統會將其重新導向至 WhatsApp，用戶會在此收到歡迎訊息，內容提供如何與您互動的資訊。

如果您啟用此功能，而用戶傳送訊息給您，WhatsApp 用戶端會檢查用戶與商家電話號碼之間是否有現存的訊息對話串。如果沒有，用戶端會觸發 messages Webhook，並將 type 設為 request_welcome，您就可以用自己的歡迎訊息來回覆用戶。

request_welcome 會觸發顧客服務視窗，該視窗允許您的商家在回覆顧客時傳送任意格式的訊息。

Webhook 承載

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<WHATSAPP_USER_NAME>"
                },
                "wa_id": "<WHATSAPP_USER_ID>"
              }
            ],
            "messages": [
              {
                "from": "<WHATSAPP_USER_PHONE_NUMBER>",
                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<TIMESTAMP>",
                "type": "request_welcome"  // Indicates first time message from WhatsApp user
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

破冰對話

破冰對話是您第一次與用戶聊天時顯示在訊息對話串中，可自訂、可點擊的字串。例如，「規劃旅行」或「建立健身計畫」。

破冰對話非常適用於服務互動，例如客戶支援或帳號服務。例如，您可以在應用程式或網站中內嵌 WhatsApp 按鈕。當用戶點擊按鈕時，系統會將其重新導向至 WhatsApp，用戶可以在此選擇一系列可自訂的提示，內容顯示如何與您服務互動的資訊。

一個商家電話號碼最多可以配置 4 則破冰對話。每則破冰對話最多可以有 80 個字元。不支援表情符號。

當用戶點擊破冰對話時，會觸發標準的收到訊息 Webhook，並將破冰對話字串指派至承載中的 body 屬性。如果用戶嘗試傳送訊息給您，而不是點擊破冰對話，則會顯示鍵盤迷你窗，但可以將其關閉，就會再顯示破冰對話選單。

如果 WhatsApp 用戶點擊已配置預先填妥文字的通用連結（即 wa.me 或 api.whatsapp.com 連結），系統會自動關閉破冰對話的用戶介面。

Webhook 承載

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<WHATSAPP_USER_NAME>"
                },
                "wa_id": "<WHATSAPP_USER_ID>"
              }
            ],
            "messages": [
              {
                "from": "<WHATSAPP_USER_PHONE_NUMBER>",
                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<TIMESTAMP>",
                "text": {
                  "body": "Plan a trip"
                },
                "type": "text"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

指令

指令是一種字串，WhatsApp 用戶在與商家的訊息對話串中輸入正斜線時，就會顯示這些字串。

指令是由指令本身和提示所組成，可讓用戶知道使用指令時會發生什麼事情。例如，您可以定義指令：

/imagine - Create images using a text prompt

當 WhatsApp 用戶輸入 /imagine cars racing on Mars 時，會觸發收到訊息 Webhook，並且將該確切的字串指派至 body 屬性。然後，您就可以產生並傳回在火星上賽車的圖像。

您最多可以定義 30 個指令。每個指令最多有 32 個字元，而每個提示最多有 256 個字元。不支援表情符號。

Webhook 承載

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<WHATSAPP_USER_NAME>"
                },
                "wa_id": "<WHATSAPP_USER_ID>"
              }
            ],
            "messages": [
              {
                "from": "<WHATSAPP_USER_PHONE_NUMBER>",
                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<TIMESTAMP>",
                "text": {
                  "body": "/imagine cars racing on Mars"
                },
                "type": "text"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

經由 API 配置

透過使用 API，您也可以配置對話元件並查看任何配置的值。

對話元件 API 有兩個端點：

POST </PHONE_NUMBER_ID>/conversational_automation 用於在指定電話號碼上配置對話元件。

GET /<PHONE_NUMBER_ID>/conversational_automation 可傳回指定電話號碼上的 enable_welcome_message、指令和提示欄位的現有值。

經由 API 配置對話元件

您可以透過呼叫 POST 端點，在指定電話號碼上配置對話元件。

要求語法

// Enable or disable the Welcome Message for the given phone number ID
POST /<PHONE_NUMBER_ID>/conversational_automation?enable_welcome_message=<ENABLE_DISABLE>

// Configure Commands with names and descriptions
POST /<PHONE_NUMBER_ID>/conversational_automation?commands=<COMMAND_LIST>

// Configure Prompts
POST /<PHONE_NUMBER_ID>/conversational_automation?prompts=<PROMPT>

內文屬性


預留位置說明範例值

<PHONE_NUMBER_ID>

整數

必要項目。


WhatsApp Business 帳號上的電話號碼編號。

+12784358810

<ENABLE_DISABLE>

布林值

選用項目。


用於在電話號碼上啟用或停用歡迎訊息的布林值。


true

<COMMAND_LIST>

JSON

選用項目。


要配置的指令清單。


"commands": {
     "command_name": "generate"
     "command_description": "Create a new image",
     “command_name”: “rethink”
     “command_description”: “Generate new images from existing images”,
}

<PROMPTS>

字串清單

選用項目。


要配置的提示。


"prompts": ["Book a flight","plan a vacation"]

要求範例

   curl -X POST \
 'https://graph.facebook.com/v19.0/PHONE_NUMBER_ID/conversational_automation' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
   "enable_welcome_message": true/false,
   "commands": [
     {
       "command_name": "tickets",
       "command_description": "Book flight tickets",
     },
     {
       "command_name": "hotel",
       "command_description": "Book hotel",
     }
   ],
 "prompts": ["Book a flight","plan a vacation"]
}'

回應範例

{
  "success": true
}

經由 API 查看現有配置

您可以透過呼叫 GET 端點，查看指定電話號碼上的現有對話元件配置。

要求語法

GET  /<PHONE_NUMBER_ID>?fields=conversational_automation

回應範例

{
  "conversational_automation": {
    "enable_welcome_message": true
    "prompts": [
      "Find the best hotels in the area",
      "Find deals on rental cars"
    ],
    "commands": [
      {
        "command_name": "tickets",
        "command_description": "Book flight tickets",
      },
      {
        "command_name": "hotel",
        "command_description": "Book hotel",
      }
    ],
  }
  "id": "123456"
}

測試

若要在配置完成後即測試對話元件，請開啟 WhatsApp 用戶端，並使用商家電話號碼開啟對話。

針對歡迎訊息和破冰對話，如果已經有與商家電話號碼進行中的對話串，則必須先清除對話串：

  1. 在 WhatsApp 用戶端開啟對話串。
  2. 點擊商家電話號碼的個人檔案
  3. 點擊清除對話 > 清除所有訊息。
  4. 清除對話。
  5. 與此商家開始新的對話串。

接著，您可以傳送訊息到商家電話號碼，如此應該會觸發 request_welcome Webhook。