Set up Instagram

Back to messaging or digital channels Connect an Instagram professional account to your agent so people reach it through Instagram direct messages. You link the account to a Facebook Page and a Meta app, enter the account’s credentials in Artemis, then register a signed webhook that Meta verifies. The setup requires:

Instagram and Meta setup: prepare the account, Page, and app, and collect four values.
Artemis channel configuration: create the connection, then copy its Webhook URL.
Webhook configuration in Meta: verify the callback and subscribe the account.
Verify the connection with real messages, actions, and media.

After setup, a direct message to the professional account opens a session in Artemis, and the agent replies in the same Instagram conversation. Important considerations

The Instagram Account ID selects the connection: Artemis reads the account ID from entry.id in each signed webhook and matches it to the connection. The linked Page Access Token must message on behalf of that same account.
Three IDs look alike: Artemis routes on the Instagram Account ID. The Facebook Page ID and each customer’s sender ID appear nearby and never route.
Create the connection before you verify the webhook: Meta’s verification request carries the Verify Token but no account ID, so Artemis finds the connection by the stored token.
Development mode limits testing: Only app roles and Instagram testers reach the agent until you complete review and switch the app to Live.

Prerequisites

Confirm these before you start.

An Instagram Business or Creator account. Personal accounts can’t use this integration.
A Facebook Page linked to that account, where you can perform the messaging and moderate tasks.
A Meta developer account that can create a business app and reveal its App Secret.
Artemis project access with permission to open Deployments -> Channels, and a deployed agent in the environment you intend to bind.

How Artemis routes Instagram events

Meta sends every event to one generic URL, so Artemis identifies the connection from the signed payload.

Piece	Owner	What it does
Instagram Account ID	Meta	Routes inbound events by matching `entry.id`.
Page Access Token	Meta	Authorizes replies. Artemis sends them to `/{InstagramAccountId}/messages` with the token as a Bearer token.
App Secret	Meta	Verifies `X-Hub-Signature-256` on every inbound POST, over the exact raw body.
Verify Token	You	Answers Meta’s one-time verification challenge.
Webhook URL	Artemis	Receives events at `/api/v1/channels/instagram/webhook`, with no identifier suffix.

Artemis scopes each conversation to the account and the sender together, as an instagram:{accountId}:{senderId} session.

Instagram and Meta setup

Do this in Instagram and Meta before you open Artemis. Select Open Meta for Developers in the setup guide to jump straight there. Meta covers the same ground in its Instagram messaging get started guide.

Use a professional account

In the Instagram app, open your profile, then the menu, then Settings and privacy.
Switch the account type to Business or Creator.

Link the account to a Facebook Page

In the professional account settings, connect the Facebook Page that will issue the Page Access Token.
Confirm the link from the Page side too.

Create or select a Meta business app

Open My Apps and create an app with the business messaging use case, or open an existing one.
Add the Instagram product and configure Instagram messaging for the linked Page and account.

Keep development and production on separate apps and accounts.

Assign access and generate the Page Access Token

Grant the app, testers, and system users the Instagram messaging and Page permissions they need.
Complete any permission review your app mode requires.
Generate a Page Access Token for the linked Page.

The token needs instagram_manage_messages. A token from a short-lived user token lasts about an hour, and one from a long-lived user token doesn’t expire.

Find the Instagram Account ID

Copy the numeric professional account ID from the Instagram messaging area of the App Dashboard. You can also query the linked Page for its connected Instagram account in the Graph API Explorer.Don’t use the @username, the Facebook Page ID, the Meta App ID, a recipient PSID, or a profile URL.

Copy the App Secret

Go to App settings -> Basic.
Select Show beside App secret, re-enter your password, and copy the value.

Use the App Secret from the same app that owns the Instagram webhook.

Choose a Verify Token

Create a long random value that only Artemis and the Meta webhook form know. Use a different value per environment.

Artemis channel configuration

Create the connection before you select Verify and Save in Meta. Artemis resolves Meta’s challenge from a hash of the saved Verify Token.

Open Artemis and select the project.
Go to Deployments -> Channels -> Instagram -> + New. The New Instagram Connection dialog opens, with the setup guide on the left and the fields on the right.

Configure the fields:

Artemis field	Source / Notes	What it controls
Display Name	You choose it	The label operators see. Name it for the account and environment. Routing ignores it.
Instagram Account ID	The App Dashboard or Graph API Explorer	The routing key, matched to `entry.id` in each webhook.
Page Access Token	The linked Facebook Page	Authorizes replies to `/{InstagramAccountId}/messages`.
App Secret	App settings -> Basic	Validates `X-Hub-Signature-256` over the exact raw POST body.
Verify Token	You create it	Your shared challenge secret. It isn’t the Page Access Token or the App Secret.
Environment	Your published environments	The environment whose active deployment answers messages. Leave the working copy default only while you develop.
Provider Verification Strength	Defaults to Weak	How far the runtime trusts Meta’s identity assertion when it links a person to an existing session. Choose Strong only when you base continuity and account-linking decisions on it.
Initial Status	Defaults to Active	Keep it Active. Meta’s challenge resolves only for an active connection.

Select Create.
Copy the Webhook URL from the connection’s summary panel. Don’t add an account ID or any suffix.

Webhook configuration in Meta

Registration has two halves. Meta verifies the URL whether or not you subscribe to anything, so finish both.

Confirm the Artemis connection exists and is Active.
In the same Meta app, open the Instagram webhook configuration and paste the Artemis Webhook URL exactly.
Enter the same Verify Token and select Verify and Save. Meta sends hub.mode=subscribe, hub.verify_token, and hub.challenge, and Artemis returns the challenge only when the token matches an active Instagram connection.
Subscribe to messages for text, attachments, and quick replies, and messaging_postbacks for action callbacks. Save the subscription.
Confirm the app and the Page subscription connect the same Instagram account. Artemis rejects a connection mismatch.
Make sure any proxy in front of Artemis keeps X-Hub-Signature-256 and passes the raw body unchanged.

Validation checklist

Work down this list once per connection.

Validation item	Expected result
Prepare the account	Business or Creator account, linked to a Page where you hold messaging and moderate tasks.
Prepare the app	Instagram product added, permissions granted, and a valid Page Access Token.
Create the Artemis connection	Saved as Active with the account ID, token, App Secret, and Verify Token.
Register the webhook	Meta verifies the callback, with `messages` and `messaging_postbacks` subscribed for the intended account.
Send a real message	A direct message reaches the agent and one reply returns.

Verify the connection

Artemis doesn’t synthesize Meta events, so a real Instagram conversation is the only end-to-end proof.

While the app is in Development, send from an account with an app or Instagram tester role. A public user proves nothing until review and Live mode are complete.
Send a unique text to the professional account. Confirm one signed messages event, one session, and no processing of echo events.
Confirm the reply reaches the original sender through /{InstagramAccountId}/messages, inside the messaging window.
Select an authored quick reply and a generic-template action. Confirm each resumes the same instagram:{accountId}:{senderId} session.
Send image, video, audio, and file attachments. Artemis downloads signed Meta CDN URLs promptly, before they expire, and applies size and attachment policy.

Input	What to confirm
`text`	The agent receives and answers it.
`image`, `video`, `audio`, `file`	The download succeeds and the agent processes the file.
`quick replies`, `postbacks`	The selection returns to the same session with the right action.

Instagram behavior and limits

Design agent responses to fit these limits.

Area	Limit
Quick replies	Buttons and selects become quick replies, up to 13 options, with titles truncated to 20 characters.
Carousels	Generic templates support up to 10 elements, each with up to 3 buttons.
Ignored inputs	Artemis ignores shares, story mentions, like-hearts, reels, stickers, and fallback-only attachments rather than creating blank agent turns.
Media downloads	Recognized Meta and Instagram CDN hosts only, a 30-second timeout, and a 100 MB streaming cap.
Messaging window	Meta can reject replies outside the Instagram messaging window. Test expected conversation timing and approved use cases before production.

Security and lifecycle

Meta signs what it sends. Your Verify Token only protects the one-time challenge.

Signatures: Artemis rejects any POST without a valid X-Hub-Signature-256 before queueing. Preserve the request body, content encoding, header, external scheme, and proxy behavior through ingress.
Verify Token: Use a unique random value per environment, and rotate it in Artemis and Meta together.
Page Access Token: It authorizes outbound messages. Encrypt and redact it, grant least privilege, monitor expiry, rotate it, and keep it out of browser code.
Environments: Use separate Meta apps and accounts, or at least isolated credentials, tokens, subscriptions, and connections, for development and production.

Manage the channel connection

Open a connection from Deployments -> Channels -> Instagram to manage it. The page has a header, three tabs, and a summary panel on the right. Header. Shows the connection name, its environment badge, its status, and when it last changed. The … overflow menu holds the connection-level actions. Summary panel. Stays visible on every tab.

Field	Description
Channel and Connection Type	Read Instagram and Channel Connection.
Identifier	The Instagram Account ID this connection routes on. Check it first when messages arrive and no session appears.
Credentials	Reads Configured once credentials save.
Webhook URL	The callback URL for Meta, with a copy control.
Created and Updated	Date and time of creation and of the last change.

Credentials
Configuration
Deployment

Artemis encrypts credentials after you save them. Leave a field blank to keep its current value, or enter a new value to replace it.

Field	Description
Use Auth Profile	Turn it on, then select a saved auth profile in place of the fields below.
Page Access Token	Replace it when you generate a new token in Meta.
App Secret	Replace it if the Instagram product moves to another Meta app.
Verify Token	Changing it breaks the Meta webhook until you enter the same value in Meta.

Select Save Credentials to apply your changes.

Update how the connection behaves. Instagram Settings holds the provider-specific fields.

Setting	Description
Display Name	The label operators see.
Provider Verification Strength	How far the runtime trusts Meta’s identity assertion.
Instagram Account ID	Read-only, with a copy control. To serve another account, create a new connection.
Message template	The authorization message the connection sends when a tool needs the user to authorize. Insert variables from the chips, select Show more for the full list, and select Show preview to check it.
Webhook URL	The callback URL, with a copy control.

Select Save Changes to apply your changes.

Choose which deployed version answers Instagram messages.

Setting	Description
Environment	Under Environment Binding. Selects which deployed version handles incoming messages.
Active Deployment	Shows the bound version and when someone deployed it.

Select Save Changes after you switch the environment.

Troubleshoot connection issues

Most failures trace to the token, the App Secret, or the subscription.

Symptom	Likely cause	Recommended action
Meta can’t verify the callback	No active connection, mismatched token, or unreachable endpoint	Create the Active connection first, use the same Verify Token in both systems, expose public HTTPS, and keep the generic Instagram webhook path.
Inbound requests return `401`	Wrong App Secret or altered request	Use the App Secret from the app that owns the webhook, preserve `X-Hub-Signature-256`, and stop proxies from reserializing JSON.
No connection found	The payload’s account ID doesn’t match	Compare `entry.id` with the saved Instagram Account ID. A Page ID or sender ID in that field produces this result.
Verified but no messages arrive	Missing subscription or ineligible sender	Subscribe `messages` and `messaging_postbacks`, connect the intended account, inspect Meta deliveries, and confirm the sender holds a role in the current app mode.
Inbound works but outbound fails	Token, linkage, or window issue	Check the Page Access Token, account linkage, permissions, token expiry, messaging window, and Graph API reachability.
Text works but actions don’t	Missing postbacks subscription or oversized payload	Subscribe `messaging_postbacks`, and keep quick-reply and template payloads within the limits.
Text works but attachments fail	Media outside policy	Use image, video, audio, or file, confirm the signed URL hasn’t expired, the host is a recognized Meta CDN, the download is within 100 MB, and your attachment policy accepts it.
Meta rejects replies after a delay	The messaging window closed	Reproduce inside an active conversation, and review Meta’s current messaging window and approved use cases.

Meta reference

Use these pages when you need detail beyond what this article covers.

Resource	Use it for
Instagram Platform overview	Account eligibility and rate limits.
Instagram messaging get started	App setup, permissions, and Page tokens.
Send a message	Outbound formats and messaging window rules.
My Apps	Returning to an app or checking which app owns a subscription.

Related articles:

Get started

Build

Test and evaluate

Deploy

Analytics and insights

References

Prerequisites

How Artemis routes Instagram events

Instagram and Meta setup

Artemis channel configuration

Webhook configuration in Meta

Validation checklist

Verify the connection

Instagram behavior and limits

Security and lifecycle

Manage the channel connection

Troubleshoot connection issues

Meta reference

​Prerequisites

​How Artemis routes Instagram events

​Instagram and Meta setup

​Artemis channel configuration

​Webhook configuration in Meta

​Validation checklist

​Verify the connection

​Instagram behavior and limits

​Security and lifecycle

​Manage the channel connection

​Troubleshoot connection issues

​Meta reference

Prerequisites

How Artemis routes Instagram events

Instagram and Meta setup

Artemis channel configuration

Webhook configuration in Meta

Validation checklist

Verify the connection

Instagram behavior and limits

Security and lifecycle

Manage the channel connection

Troubleshoot connection issues

Meta reference