Slack Integration

ChatBotKit's Slack integration enables you to deploy powerful AI agents directly within your Slack workspace, allowing teams to interact with intelligent assistants through natural conversations in channels, direct messages, and slash commands. This integration provides a comprehensive solution for customer support automation, knowledge management, team collaboration, and workflow enhancement.

The Slack integration supports advanced features including contextual conversations with visible message history, file attachments for document analysis, interactive references with citation buttons, and user feedback collection through reaction-based ratings. All interactions are processed through secure webhook endpoints that handle real-time events from Slack.

Creating a Slack Integration

Creating a Slack integration establishes the foundation for deploying your AI agent within a Slack workspace. The integration requires proper authentication credentials from Slack and allows you to configure various behavioral options that control how your bot interacts with users.

Before creating the integration, you'll need to set up a Slack app in your workspace and obtain the necessary credentials. The Slack app must be configured with appropriate OAuth scopes, event subscriptions, and slash command settings to enable full functionality.

To create a new Slack integration, send a POST request with your configuration:


POST /api/v1/integration/slack/create
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

{
  "name": "Customer Support Bot",
  "description": "AI assistant for customer support inquiries",
  "botId": "bot_abc123",
  "signingSecret": "your_slack_signing_secret",
  "botToken": "xoxb-your-bot-token",
  "visibleMessages": 10,
  "attachments": true,
  "references": true,
  "ratings": true
}
http

The signingSecret and botToken are obtained from your Slack app configuration. The signing secret is found under "Basic Information" → "App Credentials" → "Signing Secret", and the bot token is located under "OAuth & Permissions" → "Bot User OAuth Token" (starts with xoxb-).

Required OAuth Scopes

Your Slack app must have these Bot Token Scopes configured in "OAuth & Permissions":

app_mentions:read - Allows the bot to see when it's mentioned in channels
channels:history - Enables reading public channel message history
groups:history - Allows reading private channel messages
im:history - Enables reading direct message history
mpim:history - Allows reading group direct message history
chat:write - Permits sending messages to channels and DMs
users:read - Enables reading user profile information
commands - Required for slash command functionality
files:read - Required when attachments feature is enabled

Configuration Options

The integration supports several optional configuration parameters:

visibleMessages (number, 0-10): Number of recent channel messages to include as context for bot responses. When set to a value greater than 0, the bot can understand and reference previous messages in the conversation thread. Recommended value is 5-10 for optimal context without overwhelming the AI model.

attachments (boolean): Enables file upload support, allowing users to share documents, images, spreadsheets, and other files with the bot for processing and analysis. Useful for technical support scenarios, document review workflows, and content analysis tasks.

references (boolean): Displays interactive "View References" buttons below bot responses that contain citations or source material. Users can click these buttons to see the exact sources used in generating the response, including document names and relevant excerpts.

ratings (boolean): Adds thumbs up (👍) and thumbs down (👎) reaction buttons below bot responses, enabling users to provide immediate feedback on response quality. Downvotes prompt users to optionally provide detailed feedback explaining why the response wasn't helpful.

contactCollection (boolean): Enables collection and storage of user contact information during conversations, useful for lead generation and customer relationship management.

sessionDuration (number): Maximum duration in milliseconds for conversation sessions before automatic reset. When null or not specified, sessions remain active indefinitely.

Webhook Configuration

After creating the integration, configure these webhook URLs in your Slack app settings:

Event Subscriptions (Enable Events → Request URL):

https://api.chatbotkit.com/v1/integration/slack/{slackIntegrationId}/event

Subscribe to these bot events:

app_mention - When bot is mentioned in channels
message.channels - Public channel messages
message.groups - Private channel messages
message.im - Direct messages
message.mpim - Group direct messages

Slash Commands (Create New Command → Request URL):

https://api.chatbotkit.com/v1/integration/slack/{slackIntegrationId}/command

Interactivity & Shortcuts (Turn on Interactivity → Request URL):

https://api.chatbotkit.com/v1/integration/slack/{slackIntegrationId}/interaction

Replace {slackIntegrationId} with the ID returned from the create endpoint.

Warning: The signing secret and bot token are sensitive credentials that must be kept secure. Never commit these values to version control or share them publicly. If credentials are compromised, regenerate them in your Slack app settings and update your ChatBotKit integration immediately.

Note: Some configuration options like attachments, references, and ratings are marked as beta features and may evolve based on user feedback and platform improvements.

For comprehensive setup instructions including step-by-step Slack app configuration, see the Slack Integration Documentation.

Slash Command Endpoint

Process slash command interactions from Slack, enabling users to invoke your bot with a quick command syntax like /botname your question. Slash commands provide an ephemeral, private way for users to interact with the bot without posting visible messages in channels.

The command endpoint must be configured in your Slack app settings under "Slash Commands" as the Request URL for each command you create. When users type a registered slash command, Slack sends a POST request to this endpoint with the command details and user input.

Webhook URL Configuration

Configure this URL in Slack app settings under "Slash Commands" → "Request URL":

https://api.chatbotkit.com/v1/integration/slack/{slackIntegrationId}/command

Replace {slackIntegrationId} with your actual integration ID from ChatBotKit.

Creating a Slash Command

In your Slack app configuration:

Navigate to "Slash Commands" section
Click "Create New Command"
Configure the command:
- Command: /yourcommand (e.g., /support, /ask, /help)
- Request URL: The webhook URL above
- Short Description: Brief explanation shown in slash command list
- Usage Hint: Example text shown to users (e.g., "ask a question")
Save and reinstall the app to your workspace

How Slash Commands Work

User Invocation: Users type the command followed by their input:

/support How do I reset my password?

Immediate Response: The endpoint acknowledges the command immediately with a 200 OK response containing empty string. This prevents Slack from showing a timeout error to the user.

Background Processing: The command and text are queued for asynchronous processing. The bot generates a response and posts it back to Slack using the provided response_url.

Ephemeral Delivery: Bot responses to slash commands are typically delivered as ephemeral messages (visible only to the user who invoked the command). This provides private, unobtrusive assistance.

Use Cases for Slash Commands

Private Queries: Users get assistance without posting publicly in channels:

/help What is the vacation policy?

Only the user sees the question and response.

Quick Information Lookup: Fast access to information without context switching:

/docs search authentication

Bot searches documentation and returns results instantly.

Status Checks: Query system status or personal information:

/status check server health

Get immediate status updates without navigating away from Slack.

Workflow Triggers: Initiate processes or actions:

/create ticket User authentication issue

Kick off automated workflows through conversational commands.

Best Practices

Command Naming: Choose short, memorable command names that reflect their purpose:

Good: /help, /ask, /support
Avoid: /chatbotkit-customer-support-assistant

Usage Hints: Provide clear, concise usage hints:

Good: "ask a question or search for information"
Avoid: "enter your query here to receive assistance from the AI"

Description: Write descriptions that explain value, not mechanics:

Good: "Get instant help with common questions"
Avoid: "Sends your text to the ChatBotKit API for processing"

Troubleshooting Slash Commands

Command Not Available:

Verify command is created in Slack app configuration
Ensure app is installed/reinstalled after creating command
Check that command name matches exactly (including leading /)
Confirm user has permission to use slash commands

Command Timeout Errors:

Check endpoint is responding within 3 seconds
Verify webhook URL is correctly configured
Ensure integration ID in URL is correct
Test endpoint availability and latency

No Response from Bot:

Verify signature validation is passing
Check that background queue is processing commands
Ensure bot token has necessary permissions
Review queue processing logs for errors
Test with event endpoint to isolate command-specific issues

Authentication Failures:

Confirm signing secret matches Slack app settings
Check for extra whitespace or encoding issues in secret
Verify request is genuinely from Slack (check IP ranges)
Review authentication error logs in integration

Limitations and Considerations

Input Length: Slack limits slash command text to 4000 characters. Longer inputs are truncated.

Rate Limits: Users can invoke slash commands rapidly. Implement rate limiting if needed to prevent abuse.

Visibility: Slash command invocations and responses are private by default. Users cannot share responses with others unless you explicitly post public messages.

Multiple Commands: You can register multiple slash commands pointing to the same endpoint. The command name is included in the payload so you can route different commands appropriately.

Ephemeral vs Public: Responses sent via response_url can be either ephemeral (private to user) or in_channel (visible to everyone). Configure this in your bot's response logic based on use case.

Note: Slash commands provide a complementary interaction method to mentions and direct messages. Users can choose the interaction style that best fits their workflow and privacy needs. Consider supporting all interaction methods for maximum flexibility.

For information about other interaction methods, see the event webhook and interaction endpoint sections.

Deleting a Slack Integration

Permanently remove a Slack integration from your ChatBotKit account. This operation deletes the integration configuration but does not automatically uninstall the Slack app from your workspace or remove the bot from channels.

Deletion is immediate and irreversible. Once deleted, the integration's webhook endpoints become inactive and will no longer process events from Slack. Any ongoing conversations will be terminated, and the bot will stop responding to messages.


POST /api/v1/integration/slack/{slackIntegrationId}/delete
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

{}
http

Replace {slackIntegrationId} with the unique identifier of the integration you want to delete.

What Gets Deleted

When you delete a Slack integration:

Removed:

Integration configuration and settings
Webhook endpoint registrations
Associated conversation sessions
Stored authentication credentials
Feature configuration (visible messages, attachments, references, ratings)

Preserved:

Historical conversation logs (if logging was enabled)
Associated bot configuration (bot remains available for other integrations)
Blueprint resources (if the integration was part of a blueprint)
The Slack app installation in your workspace

Post-Deletion Steps

After deleting a ChatBotKit integration, you should also remove the bot from your Slack workspace to complete the cleanup:

Uninstall the Slack App:
- Go to your Slack workspace settings
- Navigate to "Manage Apps" or "App Management"
- Find your ChatBotKit bot app
- Click "Remove App" or "Uninstall"
Remove Bot from Channels:
- If the bot is still in channels, use /kick @botname to remove it
- This prevents confusion if users try to interact with the now-inactive bot
Update Documentation:
- Notify team members that the bot is no longer available
- Update any internal documentation referencing the bot

Response


{
  "id": "slack_xyz789"
}
json

The response confirms the integration ID that was deleted. After deletion, attempting to fetch or update this integration will return a 404 Not Found error.

Important Considerations

Irreversible Operation: There is no undo or recovery mechanism. Once deleted, you must create a new integration and reconfigure all settings if you want to restore the bot functionality.

Active Conversations: Any conversations in progress when the integration is deleted will be immediately terminated. Users will receive no notification, and the bot will simply stop responding.

Webhook Failures: After deletion, Slack will continue attempting to send events to the now-inactive webhook URLs. These requests will fail with 404 errors until you uninstall the Slack app or update its webhook URLs.

Orphaned Resources: The associated bot and blueprint (if any) are not deleted and remain available. If you want to remove these resources completely, delete them separately using their respective delete endpoints.

Best Practices

Before Deleting:

Verify this is the correct integration by checking its name and ID with the fetch endpoint
Notify users who rely on the bot that it will be removed
Consider exporting conversation logs if needed for future reference
Document the bot's configuration if you might want to recreate it later

After Deleting:

Uninstall the corresponding Slack app from your workspace
Remove the bot from all channels where it was active
Update any automation or scripts that reference the integration
Verify that webhook URLs are no longer receiving traffic

Alternative to Deletion: If you want to temporarily disable the bot without deleting the configuration, consider updating it with invalid credentials or removing the bot from all channels. This preserves your configuration for future reactivation.

For information about recreating a similar integration, see the creating integration section above.

Event Webhook Endpoint

Handle real-time events from Slack including mentions, messages, and user interactions. This webhook endpoint is the core of the Slack integration, receiving and processing all events that trigger bot responses and conversations.

The event endpoint must be configured in your Slack app settings under "Event Subscriptions" as the Request URL. Slack sends HTTP POST requests to this endpoint whenever subscribed events occur in your workspace, such as when users mention the bot or send direct messages.

Webhook URL Configuration

Configure this URL in Slack app settings under "Event Subscriptions" → "Request URL":

https://api.chatbotkit.com/v1/integration/slack/{slackIntegrationId}/event

Replace {slackIntegrationId} with your actual integration ID from ChatBotKit.

Event Subscription Requirements

Subscribe to these bot events in your Slack app configuration:

Required Events:

app_mention - Triggered when users mention the bot with @botname
message.channels - Messages in public channels where bot is present
message.groups - Messages in private channels where bot is present
message.im - Direct messages sent to the bot
message.mpim - Group direct messages including the bot

Without these subscriptions, the bot will not receive events and cannot respond to users.

How Event Processing Works

URL Verification: When you first configure the webhook URL, Slack sends a url_verification challenge request. The endpoint automatically responds with the challenge value to complete verification.

Event Callback Processing: For each subscribed event, Slack sends an event_callback payload containing:

Event type (app_mention, message, etc.)
User information
Channel details
Message content
Timestamp for threading

Signature Validation: Every request is validated using the signing secret to ensure it genuinely comes from Slack. Invalid signatures are rejected with a 403 Forbidden response.

Asynchronous Processing: Events are queued for background processing to meet Slack's 3-second response requirement. The endpoint acknowledges receipt immediately and processes the conversation asynchronously.

Supported Event Types

app_mention: Triggered when users mention the bot in channels:


## Fetching Integration Details

Retrieve detailed configuration and status information for a specific Slack integration. This endpoint provides complete visibility into an integration's settings, feature enablement, and associated resources.

The fetch operation is useful for reviewing current configuration, debugging integration issues, or synchronizing integration settings with external systems. Like the list endpoint, sensitive authentication credentials are never returned for security reasons.

```http
GET /api/v1/integration/slack/{slackIntegrationId}/fetch
Authorization: Bearer YOUR_API_TOKEN

Replace {slackIntegrationId} with the unique identifier of your Slack integration.

Response Fields

The response includes all configuration details for the integration:

Identification:

id: Unique identifier for the integration
name: Human-readable name
description: Descriptive text about the integration's purpose

Resource Associations:

blueprintId: ID of associated blueprint (if configured)
botId: ID of the bot powering this integration

Feature Configuration:

visibleMessages: Number of recent messages included as context (0-10)
attachments: Whether file upload support is enabled
references: Whether citation reference buttons are displayed
ratings: Whether user feedback ratings are enabled
contactCollection: Whether contact information is collected
sessionDuration: Maximum session duration in milliseconds (null for unlimited)

Metadata:

meta: Custom metadata object for storing additional properties
createdAt: ISO timestamp of integration creation
updatedAt: ISO timestamp of last modification

Security Considerations

For security reasons, sensitive credential fields are returned as sentinel values instead of actual secrets:

signingSecret: Returns "********" if configured, null if not set
botToken: Returns "********" if configured, null if not set
userToken: Returns "********" if configured, null if not set

This allows you to verify that credentials are configured without exposing the actual values. When updating an integration, you can send back the sentinel value "********" and the existing credential will be preserved unchanged. Only send a new actual token value if you want to update it.

Example Response


{
  "id": "slack_xyz789",
  "name": "Customer Support Bot",
  "description": "Handles customer inquiries in #support channel",
  "blueprintId": "blueprint_abc123",
  "botId": "bot_def456",
  "signingSecret": "********",
  "botToken": "********",
  "userToken": null,
  "visibleMessages": 10,
  "attachments": true,
  "references": true,
  "ratings": true,
  "contactCollection": false,
  "sessionDuration": 3600000,
  "meta": {
    "workspace": "acme-corp",
    "team": "support"
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-20T14:45:00Z"
}
json

Common Use Cases

Configuration Review: Verify current settings before making updates to ensure you understand the existing configuration.

Debugging: Check feature enablement and resource associations when troubleshooting integration behavior.

Monitoring: Periodically fetch integration details to track configuration changes and audit modifications.

Synchronization: Use fetch to synchronize integration settings with external configuration management systems or dashboards.

If the integration ID doesn't exist or you don't have permission to access it, the endpoint returns a 404 Not Found or 403 Forbidden response respectively.

Interactive Components Endpoint

Handle interactive component actions from Slack, including button clicks, menu selections, modal submissions, and shortcuts. This endpoint processes all user interactions with rich UI elements added by the bot, such as reference citation buttons, feedback rating buttons, and modal dialogs.

The interaction endpoint must be configured in your Slack app settings under "Interactivity & Shortcuts" as the Request URL. When users interact with buttons, dropdowns, or other interactive elements, Slack sends POST requests to this endpoint with the interaction details.

Webhook URL Configuration

Configure this URL in Slack app settings under "Interactivity & Shortcuts" → "Request URL":

https://api.chatbotkit.com/v1/integration/slack/{slackIntegrationId}/interaction

Replace {slackIntegrationId} with your actual integration ID from ChatBotKit.

Supported Interaction Types

Block Actions (Button Clicks):

When users click interactive buttons attached to bot messages:

Show References Button: Displays a modal with citation sources for bot responses
Upvote Button (👍): Records positive feedback on bot response quality
Downvote Button (👎): Opens feedback modal to collect improvement suggestions

View Submissions (Modal Forms):

When users submit modal dialog forms:

Downvote Reason Modal: Collects detailed feedback explaining why a response was unhelpful
Custom modal submissions from shortcuts or workflows

View Closed (Modal Cancellations):

When users close or cancel modal dialogs without submitting. These are acknowledged but don't trigger additional processing.

Shortcuts and Message Actions:

Global shortcuts and message-specific actions (placeholder for future functionality).

Reference Citations Feature

When the references feature is enabled in your integration, bot responses include a "View References" button below messages that contain citations or source material.

How Reference Citations Work:

Response Generation: Bot generates response with source citations
Reference Storage: Citations are stored in Redis with a unique key
Button Attachment: "View References" button is added to message with reference key
User Interaction: User clicks button to see sources
Modal Display: References modal opens showing formatted citation list

Reference Modal Format:

The modal displays each reference with:

Numbered list of sources
Clickable URLs to original documents
Document titles or names
Brief descriptions or excerpts (when available)
Visual separators between references

Reference Expiration: Citations are cached in Redis with time-based expiration (typically 24-48 hours). If references expire before a user clicks the button, the modal shows "References are no longer available" message.

User Feedback Ratings Feature

When the ratings feature is enabled, bot responses include thumbs up (👍) and thumbs down (👎) reaction buttons for immediate quality feedback.

Upvote (Thumbs Up) Flow:

User clicks 👍 button below bot response
Interaction queued for background processing
Positive rating recorded with message token
No modal or additional UI shown (immediate acknowledgment)

Downvote (Thumbs Down) Flow:

User clicks 👎 button below bot response
Feedback modal opens asking "Why was this response unsatisfactory?"
User optionally provides detailed feedback (500 character limit)
User clicks "Downvote" to submit or "Cancel" to dismiss
Negative rating recorded with optional reason text
Modal closes automatically after submission

Rating Privacy: All ratings are associated with the message token and user ID but are not publicly visible in Slack. Analytics and quality metrics are available through ChatBotKit dashboards.

Request Processing Flow

Payload Extraction: Slack sends interaction payloads as form-encoded data with a JSON payload parameter. The endpoint:

Extracts URLSearchParams from raw request body
Retrieves payload parameter value
Parses JSON to get interaction details
Validates request signature using signing secret

Signature Validation: Like all Slack webhooks, interaction requests must pass signature validation:

Extract signature headers from request
Compute expected signature using signing secret and timestamp
Compare computed vs provided signatures
Reject invalid signatures with 403 Forbidden

Type-Based Routing: Different interaction types (block_actions, view_submission, view_closed) are routed to appropriate handlers based on payload.type field.

Immediate Acknowledgment: All interactions must be acknowledged within 3 seconds to prevent timeout errors. The endpoint returns immediately while queuing complex operations for background processing.

Response Time Requirements

Slack requires interaction endpoints to respond within 3 seconds. The endpoint meets this by:

Immediate Acknowledgment: Returns response before processing completes
Async Processing: Queues complex operations for background handling
Modal Operations: Opens modals synchronously (fast operation)
Edge Runtime: Uses edge functions for minimal cold start latency

Error Handling

Missing References: When users click "View References" but citations have expired:

Display modal with "References are no longer available" message
Provide friendly explanation that data is temporary
Log event for monitoring and debugging

Modal Opening Failures: If modal cannot be opened (invalid trigger_id, expired, or API error):

Catch and log the error with details
Show error modal explaining the issue
Return acknowledgment to prevent user-visible timeout

Malformed Payloads: When payload parsing fails or structure is unexpected:

Log parsing error with context
Trigger automatic setup validation
Return 403 Forbidden response
Prevent further processing of invalid data

Rating Processing Failures: If rating event cannot be queued:

Log error with message token and action type
Return acknowledgment to user (fail gracefully)
Retry in background if possible

Trigger ID Lifecycle

Slack provides a trigger_id with most interactions that's used to open modals:

Valid Duration: Trigger IDs expire 3 seconds after the interaction occurs Single Use: Each trigger ID can only be used once to open a modal Purpose: Prevents unauthorized modal opening and ensures timely responses

This tight deadline is why the endpoint must process interactions and open modals immediately rather than queuing them for later processing.

Troubleshooting Interactions

Buttons Not Responding:

Verify webhook URL is configured in "Interactivity & Shortcuts"
Check integration ID in URL matches your ChatBotKit integration
Ensure signing secret is correctly configured
Review interaction event logs for signature validation failures
Test with simpler interactions (upvote) to isolate complex features

Modals Not Opening:

Check that trigger_id is present in interaction payload
Verify bot token has chat:write scope
Ensure modal is opened within 3 seconds of interaction
Review Slack API response for specific error messages
Test trigger ID expiration by clicking old buttons

References Not Displaying:

Verify references feature is enabled in integration settings
Check Redis connectivity and data persistence
Review reference key generation in bot response logic
Verify reference expiration settings (TTL)
Test with freshly generated responses

Ratings Not Recording:

Confirm ratings feature is enabled in integration settings
Verify rating events are being queued successfully
Check background queue processing logs
Ensure message tokens are being generated correctly
Review rating analytics to confirm data is being stored

Authentication Failures:

Verify signing secret matches Slack app settings exactly
Check for whitespace or encoding issues in secret
Confirm requests are genuinely from Slack IP ranges
Review signature validation error logs for patterns
Test with event endpoint to verify credentials work elsewhere

Best Practices

Enable Complementary Features: Use references and ratings together for comprehensive response quality feedback. References provide transparency while ratings capture sentiment.

Monitor Modal Performance: Track how often references are viewed and ratings are provided. Low engagement may indicate unclear buttons or poor button placement.

Reference Expiration Policy: Balance storage costs with user experience. 24-48 hour expiration provides good UX while preventing unbounded data growth.

Feedback Collection: Review downvote reasons regularly to identify patterns in response quality issues and prioritize bot improvements.

Error Visibility: Display user-friendly error messages in modals rather than silent failures. Users appreciate knowing what went wrong.

Security Considerations

Signature Validation Required: All interaction requests must pass signature validation. Never process unauthenticated requests.

Private Metadata Protection: Modal private_metadata can contain sensitive information (tokens, IDs). Ensure this data is not logged or exposed inadvertently.

Rate Limiting: Users can click buttons rapidly. Implement deduplication if needed to prevent duplicate rating recordings.

Token Security: Message tokens used in ratings should be cryptographically secure random values to prevent guessing or manipulation.

Note: Interactive components significantly enhance user experience by providing rich, app-like interfaces within Slack. The combination of references (transparency) and ratings (feedback) creates a quality improvement loop that helps continuously refine bot responses.

For information about the initial bot responses that include these interactive components, see the event webhook endpoint section.

Validating Integration Setup

Verify that a Slack integration is properly configured with valid authentication credentials. The setup endpoint performs validation checks to ensure the signing secret and bot token are present and properly formatted before the integration can process events from Slack.

This endpoint is primarily used internally during integration creation and updates, but can also be called manually to troubleshoot configuration issues or verify credentials after manual changes.


POST /api/v1/integration/slack/{slackIntegrationId}/setup
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

{}
http

Validation Checks

The setup validation performs the following checks:

Signing Secret Validation:

Verifies that signingSecret field is not null or empty
Confirms the value is properly formatted
This credential is used to verify webhook requests from Slack

Bot Token Validation:

Verifies that botToken field is not null or empty
Confirms the token starts with xoxb- (bot token prefix)
This token is used to make API calls back to Slack

If either validation fails, the endpoint returns a 409 Conflict error with a descriptive message indicating which credential is missing or invalid.

When to Use Setup Validation

After Manual Credential Updates: If you've updated authentication credentials in your database or through direct API calls, run setup validation to confirm the changes are correct.

Troubleshooting Authentication Failures: When webhook requests are failing with authentication errors, use setup to verify credentials are properly configured.

Integration Health Checks: Include setup validation in monitoring scripts to ensure critical integrations remain properly configured.

Post-Migration Verification: After migrating integrations between environments or accounts, validate that credentials were transferred correctly.

Automatic Setup Invocation

The setup endpoint is automatically called in several scenarios:

During Update Operations: When you update an integration using the update endpoint, setup validation runs automatically to ensure new credentials are valid.

After Authentication Failures: When webhook requests fail signature validation, the system automatically triggers setup to diagnose and log configuration issues.

On Configuration Errors: Various integration errors trigger automatic setup checks to help identify the root cause.

Response

Success Response (200 OK):


{
  "id": "slack_xyz789"
}
json

Error Response (409 Conflict):


{
  "error": "conflict",
  "message": "No signingSecret specified"
}
json


{
  "error": "conflict",
  "message": "No botToken specified"
}
json

Troubleshooting Setup Failures

Missing Signing Secret: The integration was created without a signing secret. Update the integration with the correct value from Slack app settings under "Basic Information" → "Signing Secret".

Missing Bot Token: The integration was created without a bot token. Update the integration with the correct value from Slack app settings under "OAuth & Permissions" → "Bot User OAuth Token".

Empty Credentials: Credentials were set to empty strings. Ensure you're passing the actual credential values, not placeholder strings.

Token Format Issues: Bot tokens must start with xoxb-. If you're seeing format errors, verify you're using the bot token and not a user token (which starts with xoxp-).

Security Considerations

The setup endpoint only validates that credentials exist and are properly formatted. It does not:

Test connectivity to Slack's API
Verify OAuth scope permissions
Confirm webhook URL registration
Validate team or workspace associations

For comprehensive integration testing, send a test message through Slack and verify the bot responds correctly. This confirms that all components of the integration are working together.

Note: Setup validation is a lightweight operation that completes quickly (typically under 100ms) and can be called frequently without impacting performance or triggering rate limits.

Updating Integration Configuration

Modify an existing Slack integration's configuration, including authentication credentials, feature settings, and resource associations. Updates take effect immediately and trigger an automatic setup verification to ensure the integration continues functioning correctly.

The update endpoint accepts the same parameters as the create endpoint, allowing you to modify any aspect of your integration's configuration. When you update authentication credentials or enable new features, the integration automatically re-validates its configuration with Slack.


POST /api/v1/integration/slack/{slackIntegrationId}/update
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

{
  "name": "Updated Bot Name",
  "visibleMessages": 5,
  "references": true,
  "ratings": false
}
http

Common Update Scenarios

Rotating Credentials: If your Slack bot token or signing secret is compromised or expired, update them immediately:


{
  "signingSecret": "new_signing_secret_from_slack",
  "botToken": "xoxb-new-bot-token"
}
json

After updating credentials, the integration automatically triggers a setup validation to confirm the new credentials work correctly.

Enabling Beta Features: Activate new features like attachments or references:


{
  "attachments": true,
  "references": true,
  "ratings": true
}
json

Adjusting Context Window: Modify the number of visible messages for better context:


{
  "visibleMessages": 10
}
json

Higher values (8-10) provide more context but may increase processing time and token usage. Lower values (3-5) offer faster responses with less context.

Changing Bot Association: Switch to a different bot configuration:


{
  "botId": "bot_new_configuration"
}
json

This is useful when you've improved your bot's backstory, added new datasets, or want to test different AI models without creating a new integration.

Automatic Setup Validation

When you update an integration, the system automatically:

Validates Credentials: Confirms that signing secret and bot token are properly formatted
Tests Connectivity: Verifies the bot token has the necessary OAuth scopes
Updates Webhooks: Ensures event subscriptions are properly configured
Synchronizes State: Updates internal caches and configuration

This automatic validation helps catch configuration errors immediately rather than discovering them when users try to interact with the bot.

Update Considerations

Credential Format: The bot token must start with xoxb- and the signing secret should be a 32-character hexadecimal string. Invalid format results in validation errors.

OAuth Scopes: If you update to a new bot token, ensure it has all required OAuth scopes. Missing scopes may cause the bot to work in some contexts but fail in others (e.g., working in DMs but not in channels).

Feature Dependencies: Some features have dependencies:

attachments requires the files:read OAuth scope
references requires proper event subscription configuration
ratings works independently but provides better UX when combined with references

Session Duration Limits: The sessionDuration field accepts values from 0 to one month in milliseconds (2,592,000,000 ms). Values outside this range are rejected.

Visible Messages Range: The visibleMessages parameter accepts values from 0 to 10. Values outside this range are rejected to prevent performance issues.

Response


{
  "id": "slack_xyz789"
}
json

The response confirms the integration ID was updated successfully. After a successful update, use the fetch endpoint to retrieve the complete updated configuration.

Warning: Updating authentication credentials while the bot is actively handling conversations may cause temporary disruptions. Consider performing credential updates during low-traffic periods or notify users in advance when possible.

Note: Changes to feature flags (attachments, references, ratings) take effect immediately. Users will see new buttons and features in subsequent bot responses, but existing messages remain unchanged.

Listing Slack Integrations

Retrieve a list of all Slack integrations configured in your ChatBotKit account. This endpoint supports pagination and filtering to help you manage multiple Slack workspace integrations efficiently.

The list endpoint returns all integration configurations with sensitive credentials displayed as "********" if configured or null if not set. This allows you to verify which integrations have credentials configured without exposing the actual secret values.


GET /api/v1/integration/slack/list
Authorization: Bearer YOUR_API_TOKEN
http

Pagination Parameters

cursor (string, optional): Pagination cursor for retrieving the next page of results. Use the cursor value returned in the previous response to fetch subsequent pages.

order (string, optional): Sort order for results. Valid values are asc (ascending) or desc (descending). Default is desc, which returns the most recently created integrations first.

take (number, optional): Number of items to retrieve per page. Controls the page size for pagination.

Filtering Options

You can filter results using query parameters:

blueprintId (string, optional): Filter integrations associated with a specific blueprint ID. Useful when managing integrations organized within blueprint resources.

meta (object, optional): Filter by metadata properties. Allows custom filtering based on metadata tags or properties you've assigned to integrations.

Response Structure

The response includes an array of integration objects, each containing:

id: Unique identifier for the integration
name: Human-readable name for the integration
description: Descriptive text explaining the integration's purpose
blueprintId: Associated blueprint ID (if linked)
botId: Associated bot ID (if configured)
visibleMessages: Number of context messages included in conversations
attachments: Whether file attachments are enabled
references: Whether reference citations are enabled
ratings: Whether user feedback ratings are enabled
contactCollection: Whether contact information collection is enabled
sessionDuration: Session timeout duration in milliseconds
meta: Custom metadata object
createdAt: Timestamp when integration was created
updatedAt: Timestamp of last update

Security Note: The signingSecret, botToken, and userToken fields are intentionally excluded from list responses to prevent credential exposure. These values are write-only and should be stored securely in your own systems if needed for reference.

Example Response


{
  "items": [
    {
      "id": "slack_xyz789",
      "name": "Customer Support Bot",
      "description": "Handles customer inquiries",
      "botId": "bot_abc123",
      "visibleMessages": 10,
      "attachments": true,
      "references": true,
      "ratings": true,
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-15T10:30:00Z"
    }
  ]
}
json

For managing individual integrations, use the fetch, update, and delete endpoints described in the following sections.