Skip to content

Connect channels

Connect Instagram

How to link an Instagram professional account for Direct, comments and mentions.

  • An Instagram professional account (business or creator). If no account is granted at login, the connection is rejected with instagram_account_not_professional.
  • You do not need a Facebook Page.
  • The person logging in must manage the account on Instagram.
  • On the account, turn on Settings → Messages and story replies → Message controls → Connected tools → Allow access to messages. Without it Direct does not work (see Direct access disabled).

Messajo only asks for the permissions of the Instagram API with Facebook Login for Business:

Permission What for Required
instagram_basic Read the account profile and media yes
instagram_manage_messages Receive and send Direct messages yes
instagram_manage_comments List, reply to, hide and delete comments; private replies; mentions no
instagram_content_publish Publish photos, videos, carousels, Reels and Stories no
instagram_manage_insights Read the insights of the account and of each post no

Without one of the two required permissions the connection is not created (signup_scope_mismatch). The others can be unchecked on the Instagram screen: the account connects, the connection page shows Missing permissions and the feature answers 403 instagram_scope_missing, with the permission in details[0].message, until you reconnect.

  1. Open Connections → Connect Instagram. The panel navigates to Meta’s page (Facebook Login for Business), with no popup and working on mobile.
  2. Sign in, choose the Instagram account(s) Messajo may access and confirm.
  3. Meta sends you back to Messajo, which exchanges the code for an access token, reads the account, subscribes the app to the webhooks and reads the messaging profile.
  4. Done: the account shows as Active, with the subscribed webhook fields.
  • One account granted: it connects directly.
  • More than one: Messajo shows a picker and connects one per login. Repeat the login to connect the others.
  • None: error instagram_account_not_professional.

If you cancel on the Meta screen, the attempt shows in the connection History with the CANCEL event. If a step fails after the connection is created, it stays Pending with the missing step, and Finish connection redoes only what is missing.

An organization can connect several accounts. To connect a customer’s account, send an invite link with the Instagram channel: the person authorizes from the invite’s public page, without a Messajo account.

The access does not expire, so there is nothing to renew. If Meta revokes it (password changed, app removed from the account, error 190), the connection becomes needs_reconnect with token_invalid and the owner gets the notice with the reconnection link. Reconnecting keeps the same connection.

If Allow access to messages is turned off on the account, the connection health check reports reason: "dm_access_disabled": a connection.updated event goes out and the panel shows a warning. The connection stays active, and comments, publishing and insights keep working; only Direct does not. To fix it, on Instagram open Settings → Messages and story replies → Message controls → Connected tools and turn on Allow access to messages. The warning clears on the next check.

Accounts connected with Instagram Login must reconnect once. Message ids from Meta differ between the two logins.

Instagram and Messenger use the same engine and the same POST /v1/messages. to is the contact’s IGSID (or Messajo’s ctc_…).

type WhatsApp Instagram Messenger
text (with quick_replies on IG/Messenger) yes yes yes
image · video · audio · document yes yes yes
images (2 to 10 images in one message) no yes no
reaction yes yes yes
like no yes no
share (share a post of the account) no yes no
buttons · cards no yes yes
template · interactive · location · contacts · sticker yes no no

A type outside the matrix returns 422 type_not_supported_by_channel. On Instagram, text is up to 1,000 bytes; images up to 8 MB (JPEG, PNG or GIF); audio, video and PDF up to 25 MB. typing: true shows “typing” before the send and POST /v1/messages/{id}/read marks the conversation as seen. The contact arrives with name, username and picture (read on the first message and every 7 days).

Meta only lets you reply inside a window opened by the contact’s last message:

Window When it applies
24 hours Any reply, counted from the contact’s last message
7 days After the contact replies to a Direct ad (Messajo recognizes the ad referral)
7 days With tag: "human_agent"

tag: "human_agent" is only for replies written by a person (Meta policy): never use it in automation or bots. The panel does not offer the tag in automations. It requires the Human Agent feature approved in App Review; without it Meta rejects and Messajo returns 403 human_agent_not_approved.

Outside the window, Messajo rejects before calling Meta: 422 outside_service_window, with the window end in details[0].message. With the tag and more than 7 days: 422 human_agent_window_closed. Reactions, likes and share do not open or extend the window.

With instagram_manage_comments, Messajo subscribes the comments, live_comments and mentions fields and delivers the comment.* and mention.received events (catalog).

What /v1 route Event
Comments on a post (live from Meta, with Messajo’s state) GET /connections/{id}/posts/{post_id}/comments —
Reply in public POST /connections/{id}/comments/{comment_id}/replies with { message } (up to 2,200 characters) comment.replied
Hide or show POST /connections/{id}/comments/{comment_id}/hide with { hidden } comment.hidden · comment.unhidden
Delete DELETE /connections/{id}/comments/{comment_id} comment.deleted
Private reply POST /connections/{id}/comments/{comment_id}/private-reply comment.private_replied + message.sent
Mentions GET /connections/{id}/mentions mention.received

A private reply sends a Direct message to the commenter, even without an open 24-hour window. Meta’s rules: only text, buttons or cards; one per comment (409 private_reply_already_sent); up to 7 days after the comment, and on a live comment only during the live (422 private_reply_window_closed). The reply opens the conversation with the contact and the next messages follow the normal windows.

You can only delete comments on the account’s own media (comment_not_owned). Your reply comes back from Meta as a webhook, but does not produce an event again.

In Connections → (account) → Messaging profile, or with GET/PUT /v1/connections/{id}/messaging-profile:

  • Ice breakers: up to 4 per language, up to 80 characters each, with the payload that arrives in the webhook when the person taps.
  • Persistent menu: up to 20 items (postback or link).
  • Ad welcome messages: on Instagram, welcome messages are the Direct ad flows (/v1/connections/{id}/welcome-flows). A flow used in an ad cannot be changed or deleted (welcome_flow_in_use).

Messaging profile screen of an Instagram account, with an ice breaker and a welcome flow

The PUT is partial: a missing field does not change, null deletes. After saving, Messajo reads the profile back from Meta.

If you already speak the Instagram Graph API, use /v1/instagram/{ig_user_id}/... with Meta’s body and response untouched: Messajo adds the account token and checks the key’s permission. Standalone nodes (media, comment, container, message) live at /v1/instagram/{ig_user_id}/nodes/{node_id}.

  • POST …/messages records the message in the logs, spends the send tokens and returns X-Messajo-Message-Id.
  • subscribed_apps, access_token and oauth/* are blocked (403 mirror_path_blocked).
  • media_publish through the mirror does not go through Messajo’s scheduling: to schedule, use /v1/publications.
  • bulk sending (there are no campaigns on Instagram);
  • messages outside the window;
  • groups;
  • personal accounts: it only works with a professional account.