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 端点,并使用该账户的密钥签名。
ig.me ref 参数最多可容纳的字符数,且仅限字母、数字、连字符、下划线和等号。
ig.me 链接的引荐类型;点击直达广告的引荐同样使用此类型,但 source 为 ADS。
现有会话中收到引荐后,应用可以回复的时间,该引荐会重置标准窗口。
用户点击 Click-to-Direct 广告后发出的首条消息,所开启窗口的最长时长。
根据 Meta 的 ig.me 指南,不支持 ig.me 链接的场景。
messaging_referral 何时触发?
当此前已与专业账户有会话的用户,打开带有 ref 参数的 ig.me 链接时触发。Instagram 会打开已有会话,Meta 会单独发送引荐,不附带消息。引荐到达的位置取决于会话情况以及用户的操作:
引荐通知是什么样的?
这是一个消息事件,其中 referral 对象与 sender、recipient 和 timestamp 并列,不包含 message 或 postback。Meta 的 ig.me 指南给出了引荐的取值,它们与其他 Instagram 消息事件位于同一外层结构中:
{
"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。
"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 应用中打开。
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 监控
验证时间