Messenger 開放平台

Messenger 平台的對話 API

本文件說明如何瞭解 Messenger 和 Instagram 傳訊對話的相關資訊。您會收到以下資訊：

  • Facebook 粉絲專頁或 Instagram 專業帳號的對話清單
  • 每個對話內的訊息清單
  • 與每個訊息相關的詳細資訊，包括訊息發送時間以及發送者

準備工作

本教學導覽假設您已閱讀 Messenger 平台總覽與 Instagram 傳訊總覽，且已實作所需的元件。

必備資料：

  • 貴公司的 Facebook 粉絲專頁或與您的 Instagram 專業帳號連結之 Facebook 粉絲專頁的編號
  • 可在粉絲專頁上執行 MESSAGING 或 MODERATE 任務之用戶所要求的粉絲專頁存取權杖
  • 若要存取您的商家與傳訊應用程式、Instagram 專業帳號、Facebook 粉絲專頁，或商家中未擁有角色之成員間所進行的對話，必須使用進階存取權限

您的應用程式需要具備下列項目，用戶才能和您的粉絲專頁進行 Messenger 對話：

您的應用程式需要具備下列項目，用戶才能和您的 Instagram 專業帳號進行 Instagram 傳訊對話：

  • 用戶要求的粉絲專頁存取權杖，該用戶能夠在與您的 Instagram 商業帳號連結的粉絲專頁上執行 MESSAGING 任務
  • instagram_basic、instagram_manage_messages 和 pages_manage_metadata 權限
  • 您的應用程式必須屬於已經通過驗證的商家

限制

  • 只有分享的標註或影片網址才會包含在呼叫 API 所傳回的資料或 Webhooks 通知中。
  • 如果您的帳號是使用電子郵件或電話號碼等私密金鑰連結，您將無法擷取這些帳號之間的對話。只會提供一位 Facebook 用戶與一個 Instagram 帳號之間的對話。當您的應用程式經過核准可使用 Advanced Access 時，此問題隨即獲得解決。如果您在 Instagram 應用程式的「帳號管理中心」內已連結多個帳號，您將可以擷取所有連結之帳號間的對話。
  • 「要求」資料夾中已 30 天沒有活動的對話不會在 API 呼叫中傳回。

當 Instagram 商業帳號第一次與您的應用程式連線時，您可以利用此 API 對過去的對話進行收件匣同步。

取得對話清單

若要取得對話清單，請傳送 GET 要求至 /PAGE-ID/conversations 端點，並包含 platform 參數（設為 instagram 或 messenger）。

要求範例

採用方便閱讀的格式
curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &access_token=PAGE-ACCESS-TOKEN"

成功後，您的應用程式會收到一個 JSON 物件，以及您與用戶之間所進行之對話的編號清單，還有最近傳送訊息的時間。

{
  "data": 
    {
      "id": "CONVERSATION-ID-1",  
      "updated_time": "UNIX-TIMESTAMP"
    },
    {
      "id": "CONVERSATION-ID-2",   
      "updated_time": "UNIX-TIMESTAMP"
    }
    ...
  ]
}

尋找與特定用戶的對話

若要取得 Instagram 專業帳號或 Facebook 粉絲專頁與特定用戶之間的對話，請傳送 GET 要求至 /PAGE-ID/conversations 端點，並包含 platform 參數和 user_id 參數（設為用戶的 Instagram 範圍編號或粉絲專頁範圍編號）。

要求範例

採用方便閱讀的格式
curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &user_id=INSTAGRAM-OR-PAGE-SCOPED-ID
    &access_token=PAGE-ACCESS-TOKEN"

成功後，您的應用程式會收到對話編號。


{
  "data": [
      {
        "id": "CONVERSATION-ID"
      },
  ]
}

取得對話中的訊息清單

若要取得對話中的訊息清單，請傳送 GET 要求至 /CONVERSATION-ID 端點，並包含 messages 欄位。

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/CONVERSATION-ID
    ?fields=messages
    &access_token=PAGE-ACCESS-TOKEN"

成功後，您的應用程式會收到訊息編號清單，以及建立每則訊息的時間。

{
  "messages": {
    "data": [
      {
        "id": "Message ID-1",      
        "created_time": "UNIX-TIMESTAMP-MOST-RECENT-MESSAGE"  
      },
      {
        "id": "Message ID-2",
        "created_time": "UNIX-TIMESTAMP"
      },
      {
        "id": "Message ID-3",
        "created_time": "UNIX-TIMESTAMP"
      },
...
    ]
  },
  "id": "Conversation ID", 
}

取得訊息相關資訊

如要取得訊息相關資訊，例如傳送者、接收者與訊息內容，請將 GET 要求傳送至 /MESSAGE-ID 端點，且包含您感興趣的欄位。

預設欄位是 id 與 created_time。

備註：查詢 /CONVERSATION-ID 端點時，將傳回對話中的所有訊息標號。不過，您只能取得對話中最近 20 則訊息的詳細資訊。如果您查詢最近 20 則訊息之前的訊息，您將看到訊息已遭到刪除的錯誤。

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/MESSAGE-ID
    ?fields=id,created_time,from,to,message
    &access_token=PAGE-ACCESS-TOKEN"

成功時，應用程式會收到下列 JSON 回應。在此範例中，顧客已將純文字訊息傳送至您的 Instagram 專業帳號。

{
  "id": "aWdGGiblWZ...",
  "created_time": "2022-07-12T19:11:07+0000",
  "to": {
    "data": [
      {
        "username": "INSTAGRAM-PROFESSIONAL-ACCOUNT-USERNAME",
        "id": "INSTAGRAM-PROFESSIONAL-ACCOUNT-ID"
      }
    ]
  },
  "from": {
    "username": "INSTAGRAM-USERNAME",
    "id": "INSTAGRAM-SCOPED-ID"
  },
  "message": "Hi Kitty!"
}

瞭解詳情

請瀏覽以下的參考資料：

開發人員支援