Skip to main content
After this guide, direct messages to your Instagram account reach your agent and its replies appear in the DM thread. Instagram is connected in the admin dashboard only, with Instagram Login; lua channels has no Instagram entry. You need an Instagram professional account (Business or Creator), and no Facebook Page link is required. Verified against lua-cli 3.33.0. Before you begin
  • An Instagram professional account. Meta’s Instagram Platform documentation covers converting a personal account.
  • Message access allowed for connected tools in the Instagram app (Settings → Messages and story replies → Connected tools); without it Meta delivers no DMs to any app.
  • An agent with a promoted production version; see Release an agent.
1

Dashboard: link the account

In the admin dashboard open Agents, select the agent, select + in the Channels section of its Overview tab, and choose Instagram in Connect a channel. Tick I accept the Terms of Service and Privacy Policy and select Connect. Instagram Login opens and asks for instagram_business_basic and instagram_business_manage_messages; sign in with the professional account and grant them. Lua exchanges the code for a long-lived token and subscribes the account to the messages and messaging_postbacks fields.
2

Verify

From another Instagram account, send the professional account a DM with hello. The agent replies in the thread, and lua channels list shows an INSTAGRAM entry with the username.

​
Channel behavior

​
Token lifecycle

Instagram tokens expire. Lua refreshes the long-lived token on a schedule and treats it as expiring a day early, so a healthy channel never needs attention. If Meta rejects a refresh (revoked permissions, a password change), Lua stops refreshing and marks the channel as needing reauthorisation; reconnect it from the admin dashboard and the schedule resumes.

​
Limits

  • Proactive sends are warm-only. There is no way to message someone who has never written to the account.
  • An Instagram account connects to one agent at a time. Connecting it to a second agent fails with This Instagram account is already connected to another agent. Disconnect it there before connecting it to this agent.
  • Admin dashboard only. The CLI lists the channel but cannot create or remove it.

​
Troubleshooting

The account must be a professional account, and the browser must allow the popup. Convert the account, allow popups for the admin dashboard, and select Connect again.
Check that message access for connected tools is allowed in the Instagram app and that the channel isn’t marked as needing reauthorisation in the admin dashboard. Reactions, story mentions, and receipts are dropped by design; send a text message to test.
Meta rejected the stored token, so refreshes are disabled. Disconnect the channel in the admin dashboard and connect it again with Instagram Login.

​
Next steps

Connect Facebook Messenger

The Page-based sibling, with a CLI path.

Send proactive messages

What warm-only means for follow-ups.

Channels reference

Channels.send and delivery status.

About channels

The inbound and outbound channel vocabularies.