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

Instagram messaging_referral Webhook:ig.me 链接与广告引荐

Instagram 的 messaging_referral 字段会在用户打开带有 ref 参数的 ig.me 链接时通知应用,前提是该用户此前已与专业账户有会话。事件包含顶层 referral 对象:ref 为该参数的值;source 为 SHORTLINKS;type 为 OPEN_THREAD。新会话中的 ref 则会出现在 messages 或 messaging_postbacks 事件内。

easyCoexistence 会为每个已连接的 Instagram 账户订阅评论、消息和提及,因此新会话首条消息中的 ref,以及 Click-to-Direct 广告的引荐,会以 message.referral 的形式,在转发的私信中到达您的 HTTPS 端点,并使用该账户的密钥签名。

2,083

ig.me ref 参数最多可容纳的字符数,且仅限字母、数字、连字符、下划线和等号。

OPEN_THREAD

ig.me 链接的引荐类型;点击直达广告的引荐同样使用此类型,但 source 为 ADS。

24 hours

现有会话中收到引荐后,应用可以回复的时间,该引荐会重置标准窗口。

7 days

用户点击 Click-to-Direct 广告后发出的首条消息,所开启窗口的最长时长。

Instagram Web

根据 Meta 的 ig.me 指南,不支持 ig.me 链接的场景。

messaging_referral 何时触发?

当此前已与专业账户有会话的用户,打开带有 ref 参数的 ig.me 链接时触发。Instagram 会打开已有会话,Meta 会单独发送引荐,不附带消息。引荐到达的位置取决于会话情况以及用户的操作:

Existing threadmessaging_referral: a referral object beside sender, with no message.
New thread, ice breaker tappedmessaging_postbacks: postback.referral beside title and payload.
New thread, message typedmessages: message.referral beside mid.
Click-to-Direct admessages: message.referral with source ADS, ad_id and ads_context_data.

引荐通知是什么样的?

这是一个消息事件,其中 referral 对象与 sender、recipient 和 timestamp 并列,不包含 message 或 postback。Meta 的 ig.me 指南给出了引荐的取值,它们与其他 Instagram 消息事件位于同一外层结构中:

A messaging_referral notification
{
  "object": "instagram",
  "entry": [
    {
      "id": "<IG_ID>",
      "time": 1793448000512,
      "messaging": [
        {
          "sender": { "id": "<IGSID>" },
          "recipient": { "id": "<IG_ID>" },
          "timestamp": 1793447999874,
          "referral": {
            "ref": "<REF_PARAMETER_VALUE>",
            "source": "SHORTLINKS",
            "type": "OPEN_THREAD"
          }
        }
      ]
    }
  ]
}

各字段是什么意思?

以下是 Meta 为 ig.me 引荐所记录的字段,由外到内排列:

  • sender.id:打开链接的用户的 Instagram 范围 ID。recipient.id 和 entry[].id:专业账户。
  • referral.ref:链接中 ref 参数的值,与链接携带的内容一致。
  • referral.source:Meta 的 ig.me 示例中为 SHORTLINKS。其 Instagram Messaging 指南的一张表将其拼写为 SHORTLINK,其示例页面则使用占位符。
  • referral.type:OPEN_THREAD,Meta 用于 ig.me 引荐。
  • timestamp:事件触发的时间,Meta 示例中以毫秒计。

如何构建带 ref 的 ig.me 链接?

格式为 https://ig.me/<USERNAME>?ref=<VALUE>,其中 USERNAME 是专业账户的用户名,见 Meta 的 Instagram Login 指南;其 Instagram Messaging 指南则写作 https://ig.me/m/<USERNAME>。ref 最长可达 2,083 个字符,仅限字母、数字、连字符、下划线和等号。Meta 建议用 ref 追踪渠道、将用户与另一应用中的会话关联,或指向特定内容;并建议为新会话中的破冰问题(ice breaker)各设置独立的 ref。

广告引荐在哪里到达?

在消息中。点击打开 Instagram 私信并发送消息的广告的用户,会产生一个 messages 事件,其中 message.referral 包含广告的 ref(如已设置)、ad_id、source 为 ADS、type 为 OPEN_THREAD,以及 ads_context_data,其中有广告标题和所点击的 photo_url 或 video_url。Meta 的 Instagram 页面仅记载了 ig.me 链接的 messaging_referral。

A Click-to-Direct ad referral, inside messages
"message": {
  "mid": "<MESSAGE_ID>",
  "referral": {
    "ref": "<AD_REF_IF_SET>",
    "ad_id": "<AD_ID>",
    "source": "ADS",
    "type": "OPEN_THREAD",
    "ads_context_data": {
      "ad_title": "<AD_TITLE>",
      "photo_url": "<IMAGE_URL_CLICKED>",
      "video_url": "<THUMBNAIL_URL_FOR_THE_AD_VIDEO>"
    }
  }
}

引荐会开启消息窗口吗?

在现有会话中会。Meta 的 ig.me 指南称,引荐会重置 24 小时标准消息窗口,因此应用可在事件发生后 24 小时内回复。点击 Click-to-Direct 广告后发送的首条消息,最长可开启 7 天的窗口,自该消息起算。使用 POST /<IG_ID>/messages 回复,并将 recipient.id 设为事件的 sender.id。

easyCoexistence 会转发引荐吗?

会转发随消息到达的引荐。每个已连接账户均订阅了评论、消息和提及,因此新会话首条消息中的 ref,以及 Click-to-Direct 广告的引荐,会以 message.referral 的形式,在转发的私信中到达您的端点。messaging_referral(用于现有会话)和 messaging_postbacks(用于破冰问题点击)是独立字段,由 Meta 投递给订阅了它们的应用。

常见错误

  • 在新会话中等待 messaging_referral。新会话中的 ref 会出现在 messages 或 messaging_postbacks 中,取决于用户是输入还是点击了破冰问题。
  • 在 ref 中使用其他字符。Meta 只接受字母、数字、连字符、下划线和等号,最长 2,083 个字符。
  • 把 source 与某个精确字符串做匹配。Meta 的示例显示 ig.me 为 SHORTLINKS、广告为 ADS,但其中一张表写作 SHORTLINK,因此应根据引荐所在位置和 ref 进行分支判断。
  • 在 Instagram 网页版上测试链接。Meta 不支持网页版的 ig.me 链接,请在 Instagram 应用中打开。
使用 EasyCoexistence 完成这些操作

send_social_dm 可在 24 小时窗口内回复。每个连接每月 US$ 9 至 US$ 0.75,连接越多单价越低,前 3 天免费。

常见问题

referral.source 在 Instagram 引荐中包含什么?

Meta 的 ig.me 示例中为 SHORTLINKS,点击直达广告则为 ADS,不过 Meta 的 Instagram Messaging 指南中有一张表将其拼写为 SHORTLINK。请根据引荐所在位置和 ref 进行判断,而不是依赖某个精确字符串。

ig.me 的 ref 参数最长可以是多少?

最长 2,083 个字符,且仅可使用字母、数字、连字符、下划线和等号。

ig.me 的 ref 在 Instagram 新会话中何时到达?

当用户输入首条消息时在 messages 中到达,当用户点击破冰问题时在 messaging_postbacks 中到达。messaging_referral 仅涵盖现有会话。

ig.me 链接能否在 Instagram 网页版上使用?

不能。Meta 的 ig.me 指南称,网页版不支持这些链接。

继续阅读

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

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

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

验证时间