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

Webhook 中的 Instagram 限時動態提及與回覆

Instagram 會以私訊形式,透過 messages Webhook 欄位送出限時動態提及與回覆。提及會以一則訊息送達,其 attachments 內含一個類型為 story_mention 的項目,限時動態的 CDN 網址位於 payload.url。回覆會附上用戶的文字,以及 reply_to.story,其中包含該限時動態的 url 與 id;若該限時動態帶有連結貼紙,則另有 link_sticker_url。

easyCoexistence 會為每個已連接的 Instagram 帳戶訂閱 messages,因此限時動態提及與回覆會隨其他私訊即時送達您的 HTTPS 端點,以該帳戶的密鑰簽署,且不保留副本。

story_mention

用戶在限時動態中提及帳戶時,Meta 發送的 messages 事件所屬的附件類型。

link_sticker_url

Meta 於 2025 年 12 月 12 日在 reply_to.story 加入欄位,載有所回覆限時動態的連結貼紙網址。

24 hours

限時動態的存續時間;限時動態過期或被刪除後,其提及網址將無法顯示。

Public

哪些帳戶的限時動態提及會送達;私人帳戶只有在關注專業帳戶時,其提及才會送達。

GIF, sticker

Meta《Instagram 訊息指南》所列、Webhook 不支援的限時動態回覆類型。

限時動態提及如何送達?

以私訊形式送達。當用戶在限時動態中提及專業帳戶,Instagram 會在帳戶的收件匣中放入一則引用該限時動態的訊息,Meta 並會為此發送一個 messages 事件。sender.id 是用戶的 Instagram 範圍 ID,message.attachments 內含一個類型為 story_mention 的項目,其 payload.url 即為該限時動態的 CDN 網址。Meta 的範例不含文字,因此須讀取附件:

A Story mention, 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>",
            "attachments": [
              {
                "type": "story_mention",
                "payload": { "url": "<CDN_URL>" }
              }
            ]
          }
        }
      ]
    }
  ]
}

限時動態回覆如何送達?

同樣以私訊形式送達,包含用戶的訊息,以及一個指向帳戶限時動態的 reply_to 物件。reply_to.story 載有該限時動態的 CDN url 與 id。Meta 的 Webhook 參考文件亦列出 link_sticker_url,為 2025 年 12 月新增,適用於回覆帶有連結貼紙的限時動態,Meta 建議用以按連結路由自動化流程。若是回覆較早的訊息,則改用 reply_to.mid。

The message object of a Story reply
"message": {
  "mid": "<MESSAGE_ID>",
  "text": "<MESSAGE_TEXT>",
  "reply_to": {
    "story": {
      "url": "<CDN_URL>",
      "id": "<STORY_ID>"
    }
  }
}

各欄位的意義為何?

以下為 Meta 就這兩類事件所載的欄位,由外至內排列:

  • entry[].id 與 recipient.id:專業帳戶。sender.id:用戶的 Instagram 範圍 ID,即回覆所指向的 ID。
  • timestamp:訊息的發送時間,Meta 範例中以毫秒計;entry[].time 則是 Meta 發出通知的時間。
  • message.mid:訊息 ID,用於去除重複的重試請求,以及配合 reply_to.mid 回覆。
  • attachments[].type story_mention 與 payload.url:提及,以及產生該提及的限時動態之 CDN 網址。
  • reply_to.story.url 與 reply_to.story.id:用戶所回覆的帳戶限時動態。
  • reply_to.story.link_sticker_url:該限時動態連結貼紙上的網址。
  • message.text:回覆的文字內容,訊息含文字時才會包含。

限時動態網址可用多久?

與限時動態的存續時間相同。限時動態會在 24 小時後消失,或於作者刪除時消失;Meta 的限時動態提及指南指出,此後該網址將無法顯示。其概覽另補充,Instagram 的 CDN 網址具私隱保護,對已刪除或過期的內容將不回傳任何資料。同一指南允許保存 CDN 網址,但不允許保存媒體:應用程式不得在伺服器上儲存或快取限時動態的內容,限時動態消失後應顯示佔位圖像。

哪些情況下兩類事件都不會觸發?

Meta 的指南列出以下情況,在這些情況下,等待限時動態事件的處理程式將收不到任何資料:

  • 並未關注專業帳戶的私人帳戶所作的限時動態提及。
  • 一般貼文中的標記:Meta 表示只有限時動態提及會觸發 messages Webhook,貼文標記不會。
  • 以 GIF 或貼圖回覆限時動態,Webhook 不支援此類回覆。
  • 透過提及 API 處理的限時動態:GET /<IG_ID>/tags 與 POST /<IG_ID>/mentions 均不支援,因此限時動態提及是以私訊形式送達。

限時動態提及與回覆會開啟訊息窗口嗎?

會。回覆屬於用戶發出的訊息,而 Meta 將限時動態提及列為用戶發起對話的途徑之一。用戶的行動所開啟的窗口,對大多數行動而言為 24 小時,因此帳戶可在窗口開啟期間,以 POST /<IG_ID>/messages 回覆,並將 recipient.id 設為事件的 sender.id。帳戶的回覆會以回聲(echo)形式回傳至 messages,其中 is_echo 為 true。

easyCoexistence 如何轉發?

透過 messages 欄位轉發。每個已連接的帳戶均已訂閱此欄位,因此限時動態提及與回覆會與帳戶的其他私訊一併送達您的端點。每則 entry 會置於一個信封內,信封包含 platform、account_id、external_id 與 entry,並以該帳戶的密鑰簽署於 X-EC-Signature 標頭中,僅發送一次,且不保留副本。send_social_dm 會以事件的 sender.id 作為 recipient_id 回覆該用戶,並須在 24 小時窗口內進行。

A forwarded Story mention, 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": 1793448000512,
    "messaging": [
      {
        "sender": { "id": "<IGSID>" },
        "recipient": { "id": "<IG_ID>" },
        "timestamp": 1793447999874,
        "message": {
          "mid": "<MESSAGE_ID>",
          "attachments": [
            { "type": "story_mention", "payload": { "url": "<CDN_URL>" } }
          ]
        }
      }
    ]
  }
}

常見錯誤

  • 儲存限時動態的媒體。Meta 的限時動態提及指南允許保存 CDN 網址,但不允許保存內容,而內容不得儲存或快取於您的伺服器上。
  • 只讀取 message.text。限時動態提及附有類型為 story_mention 的附件,且在 Meta 的範例中不含文字,因此只處理文字的處理程式會看到空白訊息。
  • 數天後才顯示限時動態網址。限時動態於 24 小時後過期或被刪除,網址便會失效,此後應改為顯示佔位圖像。
  • 在 comments 欄位或提及 API 中尋找限時動態提及。Meta 會以 messages 上的私訊形式送達。
使用 EasyCoexistence 完成這項設定

send_social_dm 會在 24 小時窗口內回覆用戶,回覆來源可為 Claude、ChatGPT 或您自己的程式碼。每個連接每月由 US$ 9 起,連接越多越便宜,最低降至 US$ 0.75,首 3 日免費。

常見問題

Instagram 限時動態提及事件是否包含文字?

Meta 的範例中不包含。限時動態提及附有類型為 story_mention 的附件,內含限時動態的 CDN 網址,因此只讀取 message.text 的處理程式會看到空白訊息。

Instagram 限時動態回覆中的 link_sticker_url 是什麼?

是用戶所回覆限時動態的連結貼紙上的網址,位於 reply_to.story.link_sticker_url。Meta 於 2025 年 12 月 12 日加入此欄位,並建議用以按連結路由自動化流程。

以 GIF 或貼圖回覆限時動態會觸發 Webhook 嗎?

不會。Meta 的《Instagram 訊息指南》指出,Webhook 不支援以 GIF 或貼圖回覆的限時動態。

私人帳戶會觸發限時動態提及的 Webhook 嗎?

只有在該私人帳戶關注專業帳戶時才會。公開帳戶的提及則會即時送達。

繼續閱讀

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

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

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

驗證日期