登录开始免费试用
easyCoexistence 官方 API

Webhook 中的 Instagram 限时动态提及与回复

Instagram 以私信形式,通过 messages Webhook 字段推送限时动态提及和限时动态回复。提及以一条消息到达,其 attachments 中包含一个 type 为 story_mention 的项目,限时动态的 CDN URL 位于 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 的字段,包含所回复限时动态的链接贴纸 URL。

24 hours

限时动态的存续时长;一旦过期或被删除,其提及 URL 便不再显示。

Public

哪些账户的限时动态提及会到达;私密账户的提及只有在关注该专业账户时才会到达。

GIF, sticker

根据 Meta 的《Instagram Messaging 指南》,Webhook 不支持的限时动态回复。

限时动态提及如何到达?

以私信形式到达。当用户在其限时动态中提及该专业账户时,Instagram 会在该账户的收件箱中放入一条引用该限时动态的消息,Meta 也会为此发送一个 messages 事件。sender.id 是该用户的 Instagram 范围 ID,message.attachments 包含一个 type 为 story_mention 的项目,其 payload.url 即为该限时动态的 CDN URL。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,即回复的发送目标。
  • timestamp:消息发送的时间,Meta 示例中以毫秒计;entry[].time 则是 Meta 发送通知的时间。
  • message.mid:消息 ID,用于去除重试造成的重复,并用于通过 reply_to.mid 进行回复。
  • attachments[].type story_mention 与 payload.url:提及,以及产生该提及的限时动态的 CDN URL。
  • reply_to.story.url 与 reply_to.story.id:用户所回复的该账户限时动态。
  • reply_to.story.link_sticker_url:该限时动态链接贴纸上的 URL。
  • message.text:回复的文本内容,消息包含文本时才会出现。

限时动态 URL 能使用多久?

只要限时动态本身存在就能使用。限时动态会在 24 小时后消失,或在作者删除时消失,Meta 的限时动态提及指南称届时该 URL 将停止显示;其概述还补充,Instagram 的 CDN URL 具备隐私保护机制,对已删除或已过期的内容返回空结果。同一指南允许保留 CDN URL,但不允许保存媒体:应用不得在自己的服务器上存储或缓存限时动态内容,并应在限时动态消失后显示占位符。

什么情况下两类事件都不会触发?

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 字段转发,每个已连接的账户都会订阅该字段,因此限时动态提及和回复会与该账户的其他私信一同到达您的端点:每条事件位于一个信封中,信封包含 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 URL,但不允许保留内容,内容不得存储或缓存在您的服务器上。
  • 只读取 message.text。限时动态提及带有 type 为 story_mention 的附件,且在 Meta 的示例中没有文本,因此仅处理文本的处理程序会收到空消息。
  • 数日后仍渲染限时动态 URL。限时动态在 24 小时后过期或被删除,该 URL 便会失效,因此此后应显示占位符。
  • 在 comments 字段或提及 API 中查找限时动态提及。Meta 会以 messages 上的私信形式发送这些提及。
使用 EasyCoexistence 完成这些操作

send_social_dm 可在 24 小时窗口期内回复用户,回复内容可来自 Claude、ChatGPT 或您自己的代码。每个连接每月 US$ 9 起,连接越多价格越低,最低降至 US$ 0.75;前 3 天免费试用。

常见问题

Instagram 限时动态提及事件是否包含文本?

Meta 的示例中没有。限时动态提及带有 type 为 story_mention 的附件,内含限时动态的 CDN URL,因此只读取 message.text 的处理程序会收到空消息。

Instagram 限时动态回复中的 link_sticker_url 是什么?

它是用户所回复的限时动态上链接贴纸的 URL,位于 reply_to.story.link_sticker_url 中。Meta 于 2025 年 12 月 12 日新增该字段,建议用于按链接路由自动化流程。

用 GIF 或贴纸回复限时动态会触发 Webhook 吗?

不会。Meta 的《Instagram Messaging 指南》称,Webhook 不支持使用 GIF 或贴纸进行的限时动态回复。

私密账户会触发限时动态提及的 Webhook 吗?

只有当该私密账户关注了专业账户时才会。公开账户的提及会在发生时即时到达。

继续阅读

两分钟连接您的第一个渠道。

无需等待平台审核。连接 WhatsApp、Instagram、TikTok 或其他渠道,然后让您的 AI 发布、回复或生成报告,看它如何运作。

  • 免费试用 3 天
  • 随时取消
  • 仅使用官方 API
  • 全天候 24/7 监控

验证时间