Instagram

The Instagram integration lets you deploy your ChatBotKit AI bot to handle Instagram Direct Messages, allowing customers to reach your business directly through the platform. Users can start conversations with your bot, and it responds using the knowledge and instructions you have configured. All conversations maintain context across messages, creating natural, coherent interactions.

What You Can Do

With the Instagram integration, you can:

• Direct Messaging: Deploy the bot to handle direct messages sent to your Instagram Professional account
• Conversation Context: Maintain conversation state so replies reference previous messages in the thread
• Contact Collection: Automatically capture contact information from users who message your account
• Session Management: Configure how long a conversation stays open before starting fresh
• File Attachments: Process images and media files sent by users
• Custom Metadata: Attach tracking or integration metadata to your integration
• Automated Responses: Provide 24/7 customer engagement through Instagram Direct Messages without manual intervention

How It Works

When someone sends a direct message to your Instagram Professional account, the message is forwarded to ChatBotKit through a webhook. Your bot processes the message using its backstory, knowledge (datasets), and capabilities (skillsets), then sends the reply back through Instagram. The bot remembers the conversation history within the session window, allowing for natural follow-up messages.

Getting Started

To set up the Instagram integration:

1. Go to Integrations: Navigate to Integrations and click Create Integration
2. Select Instagram: Choose Instagram Bot from the available options
3. Name and Bot: Give the integration a descriptive name and select which ChatBotKit bot will handle conversations
4. Create: Click Create to generate your integration
5. Get Your Webhook URL: After creation, you will see your unique webhook URL in the integration page
6. Add the App Secret (recommended): Copy the App Secret from Meta App Dashboard > App settings > Basic into the integration's App Secret field. When set, ChatBotKit verifies every incoming webhook notification against its X-Hub-Signature-256 signature and rejects anything not signed by your app. It is optional - integrations without it keep working - but without it the webhook accepts unsigned requests.
7. Set Up Meta Business Account: Ensure you have a Meta Business Account with an Instagram Professional account connected
8. Create Instagram App: In Meta Developer Portal, create an Instagram App
9. Generate Access Token: Generate a permanent access token using a System User with appropriate permissions
10. Add Access Token: Paste the access token into the Access Token field in your ChatBotKit integration
11. Configure Webhook: In Meta Developer Portal > Instagram > Webhooks, add your ChatBotKit webhook URL as the callback URL
12. Click Setup: Click the Setup button in ChatBotKit to verify the webhook connection
13. Test: Send a direct message to your Instagram Professional account to confirm the bot responds

Access Token Requirements

The Access Token must be a permanent token generated using a System User in your Meta App. This allows ChatBotKit to authenticate requests on behalf of your app. Follow these steps to generate one:

1. Go to Meta Developers
2. Select your app and navigate to Roles > System Users
3. Create or select a System User with Admin role
4. Click Generate Access Token, select your Instagram Professional account, and ensure the token has the instagram_manage_messages permission
5. Copy the token and paste it into ChatBotKit

The token is stored encrypted and will not be shown in full after saving.

Advanced Options

These settings appear under Advanced Options after the integration is created:

• Contact Collection - When enabled, the bot automatically creates or updates a contact record for each user who messages your account, capturing their name and Instagram ID
• Session Duration - How long the bot keeps a conversation context open. Messages within this window continue the same conversation; messages after restart a new one. Default is 1 day
• Attachments - When enabled, the bot processes images and media files sent by users
• Meta - Custom key-value metadata for tracking or system integration purposes

Best Practices

Test Before Going Live: Send test direct messages to your Instagram Professional account and verify the bot responds appropriately. Check for correct tone, helpful information, and proper formatting.

Set Clear Instructions: In your bot's backstory, include guidelines for messaging. Instagram conversations are often brief, so keep responses concise and clear.

Use Meaningful Session Duration: The default 1-day session works for most cases, but consider adjusting if your use case requires different behavior. Longer durations are useful for support bots where users may follow up much later.

Monitor Conversations: Regularly check the Conversations section to understand how users are interacting with your bot and identify areas for improvement.

Collect Useful Contact Info: Enable Contact Collection if you want to build a user list for future campaigns or better personalize responses based on known users.

Troubleshooting

Bot Not Responding: Verify that the Access Token is correct and that the webhook URL has been configured in Meta Developer Portal. Use the Setup button to re-verify the connection.

Token Expired or Invalid: Generate a new permanent access token using a System User and update it in the integration settings.

Messages Not Being Received: Confirm that your bot can receive messages by checking the Conversations section. If no conversations appear, the webhook may not be properly connected.

Session Not Persisting: If conversations are not maintaining context, check the Session Duration setting. A very short duration will cause new sessions to start frequently.