解決方案合作夥伴新手指南

本指南說明解決方案合作夥伴為了提供雲端 API 給顧客，所需要完成的步驟。主要有 4 個階段：

1. 準備和計畫
2. 設定資產
3. 簽署合約
4. 建立整合

完成之後，請保持每月更新。

準備和計畫

閱讀文件

開始之前，建議您先看過我們的開發人員文件和 Postman 文件集。這有助於您瞭解雲端 API 的運作方式，包括如何開始使用以及移轉電話號碼。

計畫設置和移轉

您必須使用「內嵌註冊」將新顧客設置到雲端 API。如果尚未設置，請整合並啟用內嵌註冊。「內嵌註冊」是註冊顧客最快、最簡單的方式，五分鐘內就能夠讓顧客開始傳送訊息。

接著，請想想您要先將哪些用戶端移轉到雲端 API。一般我們會建議將所有用戶端從內部部署移轉到雲端 API，但每個用戶端的需求可能有所不同。當您思考要移轉哪些用戶端時，請考量：

您只要知道哪個用戶端需要移轉，就可以制訂移轉計畫和時間表。

在您建立計畫時，請記得針對兩種情境設計您的系統：設置新顧客，以及將既有顧客從內部部署移轉到雲端 API。針對移轉情境，請納入備份現有內部部署實例，以及將這些電話號碼移轉到雲端 API 的計畫。

計畫與用戶端通訊

首先，您需要決定是否通知現有用戶端有關移轉的事項。然後，您應該判斷是否需要建立或更新任何文件，以支援雲端 API 設定。

決定價格

由於 Meta 已承擔雲端 API 的託管成本，您應該決定是否要因此更新價格。

設定資產

若要使用雲端 API，解決方案合作夥伴需要擁有下列資產：

簽署合約

接受服務條款

若要使用 WhatsApp Business 訊息雲端 API，您必須先代表商家接受《WhatsApp Business 平台服務條款》。

方法是前往 WhatsApp 管理工具，然後在資訊橫幅中接受服務條款。

如果您是雲端 API 的既有測試版合作夥伴，則有 90 天的寬限期。也就是說，您必須在 2022 年 7 月 5 日前接受條款，否則就會失去使用權限。

如果是初次使用雲端 API的商家（包括從內部部署 API 移轉過來的商家），請務必先接受服務條款，才能開始使用雲端 API。在您接受服務條款之前，都無法接聽註冊通話。

建立整合

步驟 1：取得系統用戶存取權杖

圖形 API 呼叫會使用存取權杖進行驗證。如需詳細資訊，請參閱存取權杖。我們建議您以系統用戶的角色產生權杖。

產生系統用戶存取權杖的方法如下：

1. 前往企業管理平台 > 企業管理平台設定 > 用戶 > 系統用戶，查看您建立的系統用戶。
2. 點擊該用戶，並選擇新增資產。這項操作會啟動新的視窗。
3. 在左側窗格的選擇資產類型下，選擇應用程式。在選擇資產下，選擇您要使用的 Meta 應用程式（您的應用程式必須要有正確的權限）。為該應用程式啟用開發應用程式。
4. 選擇儲存變更以儲存設定，並返回系統用戶主畫面。
5. 現在您可以準備產生權杖。在系統用戶主畫面中，點擊產生權杖，並選擇您的 Meta 應用程式。選擇應用程式後，您會看到可用權限清單。請選擇 whatsapp_business_management 和 whatsapp_business_messaging。點擊產生權杖。
6. 隨即開啟新視窗，其中會顯示系統用戶、指派的應用程式和存取權杖。儲存權杖。
7. 您可以選擇點擊該權杖，然後查看權杖偵錯工具。在偵錯工具中，您應該會看見所選擇的兩項權限。您也可以直接將權杖貼到存取權杖偵錯工具中。

步驟 2：設定 Webhooks

設定 Webhook 後，您就能接收來自 WhatsApp Business 平台的即時 HTTP 通知。舉例來說，如果您收到顧客的訊息，或是 WhatsApp Business 帳號（WABA）有異動，系統就會傳送通知。

若要設定 Webhook，您必須使用符合 Meta 和 WhatsApp 要求的網址來建立連結網際網路的網路伺服器。如需相關操作指示，請參閱建立端點。如果您需要端點以供測試之用，則可產生測試 Webhooks 端點。

應用程式設定

端點準備就緒後，請按照下列步驟完成相關設定，方便 Meta 應用程式使用：

您只需要針對每個應用程式設定 Webhooks 一次即可。您可以使用相同的 Webhook 接收來自多個 WhatsApp Business 帳號的多種事件類型。如需更多資訊，請參閱 Webhooks 一節。

步驟 3：訂閱自己的 WABA

若要確保收到的通知來自正確的帳號，請訂閱自己的應用程式：

curl -X POST \
'https://graph.facebook.com/v19.0/WHATSAPP_BUSINESS_ACCOUNT_ID/subscribed_apps' \
-H 'Authorization: Bearer ACCESS_TOKEN'

如果您收到下列回應，系統就會將屬於這個帳號的電話號碼的所有 Webhook 事件，傳送到設定的 Webhooks 端點。

{
  "success": true
}

步驟 4：取得電話號碼編號

若要傳送訊息，您必須註冊要使用的電話號碼，也就是先前在準備工作一節中提及的商家電話號碼。

請務必先找到該電話號碼的編號，才能繼續進行註冊程序。若要取得電話號碼編號，請發出下列 API 呼叫：

curl -X GET \
'https://graph.facebook.com/v19.0/WHATSAPP_BUSINESS_ACCOUNT_ID/phone_numbers' \
-H 'Authorization: Bearer ACCESS_TOKEN'

如果要求成功，回應會包含所有連結至您 WABA 的電話號碼：

{
  "data": [
    {
      "verified_name": "Jasper's Market",
      "display_phone_number": "+1 631-555-5555",
      "id": "1906385232743451",
      "quality_rating": "GREEN"
    },
    {
      "verified_name": "Jasper's Ice Cream",
      "display_phone_number": "+1 631-555-5556",
      "id": "1913623884432103",
      "quality_rating": "NA"
    }
  ]
}

請儲存要註冊的電話號碼編號。如需更多這個端點的相關資訊，請參閱讀取電話號碼。

移轉例外狀況

步驟 5：註冊電話號碼

取得電話號碼編號後，即可進行註冊。在註冊 API 呼叫中，您必須同時執行下列兩項操作：

1. 註冊電話號碼。
2. 設定 6 位數註冊代碼，以便啟用雙步驟驗證；這組代碼必須由您自行設定。請儲存並記住這組代碼，因為系統稍後會要求您提供這項資訊。

必須設定雙重驗證才能使用雲端 API。如果未設定，將收到設置失敗訊息：

要求範例：

curl -X POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/register' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"messaging_product": "whatsapp","pin": "6_DIGIT_PIN"}'

回應範例：

{
  "success": true
}

內嵌註冊用戶

步驟 6：接收來自消費者應用程式的訊息

當參與互動的顧客傳送訊息給商家時，您在 24 小時內都可以免費回傳訊息，這段時間稱為「顧客服務時段」。為了進行測試，我們會啟用這個時段，您要傳送多少訊息都可以。

如果是使用個人的 iOS 版／Android 版 WhatsApp 應用程式，請傳送訊息至剛才註冊的電話號碼。發送訊息後，您應該會收到傳送至 Webhook 的傳入訊息和通知，格式如下所示。

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "16315551234",
              "phone_number_id": "PHONE_NUMBER_ID"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Kerry Fisher"
                },
                "wa_id": "16315555555"
              }
            ],
            "messages": [
              {
                "from": "16315555555",
                "id": "wamid.ABGGFlA5FpafAgo6tHcNmNjXmuSf",
                "timestamp": "1602139392",
                "text": {
                  "body": "Hello!"
                },
                "type": "text"
                }
            ]
          },
        "field": "messages"
        }
      ]
    }
  ]
}

步驟 7：傳送測試訊息

啟用顧客服務時段後，您可以傳送測試訊息至上一個步驟用到的消費者電話號碼。若要這麼做，請發出下列 API 呼叫：

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", "to": "16315555555","text": {"body" : "hello world!"}}'

如果呼叫成功，回應會包含訊息編號。您可以使用這個編號，透過 Webhooks 追蹤訊息傳送進度。編號長度不可超過 128 個字元。

回應範例：

{
  "id":"wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o"
}

保持每月更新

我們會在每個月的第一個星期二發行雲端 API 更新項目，其中會包括新功能和改進項目。您不需要任何動作即可使用任何新功能，因為雲端 API 會自動更新。

常見問題

一般常見問題

技術實作常見問題

What is the architecture of the Cloud API?

The Cloud API architecture significantly simplifies the Solution Partner's operational and infrastructure requirements to integrate with WhatsApp Business Platform. First, it removes the infrastructure requirements to run Business API docker containers (CAPEX savings). Second, it obviates the need of operational responsibilities to manage the deployment (OPEX savings). For details, refer to the architecture diagram comparing the On-Premises and Cloud API deployments.

永久連結

資料隱私和帳號安全常見問題

法規遵循常見問題