Skip to main content
Version: Latest

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.

Limitations​

  • It is not possible to send messages to users who have never started a conversation with your channel
  • The messaging window lasts 7 days after the last user interaction (unlike WhatsApp which is 24h)

Media formats and limits​

TypeFormats currently accepted by the HubOutbound limitInbound mirror limit
ImageJPEG, PNG, GIF, WebP8 MBProvider maximum not published; Hub safety ceiling 2 GiB
AudioAAC, M4A/MP4 and WAV directly; OGG, Opus, MP3/MPEG and WebM input are converted to M4A25 MBProvider maximum not published; Hub safety ceiling 2 GiB
VideoMP4; QuickTime/MOV input is converted to H.264/AAC MP425 MBProvider maximum not published; Hub safety ceiling 2 GiB
StickerInstagram's like_heart platform stickerPlatform valuePlatform value
DocumentNot supported—Attachments received from users are preserved when Meta supplies them

The Hub applies only the audio and video conversions listed above. The 25 MB audio/video ceiling is the Hub's conservative attachment contract because Meta's current public documentation does not provide a stable exhaustive MIME-and-size matrix for every Instagram Messaging attachment. The inbound 2 GiB value is an operational download protection, not a Meta limit.

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​