Which button do I use to connect an Instagram account?

Connect Instagram. It signs in with the Instagram account itself, and it is the only way to link one. Connect Facebook / Messenger links Facebook Pages for Messenger only. It does not bring a Page's Instagram account with it.

What do I do when an account says needs relink?

The needs relink badge means Meta refused the daily token refresh, usually because the password changed, the app was removed or a role was lost. Click Reconnect on the row in the accounts screen and finish the consent again; the new token replaces the old one. One account.disconnected event goes to your endpoints when this happens.

Connect an Instagram account

HookChat sees an Instagram inbox only once you link the account. The link is one consent screen on Instagram. It takes a minute when the account is set up right, and gives one clear message when it is not. This page covers both.

Before you start#

A HookChat workspace. Sign in to the console to create one.
An Instagram professional account, business or creator. Personal accounts cannot use the messaging API. Switch in the Instagram app under Settings, Account type and tools.
The login for that account, since Instagram asks you to sign in on its own page.

Link the account#

Open Connect a channel in the console.
Click Connect Instagram. You go to Instagram, not to HookChat.
Sign in and allow the two permissions HookChat asks for. They are listed below.
You land back in the console with the account linked.
Send the account a DM from another account. The event shows up in the console within seconds, and at your webhook if you have one.

What HookChat asks for#

Permission	Why
`instagram_business_basic`	The account id and username, so the console can name the inbox.
`instagram_business_manage_messages`	Read DMs and send replies.

HookChat never sees the Instagram password. Meta hands over a token for that one account. The token stays on the server and is never sent to the browser.

Facebook Pages link through the other button, Connect Facebook / Messenger, for Messenger only. After consent you pick which Pages to link. A Page's Instagram account does not come with it: connect Instagram here, with Instagram Login.

When a token stops working#

Meta tokens do not last forever. A daily job refreshes them, and when Meta refuses, because the password changed, the app was removed or a role was lost, the accounts screen marks the account needs relink and sends one account.disconnected event to your endpoints. Click Reconnect on the row and finish the consent again; the new token replaces the old one. The troubleshooting page has the details.

If Meta says no#

Instagram sends you back to the console with a status. If you cancelled, the page says consent was declined. For anything else it shows the line Meta sent, so you can tell which case below you are in.

Insufficient developer role#

The Meta app behind HookChat is in development mode, and only accounts listed on the app can log in. Meta shows this while an app waits for review. Two steps fix it:

In the Meta developer dashboard open the app, then App roles, Roles, Add people. Pick Instagram Tester and enter the Instagram username.
In the Instagram app open Settings, Website permissions, Apps and websites, Tester invites, and accept. The role does nothing until the invite is accepted, and this is the step most people miss.

Then click Connect Instagram again. Once the app is live, any professional account can connect and this message goes away for good.

The account is not eligible#

The account is personal. Switch it to business or creator in the Instagram app, then try again. Nothing changes on the HookChat side.

Something went wrong starting the connection#

Meta said yes but the link step failed on our side, most often because the sign-in took longer than the ten minutes the link is valid for. Click Connect Instagram again. If it fails twice, contact support with the time it happened. The screen shows a request id; quote it if you write to support.

Disconnect an account#

On the accounts screen, click Disconnect on the row and confirm. From code, call DELETE /v1/accounts/{account_key}, or run hookchat accounts disconnect. HookChat asks Meta to stop sending the account's messages, deletes the saved token and sends account.disconnected to your endpoints. New messages for the account stop arriving at once.

Conversations and messages you already have stay. Connect the same account again and they come back. To erase them, use Data deletion and app removal.

What Meta needs for app review#

Meta asks every app for two callbacks: one for when a person removes the app, one for when a person asks for their data to be deleted. You set both once, in your Meta app dashboard on the Instagram and Messenger products: the deauthorize callback URL is https://hookchat.dev/deauthorize and the data deletion request URL is https://hookchat.dev/data-deletion. The gateway answers both. What happens after either one fires, what is erased and what stays with you, is on Data deletion and app removal.

Next#

Getting startedCreate a key, register a webhook, receive a signed event and send a reply in under ten minutes.Receive and verify eventsWhat arrives at your webhook for each DM, and how to check the signature.Reply within the windowSend a reply while Meta allows it, and what to do once the window closes.Data deletion and app removalWhat the gateway erases when a person removes your app or asks Meta to delete their data.