Instagram messaging_referral webhook: ig.me links and ad referrals
Instagram's messaging_referral webhook field notifies an app when a person who already has a conversation with a professional account opens an ig.me link carrying a ref parameter. The event holds a top-level referral object: ref, the parameter's value; source, SHORTLINKS; and type, OPEN_THREAD. A ref on a new conversation arrives inside the messages or messaging_postbacks event instead.
easyCoexistence subscribes each connected Instagram account to comments, messages and mentions, so a ref on a new thread's first message and a Click-to-Direct ad's referral reach your HTTPS endpoint inside the forwarded DM, signed with that account's secret.
Most characters an ig.me ref parameter can hold, using letters, digits, hyphens, underscores and equal signs only.
Referral type for ig.me links; a Click-to-Direct ad's referral uses it too, with source ADS.
Time the app has to reply after a referral in an existing conversation, which resets the standard window.
How long the window can last from a first message sent after clicking a Click-to-Direct ad.
Where ig.me links are not supported, according to Meta's ig.me guide.
When does messaging_referral fire?
When a person who already has a conversation with the professional account opens an ig.me link that carries a ref parameter. Instagram opens the existing thread and Meta sends the referral on its own, with no message. Where a ref arrives depends on the thread and on what the person does:
What does a referral notification look like?
A messaging event whose referral object sits beside sender, recipient and timestamp, with no message or postback around it. Meta's ig.me guide gives the referral's values, inside the same envelope as the other Instagram messaging events:
{
"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"
}
}
]
}
]
}What does each field mean?
The fields Meta documents for an ig.me referral, from the outside in:
- sender.id: the Instagram-scoped ID of the person who opened the link. recipient.id and entry[].id: the professional account.
- referral.ref: the value of the link's ref parameter, as the link carried it.
- referral.source: SHORTLINKS in Meta's ig.me samples. One table in its Instagram Messaging guide spells it SHORTLINK, and its examples page shows a placeholder.
- referral.type:
OPEN_THREAD, which Meta uses for ig.me referrals. - timestamp: when the event was triggered, in milliseconds in Meta's samples.
How do you build an ig.me link with a ref?
As https://ig.me/<USERNAME>?ref=<VALUE>, where USERNAME is the professional account's handle, in Meta's Instagram Login guide; its Instagram Messaging guide writes https://ig.me/m/<USERNAME>. The ref can run to 2,083 characters of letters, digits, hyphens, underscores and equal signs. Meta suggests refs to track channels, tie a person to a session in another app or point them to specific content, and recommends ice breakers, each with its own ref, for new conversations.
Where do ad referrals arrive?
On messages. A person who clicks an ad that opens Instagram Direct and sends a message produces a messages event whose message.referral holds the ad's ref if one was set, ad_id, source ADS, type OPEN_THREAD and ads_context_data with the ad's title and the photo_url or video_url clicked. Meta's Instagram pages document messaging_referral for ig.me links only.
"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>"
}
}
}Does a referral open the messaging window?
Yes, in an existing thread: Meta's ig.me guide says the referral resets the 24-hour standard messaging window, so the app can reply within 24 hours of the event. A first message sent after clicking a Click-to-Direct ad can open a window of up to 7 days from that message. Reply with POST /<IG_ID>/messages and recipient.id set to the event's sender.id.
Does easyCoexistence forward referrals?
The ones that ride on messages. Each connected account is subscribed to comments, messages and mentions, so a ref on a new thread's first message and a Click-to-Direct ad's referral reach your endpoint inside the forwarded DM, as message.referral. messaging_referral, for existing threads, and messaging_postbacks, for ice breaker taps, are separate fields that Meta delivers to an app subscribed to them.
Common mistakes
- Waiting for messaging_referral on a new conversation. There the ref arrives in messages or messaging_postbacks, depending on whether the person typed or tapped an ice breaker.
- Putting other characters in ref. Meta accepts letters, digits, hyphens, underscores and equal signs, up to 2,083 characters.
- Matching source against one exact string. Meta's samples show SHORTLINKS for ig.me and ADS for ads, but one of its tables reads SHORTLINK, so branch on where the referral sits and on ref.
- Testing links on Instagram Web. Meta does not support ig.me links there, so open them in the Instagram app.
send_social_dm replies inside the 24-hour window. US$ 9 to US$ 0.75 per connection per month, falling as you add connections, with the first 3 days free.
easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.
Frequently asked questions
What does referral.source contain in an Instagram referral?
SHORTLINKS in Meta's ig.me samples and ADS for a Click-to-Direct ad, though one table in Meta's Instagram Messaging guide spells it SHORTLINK. Branch on where the referral sits and on ref rather than on one exact string.
How long can an ig.me ref parameter be?
Up to 2,083 characters, using only letters, digits, hyphens, underscores and equal signs.
Where does an ig.me ref arrive on a new Instagram conversation?
On messages when the person types a first message, or on messaging_postbacks when they tap an ice breaker. messaging_referral covers existing threads only.
Do ig.me links work on Instagram Web?
No. Meta's ig.me guide says they are not supported on Instagram Web.
Keep reading
Connect your first channel in two minutes.
No platform reviews to wait for. Connect WhatsApp, Instagram, TikTok or another channel, then ask your AI to post, reply or report, and watch it work.
- 3 days free
- Cancel any time
- Official APIs only
- Monitored 24/7
Verified on