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

Instagram 訊息 Webhook:私訊負載、回聲與欄位

Instagram 訊息 Webhook 欄位會把專業帳戶的私訊即時送出:文字、附件、分享內容、限時動態回覆與提及、內嵌回覆及刪除事件。每個事件都位於 messaging 陣列中,包含發送者的 Instagram 範圍 ID、接收者、時間戳記與 message 物件;帳戶自己發出的訊息會以 is_echo 設為 true 的形式,回傳到同一欄位。

easyCoexistence 為每個已連接的 Instagram 帳戶訂閱 messages,並把其私訊(包括回聲)在抵達時轉發到你的 HTTPS 端點,以該帳戶的密鑰簽署;轉發不保留副本,私訊預設亦不儲存。

is_echo

在訊息事件上設為 true,代表該訊息由帳戶自己發出。

24 hours

大多數用戶操作適用的標準訊息時段,期間應用程式可以回覆該用戶。

ig_post

分享貼文的附件類型;舊的 share 類型只支援至 2026 年 2 月 1 日。

story_mention

有人在限時動態中提及帳戶時,Meta 發送的私訊事件所用的附件類型。

2534041

帳戶擁有者停用 Instagram 私訊存取時,代碼 200 下的錯誤子代碼。

messages 欄位何時觸發?

當用戶發私訊給專業帳戶,以及帳戶發出私訊時觸發。Meta 的範例與參考資料列出以下情況,每一種都是帶有 message 物件的 messaging 事件:

  • 文字,以及以附件形式傳送的媒體:圖片、影片、音訊與檔案。
  • 分享的貼文或 Reel,以 ig_post、ig_reel 或 reel 附件形式傳送。
  • 對帳戶限時動態的回覆,以 reply_to.story 表示;提及帳戶的限時動態,以 story_mention 附件表示。
  • 內嵌回覆早前的訊息(reply_to.mid),以及快速回覆(quick_reply.payload)。
  • 用戶刪除的訊息(is_deleted)、不支援的媒體(is_unsupported),以及來自 Click-to-Direct 廣告點擊者的訊息(referral)。
  • 帳戶發出的訊息,會以 is_echo 設為 true 回傳。

訊息通知是什麼樣子?

一個 POST 請求,其 JSON 的 object 設為 instagram。與留言不同,訊息位於帳戶 entry 內的 messaging 陣列中,每個元素都包含 sender、recipient、timestamp 與 message。以下是對帳戶限時動態的回覆範例:

A messages notification, as Meta sends it
{
  "object": "instagram",
  "entry": [
    {
      "id": "<IG_ID>",
      "time": 1793448000512,
      "messaging": [
        {
          "sender": { "id": "<IGSID>" },
          "recipient": { "id": "<IG_ID>" },
          "timestamp": 1793447999874,
          "message": {
            "mid": "<MESSAGE_ID>",
            "text": "<MESSAGE_TEXT>",
            "reply_to": {
              "story": {
                "url": "<CDN_URL_FOR_THE_STORY>",
                "id": "<STORY_ID>"
              }
            }
          }
        }
      ]
    }
  ]
}

每個欄位代表什麼?

以下是 Meta 在 Instagram Login 下為訊息事件記錄的欄位,由外至內排列:

  • entry[].id:專業帳戶的 ID。entry[].time:Meta 發出通知的時間,Meta 的訊息範例以毫秒表示。
  • sender.id 與 recipient.id:收到私訊時,分別為用戶的 Instagram 範圍 ID 與帳戶的 ID;回聲時則對調。
  • timestamp:訊息發出的時間,Meta 範例以毫秒表示。請按此排序,而非按抵達次序排序。
  • message.mid:訊息 ID,用於去重、表情回應,以及以 reply_to.mid 回覆該訊息。
  • message.text:訊息含文字時才會包含。
  • message.attachments[]:每項都有 type 與 payload,通常包含 url。分享貼文的 ig_post payload 會加入 ig_post_media_id 與 title(即其說明文字)。
  • message.reply_to:內嵌回覆為 mid;限時動態回覆則為 story,包含限時動態的 url 與 id。
  • message.quick_reply.payload 與 message.referral:所選的快速回覆,以及 Click-to-Direct 廣告的 ref、ad_id、source、type 與 ads_context_data。
  • message.is_deleted、is_echo、is_self 與 is_unsupported:只在為 true 時才包含。
  • message.admin_text 與 handoff_reason:在符合資格的應用程式上,表示 Meta 應用程式(例如 Meta Business Agent)已將對話轉交的通知;可能沒有 mid 或文字。

回聲如何運作?

帳戶發出訊息時,Meta 同樣會為此發送訊息事件,並將 is_echo 設為 true。此時 sender.id 為帳戶,recipient.id 為用戶的 Instagram 範圍 ID;帳戶發給自己的測試訊息亦會帶有 is_self。回聲記錄了帳戶的發言,對話紀錄需要它;但決定是否回覆的處理程序必須略過回聲。帳戶對訊息作出表情回應或移除回應時,Meta 不會發出回聲。

An echo of a message the account sent
{
  "object": "instagram",
  "entry": [
    {
      "id": "<IG_ID>",
      "time": 1793448061203,
      "messaging": [
        {
          "sender": { "id": "<IG_ID>" },
          "recipient": { "id": "<IGSID>" },
          "timestamp": 1793448060950,
          "message": {
            "mid": "<MESSAGE_ID>",
            "text": "<REPLY_TEXT>",
            "is_echo": true
          }
        }
      ]
    }
  ]
}

應該回覆哪個 ID?

sender.id,即用戶的 Instagram 範圍 ID。用戶向帳戶發訊息或在其媒體留言時,Meta 會建立此 ID,它只屬於該用戶與該帳戶。以 recipient.id 設為此 ID 呼叫 POST /<IG_ID>/messages 即可發出回覆。事件不包含名稱或用戶名稱;呼叫 GET /<IGSID> 並指定 name 與 username 等欄位即可取得,因為曾向帳戶發訊息的用戶已給予該查詢所需的同意。

私訊如何開啟 24 小時時段?

應用程式只能在用戶先向帳戶發訊息後,並且只能在該行為所開啟的標準訊息時段內,向用戶發訊息。大多數行為的時段為 24 小時;由點擊 Click-to-Direct 廣告後發出的第一則訊息,最長可達 7 天。用戶的新訊息會開啟新的時段,因此應追蹤其最新的 timestamp;回聲屬於帳戶自己發出的訊息,不會延長任何時段。用戶撰寫的回覆可以使用 Meta 獨立的 7 天 Human Agent 時段,並以 human_agent 標記。

訊息事件不包含什麼?

根據 Meta 的訊息參考資料,處理程序可能會尋找的一些資料並不包含在內:

  • 用戶的名稱或用戶名稱:只有 Instagram 範圍 ID,可透過 GET /<IGSID> 解析。
  • 只能觀看一次的媒體:以不含 URL 的暫時附件形式抵達。
  • 確切的輪播圖片:對輪播貼文中某張圖片的表情回應或轉寄,只會回報第一張圖片。
  • 表情回應、編輯與已讀回條:它們位於各自的欄位中。
  • 已讀標記:透過 webhook 送達的訊息,在傳送回覆之前,會在 Instagram 收件匣中保持未讀。

Meta 還列出哪些其他訊息欄位?

Meta 在 Instagram Login 下的欄位清單與範例,除 messages 外還列出以下各項,每項都是獨立的訊息事件。easyCoexistence 只為每個帳戶訂閱 messages、comments 與 mentions,因此以下各項都不在其轉發的內容之中:

  • message_reactions:用戶對訊息作出表情回應或移除回應,包含 reaction.mid、action(設為 react 或 unreact),以及 reaction 與 emoji。
  • message_edit:用戶編輯訊息,包含 message_edit.mid、新文字與 num_edit。
  • messaging_postbacks:用戶點選破冰提示或範本按鈕,包含 postback.mid、title 與 payload。
  • messaging_referral:已在對話中的用戶開啟附有 ref 參數的 ig.me 連結。
  • messaging_seen:用戶閱讀訊息,包含 read.mid。
  • messaging_optins、messaging_handover 與 standby:後兩者適用於根據 Meta 交接協議共用對話的應用程式。

帳戶必須開啟什麼?

「允許存取訊息」。Meta 要求專業帳戶先開啟此設定,才能透過 API 管理其訊息:在 Instagram 應用程式中前往「設定」、「訊息和限時動態回覆」、「訊息控制」、「已連接的工具」。關閉時,發送會以代碼 200、子代碼 2534041 失敗。應用程式亦需要 instagram_business_basic 與 instagram_business_manage_messages;如要服務並非由其擁有或管理的帳戶,則需要 Advanced Access。

easyCoexistence 如何轉發私訊?

與留言相同:Meta 為帳戶發送的每個 entry,都會以 platform、account_id、external_id 與 entry 組成的信封,POST 到你的 HTTPS 端點。信封以 X-EC-Signature 簽署,使用該帳戶的密鑰,每則只發送一次,不保留副本。回聲與其他內容一同轉發,因此回覆前請先檢查 is_echo。如需回覆,請呼叫 send_social_dm,帶入 account_id,並將事件的 sender.id 作為 recipient_id,且須在 24 小時時段內。以私訊觸發的自動化,會在同一批事件上運行。

A forwarded DM with an image
{
  "platform": "instagram",
  "account_id": "<ACCOUNT_ID>",
  "external_id": "<IG_ID>",
  "entry": {
    "id": "<IG_ID>",
    "time": 1793448000512,
    "messaging": [
      {
        "sender": { "id": "<IGSID>" },
        "recipient": { "id": "<IG_ID>" },
        "timestamp": 1793447999874,
        "message": {
          "mid": "<MESSAGE_ID>",
          "attachments": [
            { "type": "image", "payload": { "url": "<URL_FOR_THE_MEDIA>" } }
          ]
        }
      }
    ]
  }
}

常見錯誤

  • 回覆回聲。is_echo 已設定的事件是帳戶自己的訊息,回覆它會令帳戶與自己形成循環。
  • 假設訊息一定含有文字。附件、分享內容、限時動態提及與刪除,抵達時都不含 text 欄位,因此應按 message 物件中的內容分支處理。
  • 按抵達次序排列訊息。Meta 在故障後可能亂序送達訊息,因此應按 timestamp 排序。
  • 把 time 與 timestamp 當作秒解析。Meta 的訊息範例兩者都以毫秒表示;若當作秒讀取,會變成遙遠未來的日期。
使用 EasyCoexistence 完成這項設定

send_social_dm 在 24 小時時段內回覆,自動化可按固定文字或 AI 自行回覆。每個連接每月 US$ 9 起,連接越多越便宜,最低降至 US$ 0.75,前 3 天免費。

常見問題

Instagram 訊息 Webhook 的時間戳記是秒還是毫秒?

Meta 的訊息範例中,timestamp 與 entry 的時間都以毫秒表示。若當作秒讀取,會變成遙遠未來的日期。

如何從 Instagram 私訊 Webhook 取得發送者的用戶名稱?

呼叫 GET /<IGSID>,並指定 name 與 username 等欄位。事件只包含用戶的 Instagram 範圍 ID。

為什麼我的 Instagram 私訊 Webhook 沒有抵達?

請檢查:帳戶是否已開啟「允許存取訊息」;是否已透過 /subscribed_apps 訂閱 messages;應用程式是否處於 Live 模式,且對非其擁有的帳戶具備 Advanced Access。

easyCoexistence 會轉發 Instagram 訊息的表情回應嗎?

不會。表情回應位於 message_reactions 中,而 easyCoexistence 只為帳戶訂閱 messages、comments 與 mentions。

繼續閱讀

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

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

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

驗證日期