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, stream to enable token-by-token response streaming for a more interactive experience, and allowFrom to restrict which Discord users can send messages to the bot.

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 attempt to delete all existing slash commands for your Discord application before registering the new command. If individual deletions fail, setup continues and the new command will still be registered. However, if you have multiple bots or commands configured outside of ChatBotKit, they may persist alongside the new command. 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, update session management options including sessionDuration and contactCollection, and configure sender restrictions via allowFrom.

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.

Direct Message (DM) Support

Slash commands work in both Discord server channels and in direct messages (DMs) with the bot. When a user invokes the slash command in a DM, Discord sends the interaction with the user object at the root level of the payload rather than inside member.user (which is used for guild/server interactions). ChatBotKit handles both formats automatically, so your bot responds correctly regardless of whether the user is in a server channel or a private DM.

To allow users to interact via DM, ensure your Discord application has the bot scope added and that users can find and message your bot directly. No additional configuration in ChatBotKit is required - DM interactions use the same integration settings, session management, and conversation flow as server channel interactions.

Typing Indicator

When a slash command interaction includes a channel_id in the payload (which Discord provides for guild channel interactions), the integration uses the channel ID to send a typing indicator before generating a response. This shows users the "... is typing" animation while the bot processes their request. The typing indicator requires a botToken to be configured on your integration and is not shown in ephemeral mode. See your integration's Queue Processing section for more details on typing indicator behavior.

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.

Background Processing

Discord requires webhook responses within 3 seconds, which is too short for most AI conversations. To handle this, slash command interactions and setup operations are processed asynchronously in the background, so the bot can acknowledge Discord immediately and then deliver the AI response when it is ready. Duplicate webhook deliveries from Discord are safely ignored, so users never see the same response twice.

Conversation Sessions

Each user has their own independent conversation context. The sessionDuration setting controls how long that context persists between messages and defaults to one day if not specified, up to a maximum of one month. Shorter sessions are useful for stateless queries, while longer sessions enable ongoing, contextual conversations. When a session expires, the next interaction starts a fresh conversation.

When the integration's ephemeral setting is enabled, responses are visible only to the user who invoked the command and the bot operates with reduced trust to prevent exposure of sensitive information.

Typing Indicators

While the bot is preparing a response, Discord shows the familiar "... is typing" animation in the channel so users know their request is being handled. The typing indicator requires the integration's botToken to be configured and is automatically suppressed when the integration is in ephemeral mode or when the channel context is not available (such as in some DM scenarios). If the typing animation cannot be shown, the user still receives the response normally.

Streaming Responses

If streaming is enabled in the integration configuration, the bot's reply is progressively delivered to Discord as tokens are generated, creating a streaming effect in the channel. For non-streaming integrations, the complete response is delivered as a single message once generation finishes.

Sender Filtering with allowFrom

The allowFrom integration setting restricts which Discord users can trigger the bot. When configured, only messages from permitted user IDs or usernames are processed. Messages from other senders are silently dropped.

This is useful for private bots intended for specific team members, internal tools with controlled access, or staged rollouts where you want to limit interaction to a defined group before opening the bot to everyone. Configure allowFrom when creating or updating your Discord integration:

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

{
  "allowFrom": "123456789012345678,987654321098765432"
}

http

Proactive Messaging

The initiate event type allows your bot to send the opening message in a conversation rather than waiting for a user to invoke a slash command. This enables proactive outreach scenarios such as onboarding notifications, scheduled alerts, and follow-up messages triggered by external events.

When an initiate event is processed, the bot posts the opening message to the specified Discord channel or thread, and any subsequent user reply in that channel continues the same conversation context.

An optional context object can be included in the initiate payload to provide background information about the recipient or situation. The bot uses this context when responding to follow-up messages.

Sessions created by initiate events follow the same sessionDuration setting used for reactive slash-command sessions. Once a session expires, the next user message in that channel starts a new conversation.

Warning: Account-level conversational limits apply to prevent abuse and ensure fair resource allocation. If an account exceeds these limits, new interactions are rejected with a limits exceeded error. Monitor your usage and upgrade plans as needed to accommodate interaction volume.

Go to cbk.ai