Messenger 開放平台

新手指南

本文說明如何使用您的應用程式成功呼叫適用於 Instagram 的 Messenger API 支援（在開發人員政策中亦稱為 Instagram 傳訊 API）並取得 Instagram 專業帳號訊息。本文假設您已熟悉圖形 API 和 Facebook 登入。

準備工作

您需要下列項目的存取權限：

Messenger 平台的新手開發人員

  • 請按照以下逐步指南的詳細說明，瞭解如何產生粉絲專頁存取權杖、Webhook 設定。
  • 瞭解各種平台功能，並採用適合您需求的功能。

擁有 Messenger 平台經驗的開發人員

  • 存取權杖與 Webhook 的概念相似。適用於 Instagram 的 Messenger API 支援需要有 instagram_manage_messages 在粉絲專頁存取權杖中，並訂閱 Instagram 主題 Webhook。
  • 大多數功能都與 Messenger API 類似。請檢視功能清單中的詳細資訊，並採用適合您需求的功能。

登入流程

您可以使用「Facebook 登入」或 Business Login for Instagram 向您的應用程式用戶要求所需的權限。

Business Login for Instagram 流程允許用戶在登入流程期間完成以下操作：

  • 將其 Instagram 帳號轉換成 Instagram 專業帳號
  • 為其商家建立 Facebook 粉絲專頁
  • 將該粉絲專頁連結到其 Instagram 專業帳號

若要實作 Business Login for Instagram，請瀏覽我們的 Business Login for Instagram 指南 ，然後返回本指南。

1. 取得用戶存取權杖

確認您已登入 Facebook 開發人員帳號，然後存取您的應用程式並觸發「Facebook 登入」視窗。請記得，您的 Facebook 開發人員帳號必須能夠在您要查詢之 Instagram 帳號連結的 Facebook 粉絲專頁上使用至少「中等」層級存取權限執行任務。

觸發該視窗之後，點擊「確定」以授予應用程式 instagram_basic、instagram_manage_messages 和 pages_manage_metadata 權限。

API 應會傳回用戶存取權杖。擷取權杖，以供應用程式在後面的幾個查詢中使用。如果您使用圖形 API 測試工具，將會自動擷取該工具並顯示在「存取權杖」欄位中以供參考：

2. 取得用戶的粉絲專頁

查詢 GET /me/accounts 端點（這會轉譯為 GET /{user-id}/accounts，根據您的存取權杖在 Facebook 用戶節點上執行 GET）。

curl -i -X GET \
 "https://graph.facebook.com/v9.0/me/accounts?access_token={access-token}"

這應會傳回目前 Facebook 用戶可在上面執行 MANAGE、CREATE_CONTENT、MODERATE 或 ADVERTISE 任務的 Facebook 粉絲專頁集合：

{
  "data": [
    {
      "access_token": "EAAJjmJ...",
      "category": "App Page",
      "category_list": [
        {
          "id": "2301",
          "name": "App Page"
        }
      ],
      "name": "Metricsaurus",
      "id": "134895793791914",  // capture the Page ID
      "tasks": [
        "ANALYZE",
        "ADVERTISE",
        "MODERATE",
        "CREATE_CONTENT",
        "MANAGE"
      ]
    }
  ]
}

擷取您要查詢之 Instagram 帳號連結的 Facebook 粉絲專頁編號。請注意，您的應用程式用戶也許能在多個粉絲專頁上執行任務，因此您最終必須引進邏輯，以判斷應擷取的粉絲專頁編號（或設計一個用戶介面，讓您的應用程式用戶能夠識別您的正確粉絲專頁）。

3. 取得粉絲專頁存取權杖

為了執行各種 Instagram 傳訊 API 呼叫，您需要使用之前透過 FB 登入流程授予的相關 Instagram 專業帳號的關聯粉絲專頁存取權杖（PAT）。

使用您的用戶存取權杖，傳送 GET 要求至 /{page-id} 端點。例如：

curl -i -X GET "https://graph.facebook.com/{page-id}?
  fields=access_token&
  access_token={user-access-token}"

成功時，應用程式會收到以下回應：

{
  "access_token":"{page-access-token}",
  "id":"{page-id}"              
}
  • 如果您使用短期用戶存取權杖，粉絲專頁存取權杖的有效時間只有 1 小時。
  • 如果您使用長期用戶存取權杖，粉絲專頁存取權杖則沒有到期時間。

若要產生長期粉絲專頁存取權杖，您可以按照這個指南操作。

3a. 透過 Instagram 開發人員主控板工具取得粉絲專頁存取權杖

此工具目前會在未來幾週內陸續開放給所有開發人員使用。如果您在應用程式主控板下沒看到這些設定，可以利用上述步驟 1 至 5 來產生粉絲專頁存取權杖。

或者，如果您擁有想要設置在適用於 Instagram 的 Messenger API 支援的資產（Instagram 帳號和 FB 粉絲專頁），您可以利用開發人員應用程式主控板下的 Instagram 設定工具，讓您輕鬆設定粉絲專頁存取權杖和 Webhooks。您可以在「開發人員應用程式主控板」→「Messenger」→「Instagram 設定」下找到此工具。現有配置權杖和 Webhook 的方式仍可使用，但是此工具可讓您以更輕鬆的方式來設定環境。

4. 啟用訊息控制連線工具設定

為了透過 API 管理 Instagram 訊息，Instagram 專業帳號需要在訊息控制設定中啟用連線工具切換開關。

5. 取得 Instagram 專業帳號的收件匣物件

使用您擷取的粉絲專頁編號和粉絲專頁存取權杖（PAT）來查詢 GET /{page-id}/conversations?platform=instagram 端點：

curl -i -X GET \
 "https://graph.facebook.com/v9.0/17841405822304914/conversations?platform=instagram&access_token={access-token}"

這應該會傳回 Instagram 用戶上所有對話串物件的編號：

{
  "data": [
    {
      "id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6OTAwMTAxNDYyOTkyODI6MzQwMjgyMzY2ODQxNzEwMzAwOTQ5MTI4MTM2MDk5MDc1MzYyOTgx"
    },
    {
      "id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6OTAwMTAxNDYyOTkyODI6MzQwMjgyMzY2ODQxNzEwMzAwOTQ5MTI4MTYzMzQ2MzE5NjM1NDcy"
    },
    {
      "id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6OTAwMTAxNDYyOTkyODI6MzQwMjgyMzY2ODQxNzEwMzAwOTQ5MTI4MTk3MTY0NjI2NzAyMjMw"
    },
    {
      "id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6OTAwMTAxNDYyOTkyODI6MzQwMjgyMzY2ODQxNzEwMzAwOTQ5MTI4MzkzNDI5MDYzMzkyNjU0"
    }
}

如果您能夠成功執行這個最後的查詢，應該就能使用任何適用於 Instagram 的 Messenger API 支援端點來執行查詢，請參閱我們提供的各種指南和參考文件，以瞭解每個端點的功能和所需的權限。

後續步驟

  • 進一步開發您的應用程式，使其能夠成功使用所需的任何其他端點，以及追蹤每個端點需要的權限
  • 完成 Webhook 設定，使其在用戶每次傳送訊息至 Instagram 專業帳號時，都能收到即時通知。
  • 完成應用程式審查程序，並要求核准應用程式需要的所有權限，讓您的應用程式用戶能夠在應用程式正式運作時授予這些權限。

開發人員支援