Instagram Integration

Instagram Integration provides a powerful way to connect your AI bots with Instagram Messaging, enabling you to reach users through Instagram Direct Messages. The integration supports rich features including contact collection, file attachments, and comprehensive event logging for monitoring and analytics.

The Instagram Integration leverages the Meta Instagram Messaging API and requires proper configuration of webhooks, access tokens, and app settings through the Meta Developer Portal. Once configured, your chatbot can receive and respond to messages, handle multimedia content, and maintain conversation sessions with customizable durations.

Creating an Instagram Integration

Creating an Instagram integration is the first step to connecting your chatbot with Instagram Messaging. This process establishes the foundation for receiving and sending messages through the Instagram platform.

To create a new Instagram integration, you need to provide basic information such as the integration name and optional description. The integration automatically generates a unique verify token that will be used during webhook setup with Meta's platform:

POST /api/v1/integration/instagram/create
Content-Type: application/json

{
  "name": "Customer Support Bot",
  "description": "Instagram integration for customer inquiries",
  "botId": "bot_abc123",
  "contactCollection": true,
  "attachments": true,
  "sessionDuration": 3600000
}

http

The response includes the integration ID, which you'll use for subsequent configuration steps. After creating the integration, you'll need to:

  1. Configure Meta Business Account - Set up a Meta Business account and create an Instagram App through the Meta Developer Portal

  2. Connect Instagram Account - Link your Instagram Professional or Business account to your Facebook Page

  3. Set up Webhooks - Configure webhook endpoints in the Meta Developer Portal using the callback URL and verify token provided by ChatBotKit

  4. Configure Access Token - Generate a permanent access token with appropriate permissions (instagram_manage_messages) and update your integration

Integration Configuration Options

Contact Collection: When enabled, the integration automatically collects and stores contact information from users who interact with your bot, enabling personalized experiences and data-driven insights.

Session Duration: Customize how long conversation sessions persist (in milliseconds). This determines when the bot should treat messages as part of an ongoing conversation versus starting a new session.

File Attachments: Enable support for receiving and processing files, images, and other media sent by users. All attachments are securely stored and accessible through the conversation history.

Blueprint and Bot Linking: Link your integration to a specific bot or blueprint to inherit configurations and enable centralized management of multiple integrations.

Important Notes:

  • The verify token is automatically generated and cannot be changed after creation - you'll use this token during Meta webhook configuration

  • Instagram Messaging API requires a verified business account and may require payment details depending on your usage tier

  • The access token must have the instagram_manage_messages permission for full functionality

For detailed setup instructions, refer to the Instagram Integration Guide in the main documentation.

Webhook Event Handling and Verification

The callback endpoint serves as the webhook receiver for Instagram Messaging events, handling both the initial webhook verification process required by Meta and the ongoing stream of message events sent whenever users interact with your bot. This endpoint is the bridge between Meta's Instagram Messaging platform and ChatBotKit's conversation processing system, ensuring reliable, real-time message delivery and bot response handling.

Meta's webhook system requires a two-step verification process before sending live events. First, Meta sends a GET request to your callback URL with verification parameters including hub.mode set to "subscribe", hub.verify_token containing the token you provided during webhook setup, and hub.challenge containing a random string that must be returned exactly as received to complete verification. ChatBotKit automatically handles this verification by comparing the provided token with your integration's verify token and returning the challenge response when they match.

Once verified, Meta begins sending POST requests containing message events, postback events, and other user interactions. Each webhook payload contains an array of entry objects, with each entry containing a messaging array that holds individual user interactions. The callback endpoint processes these events by queuing them for asynchronous processing, ensuring fast response times and preventing webhook timeouts even when handling complex bot logic or external API calls.

The callback URL you configure in Meta's Developer Portal must match this endpoint exactly. The URL format is:

https://api.chatbotkit.com/api/v1/integration/instagram/{instagramIntegrationId}/callback

Replace {instagramIntegrationId} with your actual integration ID from ChatBotKit. This URL must be publicly accessible and support both GET (for verification) and POST (for events) requests. Meta requires HTTPS with a valid SSL certificate and will reject webhooks using self-signed certificates or plain HTTP connections.

Webhook Configuration Steps:

  1. Navigate to your Facebook App in the Developer Portal
  2. Select Instagram from the products list
  3. Click "Setup Webhooks" in the Webhooks section
  4. Enter your callback URL with the integration ID
  5. Enter the verify token from your integration's fetch response
  6. Subscribe to webhook events: messages, messaging_postbacks
  7. Click "Verify and Save" to complete the webhook configuration

Event Processing: The callback endpoint immediately acknowledges webhook deliveries with a 200 OK response to prevent Meta from marking deliveries as failed and implementing exponential backoff. Events are then queued for asynchronous processing, where conversation engines handle message routing, bot response generation, session management, and context tracking. This architecture ensures webhook responses stay within Meta's strict timeout requirements while allowing complex bot logic to execute without constraints.

Deleting an Integration

Permanently remove an Instagram integration from your account, disconnecting the associated Instagram account from your chatbot system. This operation is irreversible and should be performed with caution.

Deletion removes all integration configuration from the ChatBotKit platform but does not automatically remove webhook configurations from the Meta Developer Portal. To fully disconnect, you should also remove or disable the webhook configuration on Meta's platform:

POST /api/v1/integration/instagram/{instagramIntegrationId}/delete
Content-Type: application/json

{}

http

What Gets Deleted

Integration Configuration: All stored settings including verify token and feature flags are permanently removed from the system.

Resource Associations: Links to bots and blueprints are severed, but the associated resources themselves remain intact and can be used with other integrations.

Event Logs: Historical event logs related to this integration are preserved for auditing and debugging purposes, but no new events will be logged.

What Does NOT Get Deleted

Conversation History: Past conversations that occurred through this integration are preserved. They remain accessible and can be reviewed for analysis or compliance purposes.

Contact Records: Collected contact information from users who interacted through this integration remains in the contact database.

File Attachments: Media files and attachments sent during conversations are retained in the file storage system.

Meta Configuration: Webhook settings, Instagram app configuration, and access tokens in the Meta Developer Portal remain active. You must manually remove these if you want to fully disconnect.

Important Warnings

Immediate Effect: Deletion takes effect immediately. Any incoming Instagram messages will no longer be processed, and users will receive no response from your chatbot.

No Undo: This operation cannot be undone. If you delete an integration by mistake, you must create a new integration and reconfigure all settings, including updating webhook configurations in the Meta Developer Portal.

Active Conversations: Users with active conversations will experience interruption. The chatbot will stop responding mid-conversation without any notification to the user.

Webhook Cleanup: After deletion, Meta may continue attempting to deliver webhook events to your callback URL. You should disable or remove the webhook configuration in the Meta Developer Portal to prevent unnecessary webhook traffic.

When to Delete

Service Discontinuation: When permanently discontinuing Instagram support for a particular bot or service.

Account Migration: Before creating a new integration for a different Instagram account (though updating the existing integration is usually preferable).

Security Incident: If credentials have been compromised and you need to completely disconnect before creating a new secure integration.

Resource Cleanup: Removing test or development integrations that are no longer needed.

  1. Notify Users: If possible, inform users through Instagram that the service will be discontinued

  2. Export Data: Export conversation logs and analytics data if needed for archival purposes

  3. Remove Meta Webhooks: Disable or delete webhook configuration in the Meta Developer Portal

  4. Delete Integration: Execute the delete operation through the API

  5. Verify Cleanup: Confirm no webhook traffic is being received and no errors are being logged

Fetching Integration Details

Retrieve complete configuration details for a specific Instagram integration, including all settings, linked resources, and operational parameters. This endpoint is essential for displaying integration configuration in management interfaces and verifying setup status.

Use the integration ID to fetch detailed information about a specific Instagram integration. The response includes all configuration options and their current values, enabling you to display complete integration settings or use the data to populate update forms:

GET /api/v1/integration/instagram/{instagramIntegrationId}/fetch
Content-Type: application/json

http

Retrieved Information

The fetch endpoint returns comprehensive integration details:

Identity Information:

  • Integration ID (unique identifier for all API operations)
  • Name and description for display and organizational purposes
  • Creation and last update timestamps

Instagram Configuration:

  • Verify Token (for Meta webhook verification)
  • Contact Collection flag (whether to collect user contact information)
  • Attachments flag (support for files and multimedia)
  • Session Duration (conversation session persistence time in milliseconds)

Resource Relationships:

  • Bot ID (linked conversational AI bot)
  • Blueprint ID (associated configuration blueprint)

Metadata:

  • Custom metadata object for application-specific data

Security Considerations

For security reasons, the accessToken field is returned as a sentinel value instead of the actual credential:

  • Returns "********" if an access token is configured
  • Returns null if no access token has been set

This allows you to verify that credentials are configured without exposing the actual token values. Access tokens provide full control over Instagram Messaging API operations and should be treated as sensitive credentials. When updating an integration, you can send back the sentinel value "********" and the existing token will be preserved unchanged. Only send a new actual token value if you want to update it.

User Authorization: The fetch operation verifies that the requesting user owns the integration. Attempting to fetch another user's integration will result in a 404 Not Found response, preventing information disclosure.

Common Use Cases

Configuration Display: Populate integration settings pages in administrative interfaces, showing current configuration values and status indicators.

Setup Verification: Verify that all required fields (access token) have been configured before enabling the integration.

Update Forms: Pre-populate update forms with current configuration values, allowing users to modify specific settings while preserving others.

Status Monitoring: Check integration configuration as part of health checks or troubleshooting workflows.

Integration Cloning: Retrieve configuration from an existing integration to use as a template for creating similar integrations.

Note: Always store sensitive credentials like access tokens securely on your backend. Never expose them in client-side code or logs.

Setup and Configuration

The setup endpoint performs initialization and validation tasks for an Instagram integration, ensuring all required configurations are in place and properly connected with the Meta Instagram Messaging API. This endpoint is typically called after creating an integration and configuring the necessary credentials and settings.

Setup operations verify that the integration is properly configured and ready to receive and send messages through Instagram. While the current implementation is lightweight, this endpoint provides a foundation for future setup automation and validation logic:

POST /api/v1/integration/instagram/{instagramIntegrationId}/setup
Content-Type: application/json

{}

http

Setup Prerequisites

Before calling the setup endpoint, ensure you have completed these configuration steps:

Meta Business Account: You must have an active Meta Business account with appropriate permissions. Depending on your account status, you may need to configure payment details and verify your business information.

Instagram Professional Account: You need an Instagram Professional (Business or Creator) account connected to a Facebook Page.

Facebook App: Create a Facebook App in the Meta Developer Portal with the Instagram Messaging product enabled.

Access Token: Generate an access token with the required permissions (instagram_manage_messages). This token must be created through a System User with Admin role for production use.

Webhook Configuration: Set up webhooks in the Meta Developer Portal using the callback URL and verify token provided by your ChatBotKit integration. The webhook must be configured to receive the "messages" field for proper operation.

Configuration Verification

The setup process validates that critical configuration elements are present and correctly formatted. While specific validation logic may evolve, the endpoint ensures your integration meets minimum requirements for Instagram messaging operations.

Common Setup Issues

Invalid Access Token: Verify that your access token has the correct permissions and hasn't expired. System User tokens should be configured for long-term validity to avoid service interruptions.

Webhook Verification Failure: If webhooks aren't receiving messages, verify that you've correctly copied the callback URL and verify token to the Meta Developer Portal. The verify token is case-sensitive and must match exactly.

Account Connection Issues: Ensure your Instagram Professional account is properly connected to your Facebook Page and that the Facebook App has the necessary permissions.

Setup Workflow

  1. Create Integration: Use the create endpoint to establish a new Instagram integration and receive your verify token

  2. Configure Meta Webhooks: Set up webhook configuration in the Meta Developer Portal using the provided callback URL and verify token

  3. Generate Access Token: Create an access token through a System User in your Meta Business account

  4. Update Integration: Add the access token to your integration using the update endpoint

  5. Run Setup: Call this setup endpoint to validate the configuration

  6. Test Messaging: Send a test message to your Instagram account to verify end-to-end functionality

Integration Health Monitoring

After successful setup, monitor your integration through:

  • Event Logs: Review integration event logs for webhook delivery confirmations and message processing events

  • Conversation History: Verify that conversations are being created and messages are being processed correctly

  • Error Tracking: Watch for authentication errors, rate limiting, or delivery failures that might indicate configuration issues

For detailed step-by-step setup instructions with screenshots and troubleshooting guidance, refer to the Instagram Integration Guide in the main documentation.

Updating Integration Configuration

Modify the configuration of an existing Instagram integration to adjust settings, update credentials, or change linked resources. This endpoint allows you to fine-tune integration behavior and keep credentials current without recreating the integration.

The update operation supports modifying all configurable integration properties while preserving the integration ID and verify token. This is particularly useful for updating Meta access tokens when they expire or need to be rotated for security purposes:

POST /api/v1/integration/instagram/{instagramIntegrationId}/update
Content-Type: application/json

{
  "name": "Updated Customer Support Bot",
  "accessToken": "IGQVxxxxxxxxxxxxxx",
  "contactCollection": true,
  "sessionDuration": 7200000,
  "attachments": true
}

http

Updatable Configuration

Basic Information: Modify the integration name and description to reflect changes in purpose or organizational structure. These fields are for display purposes and don't affect operational behavior.

Instagram Credentials: Update the access token if you need to rotate credentials or when token permissions change.

Feature Toggles: Enable or disable contact collection, file attachments, and other optional features based on your use case and privacy requirements.

Session Management: Adjust session duration to control how long the system treats incoming messages as part of an ongoing conversation. Longer durations maintain context better but may not be suitable for all use cases.

Resource Linking: Change the associated bot or blueprint to modify the conversational behavior and capabilities of the integration.

Important Considerations

Verify Token Immutability: The verify token cannot be changed after integration creation. If you need a different verify token, you must create a new integration and reconfigure your Meta webhooks.

Access Token Rotation: When updating the access token, ensure the new token has the required permissions (instagram_manage_messages). Invalid tokens will cause message delivery failures.

Active Conversations: Configuration changes take effect immediately for new conversations but don't affect ongoing conversation sessions.

Metadata Preservation: The metadata field uses merge semantics - new metadata is merged with existing metadata rather than replacing it entirely, allowing partial updates.

Update Best Practices

  • Test in Development: Test configuration changes with test accounts before applying to production integrations

  • Monitor After Updates: Watch event logs and message delivery after updating credentials to ensure proper operation

  • Document Changes: Use the metadata field to track configuration history and reasons for changes

  • Secure Token Storage: Never log or expose access tokens in client-side code or error messages

  • Incremental Updates: Update one configuration aspect at a time to simplify troubleshooting if issues arise

Listing Instagram Integrations

Retrieve a paginated list of all Instagram integrations associated with your account. This endpoint is essential for managing multiple Instagram connections, monitoring integration status, and implementing integration selection interfaces in your applications.

The list endpoint supports pagination through cursor-based navigation, allowing you to efficiently retrieve large numbers of integrations. You can also filter integrations by blueprint association and customize the ordering and number of results returned:

GET /api/v1/integration/instagram/list?take=10&order=desc
Content-Type: application/json

http

The response includes comprehensive details about each integration, including configuration options, linked resources, and metadata.

Security Considerations

For security reasons, the accessToken field is returned as a sentinel value:

  • Returns "********" if an access token is configured
  • Returns null if no access token has been set

This allows you to verify which integrations have credentials configured without exposing the actual secret values.

Response Information

Each integration in the response includes:

  • Basic Details: Integration ID, name, and description
  • Verify Token: The webhook verification token (needed for Meta setup)
  • Feature Flags: Contact collection, attachments, and session settings
  • Resource Links: Associated bot ID and blueprint ID
  • Timestamps: Creation and last update times
  • Metadata: Custom metadata for application-specific tracking

Filtering and Pagination

Cursor-Based Pagination: Use the cursor parameter with a previously returned cursor value to fetch the next page of results. This ensures consistent pagination even when integrations are added or removed.

Result Ordering: Control the sort order with the order parameter (asc for oldest first, desc for newest first).

Blueprint Filtering: Add blueprintId query parameter to retrieve only integrations associated with a specific blueprint.

Result Limits: Use the take parameter to control the number of integrations returned per request (useful for implementing custom pagination UI).

Use Cases

  • Dashboard Views: Display all Instagram integrations with their configuration status in administrative interfaces

  • Integration Selection: Allow users to choose which Instagram integration to use for specific bots or workflows

  • Status Monitoring: Periodically fetch integration lists to monitor configuration completeness and identify integrations requiring attention

  • Bulk Operations: Retrieve all integrations for batch updates or configuration synchronization across multiple Instagram connections

Note: The access token field is intentionally excluded from list responses for security reasons. Use the fetch endpoint to retrieve individual integration details when needed.

Go to cbk.ai