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 帳戶之間的對話。您可透過為應用程式要求進階存取權限來解決此問題。如果您在 Instagram 應用程式的帳戶管理中心連結了多個帳戶，則能夠檢索所有連結的帳戶之間的對話。
  • 系統不會在 API 呼叫中傳回要求資料夾內 30 天未處於活躍狀態的對話。

當有 Instagram 商業帳戶最近與您的應用程式連結時，您可使用此 API 來為收件匣同步過往對話。

取得對話清單

如要取得對話清單，請傳送 GET 要求至 /PAGE-ID/conversations 端點，其中包含設定為 instagram 或 messenger 的 platform 參數。

要求範例

我們已設定特定格式以便閱讀
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 參數，以及已設定為該用戶 Instagram 範圍編號或專頁範圍編號的 user_id 參數。

要求範例

我們已設定特定格式以便閱讀
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!"
}

了解詳情

另請參閱：

開發人員支援