Instagram Messenger

Message customers on Instagram: text, media, buttons, carousels and quick replies, reactions, private replies to comments, and profile lookups. Covers the Instagram access token, the 24-hour messaging window, and what receiving messages needs.

Open in Claude

Browse 9 Instagram Messenger actions instagram-messenger

On this page

Connecting Instagram Messenger Sending a message Rich messages Typing indicator and read receipt Reading the response Get User Profile Replying to a comment privately Reacting to a message Limits Receiving messages Your first call Step Name Step Reference Execution Settings Caching Locking

Connecting Instagram Messenger

Every action needs an Instagram Messenger connection. The connector uses the Instagram API with Instagram Login, so it works with a professional (Business or Creator) Instagram account and does not need a linked Facebook Page. In the Meta developer dashboard, add the Instagram product, add your account as a tester, and generate an Instagram User access token with the instagram_business_basic and instagram_business_manage_messages permissions. The connection holds:

Instagram Access Token: kept encrypted and sent in the Authorization header, never in a URL.
Instagram Account ID (optional): messages are sent from /<account-id>/messages. When empty, the token's own account is used.
Graph API Version (optional): defaults to v25.0.

Test the connection from the connections page. It calls /me on graph.instagram.com with the token and reports Meta's error message if the token is rejected.

Sending a message

Every send action needs the recipient's Instagram-Scoped User ID. You get it from the webhook Meta delivers when someone messages you, at entry[0].messaging[0].sender.id. Every send action also has:

Messaging Type: RESPONSE replies within 24 hours of the user's last message, UPDATE is proactive, and MESSAGE_TAG sends outside the window and needs a Tag. Unlike Messenger, nothing is sent unless you set it.
Tag: for example HUMAN_AGENT, used with MESSAGE_TAG.
Additional Data (JSON): a JSON object merged into the request body as-is, for any field the form doesn't expose. Invalid JSON fails the step before the request is sent.

The 24-hour window opens each time the user messages you. Outside it, Meta rejects the send (for Messenger, error code 1545041) unless you use a message tag Meta allows for your use case.

Rich messages

Buttons, carousel cards and quick replies are entered as JSON arrays, in the same shape as Meta's Send API:

Send Button Message: Text plus Buttons, 1 to 3 items, for example [{"type":"web_url","title":"View order","url":"https://shop.example/orders/1"},{"type":"postback","title":"Reorder","payload":"REORDER_1"}]. A tapped postback button arrives in your webhook with its payload.
Send Carousel: Cards, 1 to 10 items, each {"title","subtitle","image_url","default_action","buttons"}.
Send Quick Replies: Text plus Quick Replies, 1 to 13 items such as [{"title":"Yes","payload":"YES"},{"title":"No","payload":"NO"}]. content_type defaults to text.
Send Media Message: Media Type (image, audio, video or file) and a publicly reachable HTTPS Media URL.

A list with too many items, or a value that isn't valid JSON, fails the step with a message naming the field.

Typing indicator and read receipt

Send Typing Indicator or Read Receipt takes an Action: typing_on or mark_seen. Use it before a slow reply so the user sees you're working on it.

Reading the response

Every action's result is at {{<stepReference>.response...}} (see Step Reference): response.status, response.statusText, response.headers and the Graph API body at response.data. A successful send returns { "recipient_id": "...", "message_id": "..." }. A step named "Send Reply" (reference sendReply) resolves the message ID at {{sendReply.response.data.message_id}}.

Graph API errors come back with their real status and body, and are not wrapped: {{sendReply.response.data.error.message}} and {{sendReply.response.data.error.code}}. Common codes are 10 (missing permission), 100 (invalid parameter, often a wrong recipient ID), 190 (expired token) and 613 (rate limited). Branch on {{sendReply.response.status}}, or turn on Continue On Error to handle the failure in a later step.

Get User Profile

Get User Profile reads a sender's profile by ID. Fields is a comma-separated list and defaults to name,username,profile_pic. Other fields Meta allows for Instagram users, such as follower_count and is_user_follow_business, can be added to the list. The result is at {{<stepReference>.response.data.<field>}}.

Replying to a comment privately

Send Private Reply to Comment sends a direct message to the person who commented on your post, reel or live video. Give it the Comment ID from the comments webhook and the Text. Meta allows one private reply per comment, within 7 days of the comment, and the person's reply opens the normal 24-hour window.

Reacting to a message

React to Message takes the Instagram-Scoped User ID, the Message ID from the messages webhook, an Action of react or unreact, and a Reaction such as love or an emoji character. Reaction is required when reacting.

Limits

Message text is limited to 1000 bytes, images to 8 MB, and audio, video and PDFs to 25 MB.

Receiving messages

This connector sends messages and reads profiles. Incoming messages, postbacks and comments and reactions reach you as webhook calls from Meta to a URL you register in the Meta developer dashboard. Meta first verifies that URL with a GET carrying hub.mode, hub.verify_token and hub.challenge, and expects the hub.challenge value echoed back, and it signs each delivery in the X-Hub-Signature-256 header. The connector does not handle that handshake or signature check, so a webhook trigger on its own will not pass Meta's URL verification today. Until that is built in, the endpoint that Meta calls has to answer the verification request itself.

Your first call

Create an Instagram Messenger connection with your access token.
Send a direct message to your professional account from a tester account, and copy the sender ID from the webhook payload.
Add a Send Text Message step named "Send Reply", with that ID as Instagram-Scoped User ID and any Text.
Run it and read {{sendReply.response.data.message_id}}.

Also applies here

Step Name

What it's for

Every step in a workflow gets a name — either one you set or a default based on the connector and action (e.g. "Get Order Details", "Send Welcome Email"). It's shown throughout the UI and in your execution history, and it's also the source for the step's Reference — a camelCase identifier auto-generated from the name (e.g. "Get Order Details" → getOrderDetails) — which is what you actually use in {{...}} expressions to read this step's output from later steps. See Step Reference.

Rules

Must be at least 2 characters, and 50 characters or fewer.
Must be unique within the workflow — reusing a name that's already taken will be rejected, with a suggested alternative (e.g. "Get Order Details 2").
Can't be empty.

Tips

Prefer a descriptive, human-readable name over a generic one — "Get Order Details" is easier to work with later than "HTTP Request 2", especially once a workflow has a dozen steps.
Renaming a step updates every reference to it elsewhere in the workflow automatically.

Step Reference

Syntax

Any input field can reference earlier data using {{expression}}. The expression is evaluated as JSONata — so simple dot-paths and more advanced queries (filters, functions) both work.

Referencing a step's output

Use the step's Reference — a camelCase identifier auto-generated from its Name (e.g. "Get Order Details" → getOrderDetails), shown read-only wherever the step's fields are configured — followed by the field path. Elsewhere in these docs this general pattern is written as {{<stepReference>.field.path}}:

text

{{getOrderDetails.response.data.id}}
{{getOrderDetails.response.status}}

The raw display name won't work here even though it's what you see in the UI — {{Get Order Details.response.data.id}} isn't valid, since a bare name containing spaces isn't a single JSONata identifier. Always use the camelCase Reference.

You can also reference steps by position instead of by reference:

text

{{steps[0].response.data.id}}

Referencing trigger data

text

{{trigger.headers.authorization}}
{{trigger.body.customerId}}
{{trigger.query.page}}
{{trigger.params.orderId}}
{{trigger.method}}
{{trigger.path}}

Referencing workflow variables

text

{{variables.myVariable}}

See Variables for the full list of variable types and more examples, including connection-type variables.

Referencing runtime variables

A separate, mutable namespace written by the Variable connector while a run is in progress — not the same as the workflow-level variables above:

text

{{runtimeVariables.myVariable}}

Notes

If an expression can't be resolved (a typo in a step name, a field that doesn't exist), it resolves to an empty string rather than failing the workflow — check your execution history if a value comes through blank.
Object values are automatically JSON-stringified when interpolated into a string field.

Execution Settings

Fire-and-forget

When enabled, the workflow doesn't wait for this step to complete before moving to the next one. Use it for steps whose result nothing downstream depends on — logging, analytics, notifications — so they don't add latency to the steps that matter.

Continue on error

When enabled, a failure in this step doesn't stop the workflow — execution continues to the next step. The failure is still recorded in the execution history; this just controls whether it's fatal.

Combine the two for steps that are genuinely optional to the outcome: fire-and-forget so they don't add latency, continue-on-error so a failure in them (e.g. an analytics endpoint being briefly down) doesn't take down an otherwise-successful workflow run.

Caching

What it does

When enabled, a step's result is cached for a configurable TTL (time-to-live, in seconds). If the step runs again with the same effective cache key before the TTL expires, the cached result is returned instead of re-running the step.

Configuring it

Enabled — turn caching on or off for this step.
TTL — how long (in seconds) a cached result stays valid.
Cache key template — an expression (supporting the same {{...}} step reference syntax used elsewhere) that determines what counts as "the same call". By default this is based on the step's resolved input; a custom template lets you cache more narrowly or broadly than that.

When to use it

Good candidates are steps that call something slow or rate-limited but return the same answer for the same input within a short window — a lookup against a rarely-changing external system, for example. Skip it for steps whose result must always be fresh (anything involving live inventory, pricing, or payment state).

Locking

What it does

When enabled, only one execution of this step (for a given lock key) can run at a time. If a second execution tries to run the same step while a lock is held, it waits until the lock is released or the hold period elapses.

Configuring it

Enabled — turn locking on or off for this step.
Lock key — an expression (supporting the same {{...}} step reference syntax used elsewhere) that determines what counts as "the same resource". By default the lock is scoped to the step itself; a custom key lets you lock per-customer, per-order, or any other identifier that needs serialized access.
Period — how long (in seconds) the lock is held before it's automatically released, in case an execution doesn't complete normally.

When to use it

Use it whenever concurrent executions could race on the same resource — e.g. two workflow runs both trying to update the same order's status at once. A lock key scoped to the order id ensures only one of them proceeds at a time.

Was this page helpful?

Last updated 15 October 2026