Messenger 平台

新手指南

本文件會講解如何透過應用程式成功呼叫 Messenger API Instagram 支援（亦即開發人員政策中所指的「Instagram 訊息傳送功能 API」），並獲取 Instagram 專業帳戶訊息。在本文中，我們假設您已熟悉 Graph API 和 Facebook 登入。

準備工作

您需要擁有以下項目的存取權：

Messenger 平台的新開發人員

  • 遵從下述的逐步指南，了解如何產生專頁存取憑證、webhooks 設定。
  • 了解各種平台功能，並採用適合您需要的功能。

有 Messenger 平台經驗的開發人員

  • 存取憑證與 webhooks 的概念類似。Messenger API Instagram 支援功能將需要專頁存取憑證中的 instagram_manage_messages，以及訂閱的 Instagram 主題的 webhooks。
  • 大多數功能都類似於 Messenger API。請查閱功能清單中的詳細資料，並採用適合您需要的功能。

登入流程

您可以使用 Facebook 登入或 Instagram 商家專用登入，向應用程式用戶要求所需的權限。

用戶可透過執行 Instagram 商家專用登入 流程，在登入流程期間完成以下操作：

  • 將 Instagram 帳戶轉換為 Instagram 專業帳戶
  • 為企業建立 Facebook 專頁
  • 連結專頁與 Instagram 專業帳戶

如要執行 Instagram 商家專用登入流程，請先瀏覽 Instagram 商家專用登入指南 ，然後返回本指南。

1. 取得用戶存取憑證

請確保您已登入 Facebook 開發人員帳戶，然後存取應用程式並觸發 Facebook 登入模組。請記住，您的 Facebook 開發人員帳戶必須能夠在已連結至您想查詢的 Instagram 帳戶之 Facebook 頁面中，至少以「審核」級別存取權來執行工作。

觸發模組之後，點擊「OK」來為您的應用程式授予 instagram_basic、instagram_manage_messages 和 pages_manage_metadata 權限。

API 應會傳回用戶存取憑證。擷取該憑證，以便您的應用程式在接下來的若干查詢中使用它。如果您使用的是 Graph 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 專頁集合，目前 Facebook 用戶可以執行 MANAGE、CREATE_CONTENT、MODERATE 或 ADVERTISE 任務：

{
  "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 呼叫，您需要使用相關 Instagram 專業帳戶的相應專頁存取憑證（PAT）（此憑證之前經由 Facebook 登入流程授予）。

使用您的用戶存取憑證，向 /{page-id} 端點傳送一項 GET 要求。例如：

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 帳戶和 Facebook 專頁），可利用開發人員應用程式管理中心下的 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"
    }
}

如果您可以成功執行這個最終查詢，您應該能夠使用任何 Messenger API Instagram 支援端點執行查詢：只需參考我們的各種指南和參考文件，了解每個端點可以執行的操作及其所需權限。

後續步驟

  • 進一步開發您的應用程式，使之能夠成功使用所需的任何其他端點，並持續留意每個端點需要的權限
  • 完成 Webhook 設定，以便其在用戶向 Instagram 專業帳戶傳送訊息時能夠即時接收通知。
  • 完成應用程式審查流程，就您應用程式所需的所有權限取得核准，以便待您的應用程式正式推出後，用戶可向您授予這些權限。

開發人員支援