Skip to content

A glossary story9 chapters · 6 min read

Instagram Messaging API

Meta's API for managing Instagram professional-account DMs, including story and comment replies, with its own messaging window and identity rules.

Also called: Instagram DM API · Instagram API messaging · Instagram Direct API · Messenger API for Instagram

Reviewed

Follow along

Open a story-reply webhook

7 / 7
{
  "object": "instagram",
  "entry": [
    {
      "id": "17841400000000000",
      "time": 1760860800000,
      "messaging": [
        {
          "sender": {
            "id": "5839210482910384"
          },
          "recipient": {
            "id": "17841400000000000"
          },
          "timestamp": 1760860799123,
          "message": {
            "mid": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQxNDAwMDAw",
            "text": "GOLD",
            "reply_to": {
              "story": {
                "url": "{CDN_URL_FOR_THE_STORY}",
                "id": "18043920000000000"
              }
            }
          }
        }
      ]
    }
  ]
}
The event Instagram sends when someone replies to a story. Step through the fields an inbox or bot reads: the account, the sender's IGSID, the window clock and the story being answered.

Field 7: entry.0.messaging.0.message.reply_to.story.id — Which story they answered. Keep it with the message so "GOLD" or "price?" makes sense later.

Chapter 1 · The scenario

Example: A Jaipur jewellery brand's festive story

A Jaipur jewellery brand posts a story: "Reply GOLD for this week's price list." Hundreds of replies arrive as webhooks carrying reply_to.story, and a bot answers each within seconds with the price list and three quick questions. Someone who comments "price?" under a reel gets a single private reply with the same list. Buyers who ask about a custom piece are handed to a designer, who answers the next afternoon with the HUMAN_AGENT tag. Because Instagram can't send order updates once the window has closed, the bot offers each buyer a WhatsApp opt-in for delivery updates.

— A Jaipur jewellery brand's festive story

Chapter 2 · What is the Instagram Messaging API?

The Instagram Messaging API is the part of Meta's Instagram Platform that lets a business handle direct messages for an Instagram professional (business or creator) account in its own software. It can be set up with Instagram Login, calling graph.instagram.com with an Instagram user access token, or with Facebook Login for an account linked to a Facebook Page, calling graph.facebook.com. Messages are sent with POST /{IG_ID}/messages, and incoming events arrive as webhooks with object: "instagram", each naming the user by an Instagram-scoped ID (IGSID).

Its rules come from the Messenger Platform rather than from WhatsApp. A business can only reply after the user writes, and only for 24 hours after the user's latest message; a reply sent with messaging_type: "MESSAGE_TAG" and tag: "HUMAN_AGENT" gives a person, not a bot, 7 days to answer. Events beyond plain DMs arrive the same way: a reply to the account's story carries message.reply_to.story, a story mention arrives as a story_mention attachment, and comments on posts come through the comments webhook field. A business may answer a comment with one private reply in DMs within 7 days, and ice breakers (up to four suggested questions) help people start a conversation.

Compared with the WhatsApp Business API, three differences shape any integration. There are no message templates, so once the window closes there is nothing to restart the conversation with. Users are known by an IGSID rather than a phone number, so linking an Instagram customer to a WhatsApp contact or CRM record needs your own identity step. And Instagram DMs are not part of WhatsApp's per-message pricing. Many teams route both channels into one Shared Team Inbox or Omnichannel Inbox, but the window clock, identity and allowed content are tracked per channel.

Key takeaways

  • The Instagram Messaging API lets a professional account send and receive DMs in its own software, with webhooks for incoming events.
  • Replies are allowed for 24 hours after the user's last message; a HUMAN_AGENT-tagged reply from a person gets 7 days.
  • Users are identified by an Instagram-scoped ID (IGSID), not a phone number, so they don't join up with WhatsApp contacts automatically.
  • A comment can receive one private reply within 7 days; anything more needs the user to answer first.
  • There are no message templates, so outside the window a business cannot start a conversation the way a WhatsApp template can.

Chapter 3 · In code

The Instagram Messaging API in code

curl -X POST "https://graph.instagram.com/v26.0/{IG_ID}/messages" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": { "id": "{IGSID}" },
    "message": { "text": "Here is the price list for this week: https://example.com/gold" }
  }'

Instagram Login path. With Facebook Login the same body goes to graph.facebook.com with a Page access token.

Chapter 4 · How it unfolds

How does the Instagram Messaging API work?

  1. Connect a professional account

    Use a business or creator account and authorise your app with Instagram Login (instagram_business_basic, instagram_business_manage_messages), or through a linked Facebook Page with Facebook Login.

  2. Subscribe to webhooks

    Subscribe the app to fields such as messages, messaging_postbacks, messaging_seen, messaging_reactions and comments, and verify the endpoint as for any Meta Webhook.

  3. Receive the DM

    Each event carries the sender's IGSID, your account ID, a timestamp and a message object with its mid; story replies and mentions add a story reference or attachment.

  4. Reply inside the window

    POST to /{IG_ID}/messages with recipient.id set to the IGSID within 24 hours of the user's last message. Text is limited to 1,000 bytes.

  5. Escalate or follow up within the rules

    A human agent may reply with the HUMAN_AGENT tag for up to 7 days. A comment gets one private reply through recipient.comment_id within 7 days, and more only after the user responds.

Chapter 5 · Where it goes wrong

Common mistakes with the Instagram Messaging API

  • Expecting WhatsApp-style templates

    Instagram has no approved templates for starting conversations. If you need to reach customers later, for order updates or reminders, collect an opt-in for WhatsApp or another channel while the window is open.

  • Automating under the human agent tag

    HUMAN_AGENT is for replies written by a person. Using it for bot or bulk messages breaks Meta's policy and can cost you the permission.

  • Treating the IGSID as a customer ID

    An IGSID identifies the user to your Instagram account, not across channels. Store it per channel and link it to a CRM record only when the customer shares a phone number or email.

  • Sending a second private reply

    A comment allows exactly one private reply, within 7 days. Make it count: a link or a question that invites a response opens the normal 24-hour window.

  • Losing the story context

    A story reply that just says "price?" means nothing without reply_to.story. Store the story ID with the message so agents and bots see what the user reacted to; story media links may not last.

Chapter 6 · The facts

The Instagram Messaging API: key facts and limits

AccountsInstagram professional accounts (business or creator)
Send endpointPOST /{IG_ID}/messages on graph.instagram.com or graph.facebook.com
Standard window24 hours after the user's last message
Human agent tagHUMAN_AGENT: 7 days, human-written replies only
Private repliesOne per comment, within 7 days of the comment
Ice breakersUp to 4 questions
User identifierInstagram-scoped ID (IGSID)
Text limit1,000 bytes (UTF-8)

Chapter 7 · Why it matters

Why does the Instagram Messaging API matter?

For brands whose customers find them on Instagram, DMs are where product questions, story replies and comment queries land, often in volumes no one can answer from a phone. Bringing them into a shared inbox or bot through the API means faster replies inside the 24-hour window, comment-to-DM flows for campaigns, and one view of the customer next to WhatsApp. Misreading its rules (expecting templates, ignoring the window, automating replies under the human agent tag) leads to failed sends and policy trouble.

Chapter 8 · Instagram Messaging API FAQs

Instagram Messaging API FAQs

Can I send Instagram DMs to users who haven't messaged my account?+
No. The API only lets you reply after the user starts a conversation, for 24 hours after their last message. The exceptions are one private reply to a comment within 7 days, and HUMAN_AGENT-tagged replies written by a person within 7 days.
Does the Instagram Messaging API need a Facebook Page?+
Not any more. With Instagram Login a professional account uses the API directly through graph.instagram.com. The Facebook Login path, which works through a linked Page, is still available for businesses that already use it.
How is the Instagram Messaging API different from the WhatsApp Business API?+
Instagram is reply-only within a 24-hour window and identifies users by IGSID. WhatsApp lets businesses start conversations with approved templates, identifies users by phone number (and now business-scoped user IDs) and charges per delivered message by category.
How long can a human agent reply on Instagram?+
Up to 7 days after the user's last message, if a person writes the reply and it is sent with the HUMAN_AGENT tag. Automated messages must stay inside the standard 24-hour window.

Chapter 9 · What good teams do

Best practices for the Instagram Messaging API

  • Show the remaining window time on every Instagram conversation in the inbox.
  • Use ice breakers for the three or four questions customers actually ask.
  • Answer comments both ways: a short public reply plus one private reply with the details.
  • Offer a WhatsApp opt-in in the chat when customers want updates after the window closes.

See InfiQ pricing

From definition to your first message

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms