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

Instagram 消息 Webhook:私信负载、回显与字段

Instagram 消息 Webhook 字段会实时推送专业账户的私信:文本、附件、分享内容、Story 回复和提及、内联回复以及已删除的消息。每个事件位于 messaging 数组中,包含发送者的 Instagram 范围 ID、接收者、时间戳和 message 对象;账户自己发出的消息也会通过同一字段返回,并将 is_echo 设为 true。

easyCoexistence 为每个已连接的 Instagram 账户订阅消息,并将其私信(包括回显)在到达时转发到您的 HTTPS 端点,使用该账户的密钥签名;转发过程不保留副本,私信默认不予存储。

is_echo

在消息事件上设为 true,表示该消息由账户本人发出。

24 hours

大多数用户操作适用的标准消息窗口期,期间应用可以回复该用户。

ig_post

分享帖子的附件类型;旧的 share 类型仅在 2026 年 2 月 1 日前支持。

story_mention

当有人在 Story 中提及该账户时,Meta 发送的私信事件所使用的附件类型。

2534041

错误代码 200 下的子代码,表示账户所有者已关闭 Instagram 私信访问。

messages 字段何时触发?

当用户向专业账户发送私信,以及账户自己发送私信时触发。Meta 的示例和参考文档列出了以下情况,每种都是带有 message 对象的 messaging 事件:

  • 文本,以及作为附件的媒体:图片、视频、音频和文件。
  • 分享的帖子或 Reel,以 ig_post、ig_reel 或 reel 附件形式出现。
  • 对账户 Story 的回复带有 reply_to.story;提及该账户的 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。对账户 Story 的回复示例如下:

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 回复时为 story,包含 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 或 text。

回显如何运作?

账户发送消息时,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,它仅对该用户和该账户有效。向 POST /<IG_ID>/messages 发送请求,并将 recipient.id 设为该 ID,即可发送回复。事件中不包含姓名或用户名;使用 GET /<IGSID> 并指定 name 和 username 等字段可以获取它们,因为曾向账户发消息的用户已授予该查询所需的同意。

一条消息如何开启 24 小时窗口?

应用只能在用户先向账户发消息之后,并且只能在其操作所开启的标准消息窗口期内发消息。大多数操作的窗口期为 24 小时;对于点击 Click-to-Direct 广告后发送的首条消息,窗口期最长为 7 天。用户的新消息会开启新的窗口,因此应跟踪其最新时间戳;回显是账户自己的消息,不会延长任何窗口。由人工撰写的回复,可使用 Meta 单独的 7 天 Human Agent 窗口,并标记为 human_agent。

消息事件不包含哪些内容?

根据 Meta 的消息参考文档,处理程序可能查找的以下几项内容并不存在:

  • 用户的姓名或用户名:只有 Instagram 范围 ID,可通过 GET /<IGSID> 解析。
  • 阅后即焚媒体:以不含 URL 的临时附件形式到达。
  • 确切的轮播图片:对轮播帖子中某张图片的表情回应或转发,会报告第一张图片。
  • 表情回应、编辑和已读回执,它们位于各自独立的字段中。
  • 已读标记:通过 Webhook 送达的消息,在发送回复之前,在 Instagram 收件箱中保持未读。

Meta 还列出了哪些其他消息字段?

Meta 在 Instagram Login 下的字段列表和示例中,还列出了以下字段,每个字段都是独立的消息事件。easyCoexistence 仅为每个账户订阅消息、评论和提及,因此以下字段都不属于其转发的内容:

  • 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 应用中进入 设置、消息和 Story 回复、消息控制、已连接的工具。关闭时,发送会以错误代码 200、子代码 2534041 失败。应用还需要 instagram_business_basic 和 instagram_business_manage_messages 权限;若要为其未拥有或管理的账户提供服务,还需要高级访问权限。

easyCoexistence 如何转发私信?

与评论相同:Meta 为账户推送的每个 entry 都会以 POST 方式发送到您的 HTTPS 端点,封装在包含 platform、account_id、external_id 和 entry 的信封中,使用账户的密钥在 X-EC-Signature 中签名,只发送一次,不保留副本。回显会与其他内容一并转发,因此回复前请检查 is_echo。如需回复,请在 24 小时窗口内调用 send_social_dm,将 account_id 和事件的 sender.id 作为 recipient_id 传入。以私信为触发条件的自动化会基于相同事件运行。

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 的事件是账户自己的消息,回复它会使账户陷入与自己的循环。
  • 假设消息一定包含文本。附件、分享内容、Story 提及和已删除的消息到达时都没有 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 订阅消息,以及应用是否处于 Live 模式并为其未拥有的账户启用了高级访问权限。

easyCoexistence 会转发 Instagram 消息表情回应吗?

不会。表情回应位于 message_reactions 上,而 easyCoexistence 订阅的是账户的消息、评论和提及。

继续阅读

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

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

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

验证时间