登入開始免費試用
easyCoexistence 官方 API

Instagram 留言 Webhook:負載逐欄說明

Instagram 留言 Webhook 的 comments 欄位,會在有人於專業帳戶的媒體(包括 Reels)上留言,或回覆該媒體上的留言時通知應用程式。Meta 會發出一項 change,其 field 設為 comments,value 載有留言的 id 與文字、作者的 Instagram 範圍 ID 與用戶名稱(位於 from 中)、媒體的 id 與產品類型,以及留言為回覆時的 parent_id。

easyCoexistence 會為每個已連接的 Instagram 帳戶訂閱 comments,並把 Meta 就該帳戶發送的 comments 事件,一經到達即轉發至您的 HTTPS 端點,以該帳戶的密鑰簽名,且不保留副本。

parent_id

留言為回覆時才會出現,載有其所回覆留言的 ID。

self_ig_scoped_id

當帳戶在自己的媒體上留言時,會加入 from 中,與帳戶本身的 ID 並列。

live_comments

Live 直播期間留言的獨立欄位;直播結束後,其通知即告停止。

Advanced Access

為 comments 及 live_comments 通知所必需;私人帳戶擁有的媒體不會觸發任何通知。

7 days

以留言 ID 指定,可向留言者發送一則私人回覆的剩餘時限。

comments 欄位在何時觸發?

當有人在專業帳戶擁有的媒體上留言,或提及該帳戶時,只要應用程式與帳戶均已訂閱該欄位,便會觸發。每則留言在通知中為一項 change,以下各種情況的結構相同:

  • 在帖文、Reels、Story 或廣告上的新留言,附有 media.media_product_type,指明該媒體屬於哪一種版位。
  • 對現有留言的回覆,附有 parent_id,載有其所回覆留言的 ID。
  • 帳戶在自己的媒體上作出的留言(包括其回覆):from.id 為帳戶本身的 ID,並在 from 中加入 self_ig_scoped_id。
  • 帳戶被 @ 提及:使用 Instagram Login 時,Meta 會把提及併入 comments 通知,而不另設欄位。
  • Live 直播期間的留言會送至獨立的 live_comments 欄位,結構相同,直播結束後即停止。

comments 通知是什麼樣子?

一個 POST 請求,其 JSON 的 object 設為 instagram,並有一個 entry 陣列。每個 entry 代表一個專業帳戶,包括其 ID、Meta 發送通知的時間,以及一個 changes 陣列,每則留言佔一項 change。以下是一則 Reels 回覆的例子:

A comments notification, as Meta sends it
{
  "object": "instagram",
  "entry": [
    {
      "id": "<IG_ID>",
      "time": 1793448000,
      "changes": [
        {
          "field": "comments",
          "value": {
            "id": "<COMMENT_ID>",
            "parent_id": "<PARENT_COMMENT_ID>",
            "text": "<COMMENT_TEXT>",
            "from": {
              "id": "<INSTAGRAM_SCOPED_ID>",
              "username": "<USERNAME>"
            },
            "media": {
              "id": "<MEDIA_ID>",
              "media_product_type": "REELS"
            }
          }
        }
      ]
    }
  ]
}

每個欄位代表什麼?

以下是 Meta 的 Webhook 參考為留言列出的欄位,由外而內排列:

  • entry[].id:專業帳戶的 ID,即 /me 為其返回的 user_id。由此可得知留言屬於哪個帳戶。
  • entry[].time:Meta 發送通知的時間,為 Unix 時間戳記。它不是留言的撰寫時間。
  • changes[].field:comments,或 Live 直播的 live_comments。讀取 value 前應先檢查此欄位。
  • value.id:留言的 ID,即用於公開或私下回覆、隱藏或刪除的留言 ID。
  • value.text:留言的文字,留言含有文字時才會包括。
  • value.from.id 與 value.from.username:作者的 Instagram 範圍 ID 與用戶名稱。帳戶本身留言時,會出現 value.from.self_ig_scoped_id。
  • value.media.id 與 value.media.media_product_type:被留言的媒體及其版位;Meta 的媒體參考列出 AD、FEED、STORY 及 REELS。
  • value.parent_id:回覆留言時,為其所回覆留言的 ID。頂層留言沒有此欄位。
  • value.media.ad_id、ad_title 與 original_media_id:參考中列出,適用於廣告上的留言。

comments 欄位不會報告哪些內容?

根據 Meta 的設定指南與參考,若干處理程式可能預期的資料,在事件中被略去,或根本不會發送:

  • 私人帳戶擁有的媒體上的留言:Meta 不會就此發送留言或提及通知。
  • 相簿 ID:事件不包括相簿 ID,Meta 建議以留言 ID 查詢相簿。
  • 動態廣告所用媒體的廣告 ID。
  • 留言的建立時間:GET /<COMMENT_ID>?fields=timestamp 會以 ISO 8601 格式返回。
  • 直播結束後的 Live 留言,此時 Live 媒體的通知即告停止。
  • Story 提及:Meta 的提及 API 不支援,此類提及改以私訊送達帳戶。
  • 過去的事件:Meta 不保留可供查詢的通知紀錄,因此應在每則事件到達時儲存所需資料。

comments 欄位需要什麼?

使用 Instagram Login 時,需要 instagram_business_basic 與 instagram_business_manage_comments 權限,以及 Advanced Access,Meta 規定 comments 與 live_comments 通知須具備此項。應用程式必須處於 Live 模式,並於應用程式控制台中訂閱 comments;每個帳戶須透過 POST /<IG_ID>/subscribed_apps 完成訂閱,並在 subscribed_fields 中包含 comments。Meta 強烈建議以此 Webhook 代替輪詢留言,因其可減少對速率限制的消耗。

如何從事件回覆留言?

使用事件所載的 ID。POST /<COMMENT_ID>/replies 附上 message 參數,會以 value.id 在留言下發出公開回覆。POST /<IG_ID>/messages 並將 recipient.comment_id 設為 value.id,則可向作者發送一則私人回覆,須於留言後 7 天內發出,若為 Live 留言則須在直播期間發出。from.id 是 Instagram 範圍 ID,但在對方先私訊帳戶之前,直接發送至該 ID 的私訊會失敗,因此私人回覆正是透過私訊聯絡對方的方式。

easyCoexistence 如何轉發留言?

留言一到達便即時轉發。須先透過 Claude 或 ChatGPT 的 set_social_webhook_destination,或透過 Partner API 的 PUT /channels/:id/webhook,為帳戶設定端點。easyCoexistence 會把每個已連接帳戶訂閱至承載其留言、提及及私訊的欄位,檢查 Meta 對每次傳送的簽名,立即回應 Meta,並以信封格式將該帳戶的每個 entry 以 POST 發送至您的 HTTPS URL:

  • platform 與 external_id:instagram,以及該帳戶的 Instagram ID,即等同於 entry.id。
  • account_id:該連接在 easyCoexistence 的 ID,即 list_social_accounts 返回、MCP 工具所用的 ID。
  • entry:Meta 就該帳戶發出的 entry,原封不動。因此批次傳送會拆成每個 entry 一次 POST。Meta 的 object 欄位與 X-Hub-Signature-256 不會被傳遞。
  • 傳送:只嘗試一次,最多等候 8 秒,不跟隨重新導向,目的地須為解析至公開 IP 的 HTTPS 位址。不會保留副本,亦不會重試。
A forwarded comment, headers included
POST <YOUR_ENDPOINT>
Content-Type: application/json
X-EC-Signature: t=1793448001,v1=<HEX_HMAC_SHA256>

{
  "platform": "instagram",
  "account_id": "<ACCOUNT_ID>",
  "external_id": "<IG_ID>",
  "entry": {
    "id": "<IG_ID>",
    "time": 1793448000,
    "changes": [
      {
        "field": "comments",
        "value": {
          "id": "<COMMENT_ID>",
          "text": "<COMMENT_TEXT>",
          "from": { "id": "<INSTAGRAM_SCOPED_ID>", "username": "<USERNAME>" },
          "media": { "id": "<MEDIA_ID>", "media_product_type": "FEED" }
        }
      }
    ]
  }
}

留言轉私訊規則如何處理同一事件?

它們與轉發並行讀取同一事件。當留言包含規則中的任一關鍵字(不分大小寫)時即符合,適用於指定的某則帖文或所有帖文,並會把規則的私訊作為其私人回覆發給作者;若規則設有公開回覆,亦會一併發出。帳戶本身的留言會被略過;以留言觸發的自動化,則處理沒有被任何規則回覆的留言;而已被規則回覆的留言,仍會送達您的端點。規則的公開回覆,可能會以帳戶本身的新 comments 事件返回。

常見錯誤

  • 尋找 comment_id。使用 Instagram Login 時,留言的 ID 位於 value.id;comment_id 屬於 Meta 其他登入設定的負載。
  • 回覆帳戶自己的留言。帳戶的回覆會以 from.id 等於 entry.id 的 comments 事件返回,若自動化回覆這些留言,最終會變成與自己對話。
  • 把 entry.time 當作留言時間。它記錄的是 Meta 發送通知的時間;留言本身的 timestamp 欄位才說明其撰寫時間。
  • 在 comments 欄位等待 Live 留言。Live 留言會送至 live_comments,該欄位需要另行訂閱,直播結束後即不再有通知。
使用 EasyCoexistence 完成這項設定

留言轉私訊規則與自動化會全天候回覆同一批留言。每個連接每月由 US$ 9 降至 US$ 0.75,連接越多,價格越低,並提供 3 天免費試用。

常見問題

Instagram 留言 Webhook 是否包括留言的回覆?

包括。回覆會以獨立的 comments 事件送達,並在 parent_id 中載有其所回覆留言的 ID。

Reels 留言會觸發 Instagram 留言 Webhook 嗎?

會。Reels 上的留言與帖文上的留言一樣,透過 comments 欄位送達,media.media_product_type 可用來區分兩者。

為什麼我的 Instagram 留言 Webhook 沒有觸發?

最常見的原因是:應用程式未處於 Live 模式或沒有 Advanced Access、帳戶從未透過 /subscribed_apps 完成訂閱、媒體屬於私人帳戶,或留言位於 Live 直播中,而 Live 直播使用的是 live_comments。

留言 Webhook 是否包括留言者的用戶名稱?

包括。value.from 載有該用戶的用戶名稱,並與其 Instagram 範圍 ID 並列,因此無須額外呼叫即可顯示留言者是誰。

繼續閱讀

兩分鐘內連接您的第一個頻道。

無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。

  • 免費試用 3 天
  • 隨時取消
  • 只用官方 API
  • 24/7 監察

驗證日期