Instagram messaging_postbacks webhook: ice breakers and buttons
Instagram's messaging_postbacks webhook field notifies an app when a person taps an ice breaker question, a postback button in a template, or a persistent menu item in a conversation with a professional account. The event's postback object carries title, the text the person tapped; payload, the string the app set for that option; and mid, the message ID, from Graph API v11.0.
easyCoexistence subscribes each connected Instagram account to comments, messages and mentions and forwards those events, quick reply taps included, to your HTTPS endpoint as they arrive, signed with that account's secret and with no copy kept.
Most ice breaker questions an account can set through Meta's Ice Breaker API.
Graph API version from which postback events include mid; the field itself needs v8.0 or later.
Most buttons in a button template message, each a postback or web_url button.
Time to respond after a person taps a persistent menu item, which opens the standard messaging window.
Most quick replies one message offers; a tapped quick reply arrives on messages, not messaging_postbacks.
When does messaging_postbacks fire?
When a person taps one of the account's structured options in a conversation, once the app and the account are subscribed to the field. Meta's guides list these sources:
- An ice breaker question, one of up to 4 the account offers when a conversation starts. Not available on desktop.
- A postback button in a button template, up to 3 per message, or in a generic template, up to 3 per element.
- A postback item in the account's persistent menu.
- An ice breaker tapped in a new thread opened from an ig.me link with a ref parameter: the postback then carries referral as well.
- A self-messaging test, where the account taps its own button: the event adds
is_selfset to true.
What does a postback notification look like?
A messaging event with a postback object where a DM would have its message. Meta's example for Instagram Login carries mid, title and payload, and its ice breaker guide shows the same object without mid. A notification looks like this:
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"postback": {
"mid": "<MESSAGE_ID>",
"title": "<ICE_BREAKER_QUESTION_OR_BUTTON_TITLE>",
"payload": "<PAYLOAD_SET_FOR_THE_OPTION>"
}
}
]
}
]
}What does each field mean?
The fields Meta documents for a postback, from the outside in:
- sender.id: the Instagram-scoped ID of the person who tapped, the ID to reply to. recipient.id and entry[].id: the professional account.
- timestamp: when the person tapped, according to Meta's ice breaker guide.
- postback.title: the ice breaker question or the button title the person saw.
- postback.payload: the string set for that option when it was created, chosen by the app.
- postback.mid: the ID of the message the tap sent to the account, from Graph API v11.0.
- postback.referral: ref, source and type, when the thread was opened from an ig.me link with a ref parameter.
is_self: set to true, beside postback, when the account taps its own button in a self-messaging test.
How are ice breakers set?
With POST /<IG_ID>/messenger_profile on graph.instagram.com: platform set to instagram and an ice_breakers array whose call_to_actions hold up to 4 question and payload pairs, with a locale for each translated set. GET /me/messenger_profile?fields=ice_breakers lists them, and a DELETE with fields set to ice_breakers removes them. The payload chosen here is what messaging_postbacks returns when the question is tapped.
POST https://graph.instagram.com/<IG_ID>/messenger_profile?access_token=<INSTAGRAM_USER_ACCESS_TOKEN>
Content-Type: application/json
{
"platform": "instagram",
"ice_breakers": [
{
"call_to_actions": [
{ "question": "<QUESTION_1>", "payload": "<PAYLOAD_1>" },
{ "question": "<QUESTION_2>", "payload": "<PAYLOAD_2>" }
]
}
]
}How are postback buttons sent?
Inside a message the account sends with POST /<IG_ID>/messages. A button template carries text of up to 640 characters and 1 to 3 buttons; a generic template carries up to 10 elements, each with up to 3 buttons. A button of type postback returns its payload on messaging_postbacks when tapped, while a web_url button opens a page in the in-app browser instead. The persistent menu, set on messenger_profile, takes the same two types.
Do quick replies use messaging_postbacks?
No: they arrive on messages. A tapped quick reply posts its title into the conversation as a message, and the messages event carries text set to that title and quick_reply.payload set to the option's payload. A message can offer up to 13 quick replies of up to 20 characters each, plain text only. Meta's Instagram Messaging guide also lists ice breaker and generic template selections among what messages reports, without a sample payload.
Does a tap open the messaging window?
For the persistent menu, Meta says so: a tap on a menu item opens the standard messaging window, and the account has 24 hours to respond. Reply with POST /<IG_ID>/messages and recipient.id set to the postback's sender.id. The account's reply comes back on messages as an echo, with is_echo set to true.
Does easyCoexistence forward postbacks?
Only quick reply taps. They arrive on messages, which easyCoexistence's app and each connected account are subscribed to, so they reach your endpoint with quick_reply.payload. Ice breaker, button and menu taps arrive on messaging_postbacks, which easyCoexistence does not subscribe to, so they are not forwarded.
Common mistakes
- Waiting for quick replies on messaging_postbacks. A quick reply arrives on messages, with quick_reply.payload beside the text of the option tapped.
- Routing on postback.title. The title is what the person saw and can differ by locale; route on payload, which the app sets.
- Expecting mid on an older API version. Meta includes postback.mid from Graph API v11.0 only.
- Setting more than 4 ice breakers, or testing them on desktop. Meta's Ice Breaker API takes up to 4 questions, and the feature is not available on desktop.
send_social_dm answers the person 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
Which webhook field reports Instagram ice breaker taps?
messaging_postbacks. The postback object carries the question as title and the payload set for it, plus mid from Graph API v11.0.
How many ice breakers can an Instagram account have?
Up to 4 questions, set with POST /<IG_ID>/messenger_profile and platform set to instagram, optionally per locale.
How do I reply to an Instagram postback?
With POST /<IG_ID>/messages and recipient.id set to the postback's sender.id, the Instagram-scoped ID of the person who tapped. After a persistent menu tap, Meta gives the account 24 hours to respond.
Should I route Instagram postbacks on title or payload?
On payload, the string the app set for the option. title is the text the person saw, which can differ by locale.
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