> For the full page index, fetch https://echonova.ai/llms.txt # Instagram Import an Instagram professional account, through the Facebook Page it is linked to, and connect it to an agent so it answers the direct messages people send it. Connecting Instagram puts an agent behind the direct messages of an Instagram professional account. Instagram messaging runs through the Facebook Page the account is linked to, so you connect the account through that Page. Anyone who sends the account a direct message gets the agent's reply, every exchange is recorded as a conversation on the agent, and each reply is charged as a text turn. ## What the agent can do on Instagram | Capability | Supported | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | Voice | No | | Text | Yes | | Inbound | Yes. A text message, or the payload of a quick reply or button the account offers, arrives as the person's message | | Outbound | Yes, as a reply to a message the person sent. The agent never starts a conversation | | Handoff | No | | Media | No. A message that carries only an image, a reel, a story reply with no text, audio or a sticker gets no reply, and the agent sends text only | A reply is always plain text. Each person who messages the account gets one conversation, and the conversation keeps going while the gap between messages stays under 24 hours; the next message after a longer silence starts a new one. In **Conversations** the person appears under their Instagram username when it arrives with the message, otherwise as **Visitor** followed by `#` and the last four characters of their Instagram id. The account's own replies are not treated as incoming messages, and a message Meta delivers twice is answered once. ## Prerequisites on the provider side - An Instagram professional account (a business or creator account) linked to a Facebook Page. You connect the account through that Page. - A Facebook account that manages the linked Page, ready to grant four permissions: to read the linked Instagram account (`instagram_basic`), to send and receive its messages (`instagram_manage_messages`), to list the Pages you manage (`pages_show_list`) and to manage the Page's settings (`pages_manage_metadata`). - Until Meta approves EchoNova's app, that Facebook account needs a role on EchoNova's Meta app. - An account belongs to one EchoNova workspace at a time. If it is already connected in another workspace, connecting fails with **That account is already connected to a different EchoNova workspace.** ## Connect ### Step 1: Open the agent's Channels tab Open the agent and choose **Channels**. The tab is headed **Connected Channels**. Press **Add Channel**, pick **Messaging** if you want a shorter list, and choose the **Instagram** card. The dialog **Connect Instagram Account** opens on its **Configure** tab, beside **Triggers** and **How To Connect**. The **Triggers** tab has nothing to set. It reads **Incoming messages**: **Messages to this connected account are handled by the linked agent.** ### Step 2: Name the connection and pick an account On the **Configure** tab: - **Name**: used only when you pick an already-imported account under **Credential** and press **Connect**; the row then takes this name. An account you import here is named after its **@handle**, or after its Page when it has no username. - **Credential**: a dropdown of this workspace's already-imported Instagram accounts, or a way to import a new one. If the workspace has no Instagram accounts yet, this reads **You have no Instagram accounts. Import an account here.**, with **here** as the link. If it already has some, the dropdown lists each one by its saved name, with the placeholder **Instagram account**, and a separate **Import another account** link sits below it. An account already bound to this agent or to another one is listed but disabled, marked **(on this agent)** or **(on another agent)**. ### Step 3: Connect an account Press **here** or **Import another account**. Meta's own window opens; sign in with the account that manages the linked Page and approve the four permissions. Back in EchoNova: - **One account** granted: it connects to this agent straight away, with the toast **Instagram connected**. - **Several accounts** granted: the **Choose what to connect** dialog opens, listing each by **@handle** with the Page name underneath. Tick every account to connect; one already connected here can be ticked again to refresh it (**Connected here**), and one connected in another workspace cannot be ticked (**In another workspace**). Press **Connect**, read the result line next to each account, and press **Done**. To reuse an account you already imported, pick it from the **Credential** dropdown instead. Picking one fills in **Name** with the account's saved name, if **Name** is still empty. Press the dialog's **Connect** button to bind that account to this agent. If the connect ends with an error instead, the table below has the message and what to do about it. | Message | What happened | What to do | | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | **Access was declined. No changes were made.** | You declined the permissions on Meta | Connect again and approve | | **The connection didn't complete. Please try again.** | Meta did not hand over a usable sign-in | Connect again | | No message. You land on the **Agents** list with nothing connected | More than 10 minutes passed, or the sign-in finished in a different browser from the one that started it | Open the agent again and start from its **Channels** tab | | **We couldn't resolve that page. Please try again.** | Meta returned no Page with a linked Instagram account for the account you signed in with | Sign in with an account that manages the linked Page | | **That account is already connected to a different EchoNova workspace.** | The account belongs to another workspace | Disconnect it there first | | **We couldn't create the webhook. Check the app's permissions, then reconnect.** | The Page was found but Meta refused to send its messages to EchoNova, so nothing was saved | Sign in again with an account that is an admin of the linked Page and approve all permissions | | **Something went wrong connecting this channel. Please try again.** | Meta did not hand over the linked Page's access at sign-in, or the connect failed for a reason with no message of its own | Connect again | | **This choice expired. Start again.** | More than 10 minutes passed since signing in for several accounts, or that list was already used | Press **Import another account** and sign in again | | **Move this channel?** | The account is already connected to another agent in this workspace | **Move** binds it here and closes its open conversations; **Cancel** leaves it where it is | ## Get it right Instagram messaging only works for a Page whose Instagram account is a business or creator account linked in Meta. Check that link on the Page before you sign in, rather than after **Choose what to connect** comes back without the account you expected. **Recommended** - Confirm the Page's linked Instagram professional account in Meta first, then sign in and tick its **@handle** in **Choose what to connect**. **Less effective** - Signing in and expecting every Page you manage to offer an Instagram account, then troubleshooting why one is missing from the list. ## Send the first message Open Instagram and send the account a direct message, for example "Is the blue one back in stock?". The agent replies in text, in the same direct message thread, using the **Personality** you set on the **Persona** tab. The **Greeting message** is not sent on Instagram; the agent's first message is its answer. In the portal, open the agent's **Conversations** tab: the exchange is listed under the Instagram channel. The channel's own detail page, opened from its row on the **Channels** tab, counts it under **Conversations** and **Messages** and lists it on the **Conversations** section. Each reply is priced as a text turn; see [What a turn costs](/docs/agents/what-a-turn-costs). If the workspace has no credits left, the person's message is recorded in the conversation and no reply is sent. If a reply cannot be produced, the person receives "Sorry, I can't respond right now. Please try again shortly." ## Provider limits that affect you | Limit | Value | Effect | | ----------------------- | ------------------------------------- | ------------------------------------------------------------------------- | | Accounts per connection | 1 | Connect each account separately, through its own Page | | Workspaces per account | 1 | An account connected elsewhere must be disconnected there first | | Agents per connection | 1 | Use **Assign to another agent** to move it | | Meta sign-in window | 10 minutes | Finish the sign-in within that time, once, in the browser that started it | | Choose what to connect | Valid 10 minutes, or until used once | After that, sign in again | | Page access | Does not expire | Nothing to reconnect on a schedule | | Message content in | Text, quick-reply and button payloads | Anything else is not answered | | Message content out | Text | The agent sends no images, buttons or attachments | | Conversation gap | 24 hours | A message after a longer silence opens a new conversation | ## Disconnect Open the row's menu on the **Channels** tab and choose **Disconnect**, or open the channel's detail page, press **Test** and choose **Disconnect** from the menu. The dialog **Disconnect channel?** reads "This permanently deletes {name} and its saved credential. Reconnecting later starts a brand new connection." Confirm with **Disconnect**; the toast **Channel disconnected** follows. > [!WARNING] > Disconnecting closes the account's open conversations, removes the > connection and deletes the saved access. Reconnecting starts a new > connection. The conversations already recorded stay on the agent. Disconnecting also stops EchoNova receiving the linked Page's messages once no other channel in EchoNova, such as Messenger on the same Page, still uses it. To keep the connection but stop this agent answering, choose **Assign to another agent** from the row's menu instead. Open conversations are closed and the next message goes to the agent you picked. ## Troubleshooting ### The agent never answers a direct message Check, in this order: - The row is on this agent's **Channels** tab. A connection with no agent drops every message it receives. - The message has text. An image, a reel, a story reaction, audio or a sticker alone is not answered. - The Instagram account is still linked to the Page you connected it through. If it was moved to a different Page, its messages stop reaching EchoNova; import it again through the new Page. - The workspace has credits. With none left, messages are recorded and no reply goes out. ### The person got "Sorry, I can't respond right now. Please try again shortly." The agent could not produce a reply for that turn. The message is kept in the conversation; ask the person to send it again. ### Choose what to connect doesn't list my account The Facebook Page it should come from either has no Instagram professional account linked to it, or the account you signed in with does not manage that Page. Check the link in Meta, then sign in again. ### Pause Channel does nothing **Pause Channel** on the channel's detail page does not stop the channel today. To stop the agent answering, disconnect the channel or assign it to another agent. ## FAQ ### Why does the row show a Facebook Page name? The row is named after the account's **@handle**, and its **Workspace** label shows the name of the Facebook Page the account is linked to, because Instagram messaging runs through that Page. The reply still lands in the person's direct message thread with your Instagram account. ### Does the agent answer comments on posts or stories? No. The agent answers direct messages only. ### Can the agent hand the conversation to a person? No. Instagram has no handoff. Write the **Personality** so the agent tells the person how to reach your team when it cannot help. ### Can one account talk to two agents? No. An account is one connection, and a connection answers for one agent. Move it with **Assign to another agent**. ### Does the account's access ever expire? No. Like Messenger, an Instagram connection's Page access does not expire, so there is nothing to reconnect on a schedule. ### What does Test on the channel page do? It opens the channel's action menu, with **Pause Channel** and **Disconnect**. Test the channel by sending the account a direct message from Instagram. ## Related - [Test your agent](/docs/agents/test-your-agent): check the agent's answers before you point an account at it - [Persona](/docs/agents/persona): the **Personality** text the agent uses on every channel - [How the prompt is assembled](/docs/agents/prompting-guide): what the agent reads on a text conversation - [Conversations](/docs/agents/conversations): where Instagram conversations are listed and read - [What a turn costs](/docs/agents/what-a-turn-costs): what each reply is charged - [Agent status](/docs/agents/agent-status): archiving does not stop a connected channel