Discord Integration

Discord Integration allows you to bring ChatBotKit's conversational AI capabilities directly into Discord servers, enabling bot interactions through slash commands and interactive messaging. This integration provides seamless communication between your AI bot and Discord users, supporting features like ephemeral messages, streaming responses, and customizable command handles.

Creating a Discord Integration

Creating a Discord integration establishes the connection between ChatBotKit and your Discord application. Before creating an integration, you must first set up a Discord bot application through the Discord Developer Portal. This involves creating an application, adding a bot user, and obtaining the necessary credentials.

To create a Discord integration, you need three key pieces of information from your Discord application: the Application ID, Bot Token, and Public Key. These credentials enable secure communication between ChatBotKit and Discord's API. The Application ID identifies your Discord application, the Bot Token authenticates API requests, and the Public Key verifies webhook signatures to ensure request authenticity.

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

{
  "name": "Support Bot",
  "description": "Customer support bot for Discord server",
  "botId": "bot_abc123",
  "appId": "1234567890123456789",
  "botToken": "YOUR_DISCORD_BOT_TOKEN_HERE",
  "publicKey": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "handle": "support",
  "ephemeral": false,
  "sessionDuration": 3600000
}

http

The handle parameter defines the slash command users will type to interact with your bot (e.g., /support for a handle of "support"). If not specified, the default handle is "chatbotkit". The ephemeral setting determines whether bot responses are visible only to the user who invoked the command or to all members in the channel.

Additional configuration options include sessionDuration to control conversation session length (in milliseconds), contactCollection to enable user data collection, attachments to allow file sharing, and stream to enable token-by-token response streaming for a more interactive experience.

Important: After creating the integration, you must configure the Interactions Endpoint URL in your Discord application settings. This URL receives webhook events from Discord and must be set to complete the integration setup. See the Setup section for detailed configuration steps.

Required Discord Bot Permissions

When configuring your Discord bot in the Developer Portal, ensure your bot has the following OAuth2 scopes enabled:

  • applications.commands - Required to register and manage slash commands
  • bot - Standard bot permissions for server interaction

The bot also requires these specific permissions within Discord servers:

  • Read Messages/View Channels - To see where commands are used
  • Send Messages - To reply to user commands
  • Use Slash Commands - Core functionality for command-based interactions
  • Embed Links - To format rich message responses

For more detailed information about Discord bot setup and configuration, refer to the Discord Integration Documentation and the Discord Developer Documentation.

Setting Up Your Discord Integration

Setting up a Discord integration involves configuring slash commands and establishing the interaction endpoint between Discord and ChatBotKit. This process registers your bot's commands with Discord and ensures proper webhook communication. The setup process must be completed after creating the integration and obtaining the necessary Discord application credentials.

The setup endpoint automatically configures your Discord bot by registering the slash command specified in the integration's handle parameter. It removes any existing commands to prevent conflicts and creates a new command with the specified handle and description. This ensures your bot responds consistently to the correct slash command format.

POST /api/v1/integration/discord/{discordIntegrationId}/setup
Content-Type: application/json

{}

http

After creating your Discord integration, you must configure the Interactions Endpoint URL in your Discord application settings. Navigate to the Discord Developer Portal, select your application, and go to the General Information section. Paste the Interactions Endpoint URL (provided in your ChatBotKit integration settings) into the "Interactions Endpoint URL" field and save the changes.

This endpoint receives webhook events from Discord whenever users invoke your bot's slash commands. Discord will verify the endpoint by sending a PING interaction, which ChatBotKit automatically handles by responding with a PONG. This verification must succeed before Discord allows your bot to receive interaction events.

Common Setup Issues and Solutions

Issue: Slash command not appearing in Discord

  • Solution: Run the setup endpoint to register commands. Discord may cache command lists, so you might need to restart your Discord client or wait a few minutes for commands to appear. In some cases, leaving and rejoining the server can refresh the command list.

Issue: "Invalid application command" error

  • Solution: This typically indicates the Interactions Endpoint URL is not configured correctly in the Discord Developer Portal. Verify the URL is copied exactly as shown in your ChatBotKit integration settings and that you've saved the Discord application settings. Run the setup endpoint again after correcting the URL.

Issue: Signature verification failures

  • Solution: Ensure the Public Key in your ChatBotKit integration matches exactly with the Public Key shown in your Discord application settings. Any mismatch will cause Discord to reject webhook verifications. Update the Public Key if needed and run the setup endpoint again.

Warning: The setup process will delete all existing slash commands for your Discord application before registering the new command. If you have multiple bots or commands configured outside of ChatBotKit, they will be removed. Ensure you're using dedicated Discord applications for ChatBotKit integrations to avoid conflicts.

For troubleshooting other issues, check the Event Log in your Discord integration settings, which provides detailed records of all webhook interactions and error messages. This log is invaluable for diagnosing configuration problems and API communication failures.

Updating a Discord Integration

Updating a Discord integration allows you to modify configuration settings, change bot credentials, adjust behavior options, or update the associated bot after the initial integration setup. This is particularly useful when rotating security credentials, changing slash command handles, or adjusting conversation settings based on usage patterns and requirements.

When you update an integration, the system automatically triggers a re-setup process to ensure Discord commands are synchronized with your new configuration. This means any changes to the handle parameter will result in the slash command being updated in Discord immediately, though users may need to restart their Discord clients to see the updated commands.

POST /api/v1/integration/discord/{discordIntegrationId}/update
Content-Type: application/json

{
  "name": "Updated Support Bot",
  "description": "Enhanced customer support bot with new features",
  "handle": "help",
  "ephemeral": true,
  "sessionDuration": 7200000,
  "stream": true
}

http

All parameters from the create endpoint are supported in updates. You can modify basic information like name and description, update security credentials including appId, botToken, and publicKey, change the slash command handle, adjust behavior settings like ephemeral messages and streaming, and update session management options including sessionDuration and contactCollection.

Important Update Considerations

When updating Discord credentials (Application ID, Bot Token, or Public Key), ensure the new credentials belong to the same Discord application. Changing to a different application may cause webhook verification failures and require reconfiguration of the Interactions Endpoint URL in Discord.

Changing the handle parameter updates your bot's slash command in Discord. Users will need to use the new command format (e.g., /help instead of /support). Existing conversations are not affected, but new interactions must use the updated command. Consider notifying your Discord community before changing handles to avoid confusion.

The sessionDuration parameter controls how long conversation context is maintained. Decreasing this value won't immediately expire existing sessions but will apply to new interactions. Increasing it allows longer contextual conversations but may increase resource usage. The value is specified in milliseconds, with a maximum of one month (2592000000 milliseconds).

Warning: Updating sensitive credentials like Bot Token or Public Key while the bot is actively handling conversations may cause temporary interruptions. Consider updating during low-traffic periods or notify users of potential brief disruptions. The system will automatically re-establish connections after updates.

Listing Discord Integrations

Listing Discord integrations retrieves all configured Discord bot integrations for your account, providing a comprehensive view of your Discord bot deployments across different servers and use cases. This endpoint supports pagination and filtering to help you manage multiple integrations efficiently, especially when working with large-scale deployments or testing environments.

The list endpoint returns essential information about each integration including identification, configuration settings, and timestamps. For security reasons, sensitive credentials like Bot Token and Public Key are never included in list responses, ensuring credential safety even when retrieving multiple integrations simultaneously.

GET /api/v1/integration/discord/list

http

This endpoint supports standard pagination parameters including cursor for navigating through large result sets, order to specify ascending or descending sort order (defaults to descending by creation date), and take to control the number of items returned per request. Pagination ensures efficient retrieval even when managing dozens of Discord integrations.

GET /api/v1/integration/discord/list?take=10&order=desc

http

Filtering Discord Integrations

The list endpoint supports filtering by metadata and blueprint associations. You can filter integrations by blueprint ID to see all Discord bots associated with a specific blueprint, which is useful for managing bot deployments organized by project or use case. Metadata filtering allows you to query integrations based on custom tags or properties you've added.

GET /api/v1/integration/discord/list?blueprintId=bp_abc123

http

The response includes key configuration details for each integration: the unique identifier for programmatic operations, name and description for human reference, blueprint and bot associations for understanding deployment structure, Application ID and slash command handle for Discord-specific configuration, session management settings, and creation/update timestamps for tracking integration lifecycle.

Note: The list response excludes the botToken and publicKey fields for security purposes. These sensitive credentials are only available when fetching a specific integration by ID using the fetch endpoint. This prevents accidental exposure of credentials when retrieving multiple integrations for management dashboards or monitoring tools.

Fetching a Discord Integration

Fetching a specific Discord integration retrieves detailed configuration information for a single integration, including all settings and associations. This endpoint is essential for retrieving the complete integration state when displaying configuration details, performing updates, or troubleshooting issues with a specific Discord bot deployment.

Unlike the list endpoint, fetching a single integration provides access to the complete configuration including sensitive fields (though credentials like Bot Token and Public Key remain protected). The fetch operation requires the unique integration identifier and returns comprehensive details about the integration's current state and configuration.

GET /api/v1/integration/discord/{discordIntegrationId}/fetch

http

The response includes all publicly accessible configuration parameters: basic identification including the unique ID, human-readable name and description for reference, blueprint and bot associations showing which AI bot powers this integration, Discord-specific configuration including Application ID and slash command handle, behavior settings like ephemeral mode and session duration, custom metadata for extended properties, and creation and update timestamps for tracking changes.

Using Integration Identifiers

The discordIntegrationId parameter accepts multiple identifier formats for flexible access. You can use the standard UUID format (e.g., di_abc123def456ghi789), which is the most common approach. Alternatively, you can use custom identifiers if you've configured metadata-based lookup patterns for your integrations.

This flexibility allows you to retrieve integrations using identifiers from external systems or custom naming schemes, making it easier to integrate with existing infrastructure or management tools. The system automatically resolves the provided identifier to the correct integration while enforcing access control to ensure users can only fetch their own integrations.

Security Note: The fetch endpoint excludes sensitive credential fields (Bot Token and Public Key) from responses for security reasons. These credentials are write-only after initial creation and can only be updated through the update endpoint. If you need to verify or rotate these credentials, you must provide new values through an update operation rather than retrieving existing values.

This security model prevents credential leakage through API responses while still allowing full integration management. The Application ID is included in responses as it's considered a public identifier used in Discord's OAuth and interaction flows, but authentication tokens remain protected.

Deleting a Discord Integration

Deleting a Discord integration permanently removes the connection between ChatBotKit and your Discord bot, stopping all webhook processing and slash command functionality. This operation is irreversible and immediately terminates the integration, preventing any further interactions through the Discord bot. Use this endpoint when decommissioning a bot, cleaning up test integrations, or migrating to a new configuration.

When an integration is deleted, all associated data including conversation sessions, event logs, and configuration settings are removed from ChatBotKit. However, the Discord application itself remains configured in the Discord Developer Portal. You should manually remove the Interactions Endpoint URL from your Discord application settings to complete the cleanup process.

POST /api/v1/integration/discord/{discordIntegrationId}/delete
Content-Type: application/json

{}

http

The delete operation requires no request body parameters. Simply provide the integration identifier in the URL path, and the system will verify ownership before proceeding with deletion. The operation returns the deleted integration's ID to confirm successful removal.

Impact of Deletion

Deleting an integration has immediate effects on your Discord bot's functionality. The webhook endpoint stops processing interaction events from Discord, meaning users who attempt to use the slash command will receive error messages or no response. Active conversations are terminated, and any in-progress message processing is abandoned. The slash command may remain visible in Discord for a short period due to caching, but it will not function.

Conversation history associated with the integration is preserved in the conversation database but becomes orphaned, meaning it's no longer accessible through the integration context. If you need to maintain conversation history, export or backup relevant conversations before deleting the integration. Related bot configurations and blueprints are not affected and can be reused with new integrations.

Post-Deletion Cleanup

After deleting a ChatBotKit integration, you should clean up your Discord application configuration to prevent confusion and webhook errors. Navigate to the Discord Developer Portal and remove or clear the Interactions Endpoint URL from your application's General Information section. This prevents Discord from attempting to send webhook events to endpoints that no longer exist.

If you plan to decommission the Discord application entirely, you can delete it from the Developer Portal. However, if you intend to reuse the application with a new ChatBotKit integration, you can leave it configured and simply create a new integration with the same credentials.

Warning: Deletion is permanent and cannot be undone. Ensure you have backed up any necessary configuration details or conversation logs before proceeding. If you're unsure about deletion, consider updating the integration to disable it temporarily rather than removing it permanently.

Using the Interaction Webhook

The Interactions Endpoint URL is the webhook that Discord uses to send user commands to your bot. After creating your Discord integration in ChatBotKit, copy the Interactions Endpoint URL from your integration settings and paste it into your Discord application's "Interactions Endpoint URL" field in the General Information section.

Discord will send a verification request to this endpoint when you first save it. The endpoint automatically handles this verification, responding to Discord's PING with a PONG to confirm it's working correctly. Once verified, Discord will start sending your bot's slash command interactions to this endpoint.

When users invoke your bot's slash command (e.g., /support Hello), Discord sends the interaction to this endpoint. The endpoint queues the message for processing and immediately responds to Discord within the required 3-second window. Your bot then processes the conversation in the background and sends the response back to Discord when ready.

Common Issues

If you see "Invalid Interactions Endpoint URL" errors in Discord:

  • Verify you've copied the complete URL from your ChatBotKit integration settings
  • Ensure the Public Key in ChatBotKit matches your Discord application's Public Key
  • Make sure you haven't modified the URL or added extra characters
  • Try clicking the Setup button in your ChatBotKit integration to re-register commands

If slash commands aren't appearing in Discord:

  • Run the Setup operation in your ChatBotKit integration settings
  • Restart your Discord client or refresh your browser
  • Wait a few minutes for Discord to update its command cache
  • Check that your bot has the applications.commands scope enabled

Note: This endpoint only handles slash commands. Direct bot mentions in messages won't trigger responses. Users must use the slash command format like /chatbotkit message or your custom handle like /support message.

For detailed error information, check the Event Log in your Discord integration settings. The log shows all webhook interactions and any errors that occurred, which is helpful for troubleshooting configuration issues.

Discord Queue Processing and Background Operations

The Discord queue system handles asynchronous processing of interaction events and setup operations that exceed Discord's 3-second webhook response timeout. This background processing architecture enables complex AI conversations, streaming responses, and integration setup operations without blocking webhook responses or timing out Discord's strict requirements.

The queue processes two primary event types: interaction events that handle user slash commands and AI conversation processing, and setup events that configure Discord slash commands and webhook registration. Events are queued with deduplication to prevent duplicate processing of the same interaction, which could occur if Discord retries webhook deliveries.

Interaction Event Processing

When a user invokes a slash command, the interaction endpoint queues an interaction event containing the interaction ID, application ID, user ID, interaction token, and message content. The queue handler processes these events asynchronously, managing conversation state, session management, and AI response generation without blocking the initial webhook response.

The handler retrieves or creates a conversation session based on the user ID and integration configuration. Session duration is controlled by the integration's sessionDuration setting, defaulting to one day if not specified. Sessions enable contextual conversations where the bot remembers previous messages within the session window. When sessions expire, new interactions start fresh conversations.

Conversation Processing and Streaming

After establishing a conversation session, the queue handler processes the user's message through the configured bot's conversation engine. The engine handles AI model selection, context management, and response generation. If streaming is enabled in the integration configuration, responses are sent to Discord in chunks of 20 tokens (configurable via MAX_TOKENS_DEQUE) for a progressive response experience.

The handler uses Discord's webhook API to edit the original interaction response, replacing the deferred response with actual bot content. Each streaming update appends more tokens to the message, creating a typing effect. For non-streaming integrations, a single update sends the complete response after generation finishes.

Rate Limiting and Error Handling

Discord's API enforces rate limits on webhook operations. When streaming responses, the queue handler batches token updates to minimize API calls while maintaining responsive streaming behavior. If rate limit errors occur, the system logs them but continues processing to prevent conversation failures. Future enhancements may include exponential backoff and retry logic for improved resilience.

Error handling includes catching and logging all exceptions, capturing API errors for troubleshooting, handling webhook 404 errors gracefully (which occur if the interaction token expires), and continuing processing even when individual updates fail. This robust error handling ensures that temporary failures don't completely disrupt bot functionality.

Session Management and User Context

Sessions are stored in Redis with keys in the format discord-session-{integrationId}-{userId}, ensuring each user has an independent conversation context. The sessionDuration parameter controls how long conversation context persists, with a maximum of one month. Shorter sessions are useful for stateless queries, while longer sessions enable ongoing, contextual conversations.

When the integration's ephemeral setting is enabled, responses are marked as untrusted, preventing sensitive AI capabilities that could expose private information. This setting also configures Discord's ephemeral flag on responses, making them visible only to the user who invoked the command.

Setup Event Processing

Setup events trigger automatic configuration of Discord slash commands through the Discord API. The handler retrieves all existing commands for the application, deletes them to prevent conflicts, and registers the new command with the integration's configured handle and description. This ensures slash command configurations stay synchronized with integration settings.

Setup events are triggered automatically during integration creation and updates, but can also be invoked manually through the setup endpoint to troubleshoot command registration issues or force resynchronization after Discord-side changes.

Warning: The queue handler has account limits to prevent abuse and ensure fair resource allocation. If an account exceeds conversational rate limits, new interactions will be rejected with a limits exceeded error. Monitor your usage and upgrade plans as needed to accommodate interaction volume.

Note: The queue system runs on Edge runtime with bounded concurrency (configured via withEdgeQueueHandlerBounded) to optimize performance and resource utilization across distributed infrastructure. This architecture ensures reliable processing even under high interaction volumes.

Go to cbk.ai