Skip to main content
Version: 1.0

Setting Up the Instagram Channel

The Instagram integration uses the Instagram Messaging API (Meta) via OAuth. The process connects an Instagram Business account to your Application. You can authorize the connection either through Instagram directly or through a linked Facebook account.

Prerequisites​

  • An Instagram Business or Creator account (personal accounts are not supported)
  • A Facebook Page linked to the Instagram account
  • Administrator access to the Facebook Page (required for the Facebook flow)
  • Hub Chatt2.me account with administrator permission on the Application

Connection process​

1. Start authorization​

In the Hub Chatt2.me dashboard:

  1. Go to Channels → Activate/Configure → Instagram
  2. Choose your preferred authorization method:
    • Connect with Instagram — authorizes directly via Instagram OAuth
    • Connect with Facebook — authorizes via the Facebook account linked to the Instagram Page

2a. Instagram OAuth flow​

If you chose Connect with Instagram:

  1. Log in with your Instagram Business or Creator account
  2. Authorize the requested permissions (access to message inbox)
  3. The channel is created automatically

2b. Facebook OAuth flow​

If you chose Connect with Facebook:

  1. Log in with the account that manages the Facebook Page linked to Instagram
  2. Authorize the requested permissions (access to Instagram message inbox)
  3. Select the corresponding Facebook Page
  4. Select the Instagram account linked to that Page

3. Channel ready​

After authorization, the channel is created and the UUID becomes available in the channel details.

Identifying the recipient (to)​

The to field on Instagram uses the IGSID — the unique ID of the user in Instagram Messaging. You obtain this ID from the webhook payload when the user sends you a message first.

// Example webhook payload with IGSID
{
  "sender": {
    "id": "847495124317323"
  }
}
warning

You cannot initiate conversations on Instagram with users who have never sent you a message before. The messaging window only opens after the user interacts with your channel.

Required permissions​

Meta PermissionPurpose
instagram_basicAccess basic account information
instagram_manage_messagesSend and receive messages
pages_manage_metadataManage Page metadata
pages_messagingAccess message inbox via API

Data deletion (LGPD / GDPR)​

Meta requires that apps integrating Instagram implement a data deletion endpoint. When a user requests data deletion from Meta, the Hub receives a notification and processes the deletion automatically.

You can check the status of a deletion request in the Hub Chatt2.me dashboard under Channels → Instagram → Data deletion.

Limitations​

  • It is not possible to send messages to users who have never started a conversation with your channel
  • Document files are not supported on Instagram (only text, image, video, audio, and sticker)
  • The messaging window lasts 7 days after the last user interaction (unlike WhatsApp which is 24h)

Identifying the sender (from)​

In POST /v1/communication/instagram/message, set from to the application channel UUID or the Instagram username for that channel (with or without a leading @). The UUID always works as a fallback. See Sending messages overview.

Next steps​