Trigger Integrations

ChatBotKit Trigger Integration is a powerful feature that enables event-driven workflows by allowing external applications and services to send events and information to your bots through a dedicated API endpoint. Once a trigger receives an event, it schedules the event for background processing, allowing your application to continue without waiting for a response. The bot then processes the event, determines the required actions, executes them using available skillsets, and records the results in the conversation history.

This integration is particularly valuable for agent workflows, scheduled tasks, and scenarios where immediate bot responses aren't required. All trigger interactions are logged in the Conversations tab for tracking and auditing.

Creating a Trigger Integration

Creating a trigger integration establishes a dedicated endpoint that can receive events from your applications. During creation, you configure the trigger's behavior, including authentication requirements, session management, and bot linkage.

To create a trigger integration, send a POST request with configuration details:

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

{
  "name": "Order Processing Trigger",
  "description": "Handles order processing events",
  "botId": "bot_abc123",
  "authenticate": true,
  "sessionDuration": 3600000
}

http

Important Configuration Options:

  • botId: The bot that will process trigger events (required)
  • authenticate: When enabled, requests must include authentication
  • triggerSchedule: Optional cron schedule for recurring trigger execution
  • sessionDuration: How long conversations persist (in milliseconds)
  • blueprintId: Optional blueprint for resource grouping

When a trigger integration is created, the system generates a unique secret key that can be used for authentication. This secret is returned in the response and should be stored securely if authentication is enabled.

Warning: The trigger secret is only displayed once during creation. Store it securely for future use with authenticated requests.

Sending Events to Trigger Integrations

The event endpoint is the primary way to send data and trigger bot execution through Trigger Integrations. When you send an event to this endpoint, ChatBotKit queues it for background processing, allowing your application to continue immediately without waiting for the bot to complete its work. The bot processes the event asynchronously, executes any configured actions through its skillsets, and records all results in the conversation history for auditing and tracking.

This endpoint is designed for maximum flexibility, accepting events via both GET and POST requests, supporting optional contact information for personalized interactions, and enabling session-based conversation continuity. It's the cornerstone of event-driven bot workflows, agent systems, scheduled tasks, and automated background processing scenarios where immediate responses aren't required but reliable execution and tracking are essential.

Event Endpoint URL Structure

Each trigger integration has a unique event endpoint URL constructed from its ID:

https://api.chatbotkit.com/v1/integration/trigger/{triggerIntegrationId}/event

Replace {triggerIntegrationId} with your trigger's actual identifier. You can obtain this ID from the response when creating the trigger or by listing your trigger integrations.

Sending Events via POST (Recommended)

The recommended approach for sending events is using POST requests with a JSON or text body containing the event data:

POST /api/v1/integration/trigger/{triggerIntegrationId}/event
Content-Type: application/json
Authorization: Bearer your_trigger_secret

{
  "order_id": "12345",
  "customer": "John Smith",
  "total": 99.99,
  "status": "pending"
}

http

The body content can be any valid text, JSON, or structured data that your bot needs to process. The bot receives the entire body as context and can use it to make decisions and take actions.

Sending Events via GET

For simple scenarios or when POST requests aren't feasible, you can trigger events using GET requests. This is useful for webhooks from third-party services that only support GET callbacks:

GET /api/v1/integration/trigger/{triggerIntegrationId}/event?session=user123
Authorization: Bearer your_trigger_secret

http

With GET requests, the body is empty by default. Use query parameters to pass session and contact information.

Authentication

If your trigger integration has authentication enabled (the authenticate field is true), you must include the trigger's secret in the Authorization header:

Authorization: Bearer {trigger_secret}

The secret is provided when you create the trigger or can be retrieved using the fetch endpoint. Store this secret securely - anyone with access to it can send events to your trigger.

Security Note: For production triggers handling sensitive data, always enable authentication to prevent unauthorized event submissions. Without authentication, anyone who knows your trigger ID can send events to it.

Session Management and Contact Information

The event endpoint supports optional query parameters for maintaining conversation continuity and associating events with specific contacts:

Session Parameter:

POST /api/v1/integration/trigger/{triggerIntegrationId}/event?session=checkout_abc123

http

The session parameter groups related events into the same conversation, allowing the bot to maintain context across multiple events. This is essential for multi-step workflows where the bot needs to remember previous interactions.

Contact Parameters:

Associate events with contacts by providing contact information:

POST /api/v1/integration/trigger/{triggerIntegrationId}/event?contact.name=John+Smith&contact.email=john@example.com&contact.phone=555-0123

http

Alternative parameter formats are also supported:

?contact_name=John+Smith&contact_email=john@example.com&contact_phone=555-0123

http

When contact information is provided, ChatBotKit automatically creates or updates contact records, enabling personalized interactions and contact-scoped conversation history. The bot can reference contact information during processing for more contextual responses.

Event Processing Flow

Understanding the event processing lifecycle helps you design effective trigger-based workflows:

  1. Event Reception: Your application sends an event to the trigger endpoint
  2. Immediate Acknowledgment: The endpoint returns success immediately, queuing the event for background processing
  3. Session Management: ChatBotKit checks for an existing session or creates a new conversation based on the session parameter
  4. Contact Resolution: If contact information is provided, creates or updates the associated contact record
  5. Bot Invocation: The configured bot receives the event data and conversation context
  6. Action Execution: The bot processes the event, potentially executing skillset actions like API calls, database queries, or notifications
  7. History Recording: All interactions, decisions, and action results are recorded in the conversation history

Response Behavior

The event endpoint returns an immediate success response after queuing the event:

{
  "ok": true
}

json

This response indicates the event was successfully queued, not that the bot has finished processing it. The bot executes asynchronously in the background. To monitor execution results, check the Conversations tab in your ChatBotKit dashboard or use the conversation API to retrieve the conversation history associated with the trigger integration.

Practical Examples

Example 1: Order Processing Workflow

POST /api/v1/integration/trigger/trigger_abc123/event?session=order_12345&contact.email=customer@example.com
Authorization: Bearer abc123secret
Content-Type: application/json

{
  "event": "order_created",
  "order_id": "12345",
  "amount": 149.99,
  "items": ["SKU-001", "SKU-042"],
  "shipping_address": "123 Main St, Anytown, USA"
}

http

The bot can process this order, validate inventory, send confirmation emails, update databases, and notify fulfillment systems - all automatically in the background.

Example 2: Scheduled Report Generation

POST /api/v1/integration/trigger/trigger_def456/event?session=daily_report
Authorization: Bearer def456secret
Content-Type: text/plain

Generate daily sales report for 2024-01-15

http

The bot executes on schedule, retrieves sales data, generates the report, and sends it to designated recipients.

Example 3: Simple GET-based Webhook

GET /api/v1/integration/trigger/trigger_ghi789/event?session=monitoring&contact_name=System+Monitor
Authorization: Bearer ghi789secret

http

Useful for health checks, monitoring systems, or third-party services that only support GET webhooks.

Error Handling

The endpoint returns standard HTTP error codes for common issues:

  • 401 Unauthorized: Authentication required but missing or invalid credentials
  • 404 Not Found: Trigger integration doesn't exist or has been deleted
  • 400 Bad Request: Malformed request or invalid parameters
  • 500 Internal Server Error: Server-side processing error

Always implement retry logic with exponential backoff for transient errors, especially in production systems sending high-volume events.

Best Practices

Use Descriptive Sessions: Name sessions based on their purpose (e.g., user_123_checkout or report_2024_01) to make conversation history easier to navigate and debug.

Include Context in Events: Send all relevant information in the event body that the bot might need for decision-making. Avoid requiring the bot to make additional API calls to retrieve basic context.

Monitor Conversation History: Regularly review the conversations created by your trigger to ensure the bot is processing events correctly and taking expected actions.

Implement Idempotency: Design your event-sending logic to handle duplicate submissions gracefully, as network issues may cause retries.

Secure Your Secrets: Never commit trigger secrets to version control or expose them in client-side code. Use environment variables or secure configuration management systems.

Test with Varied Payloads: Before deploying to production, test your trigger with diverse event payloads to ensure the bot handles edge cases and malformed data appropriately.

For detailed information about configuring trigger integrations and managing authentication, refer to the trigger integration creation documentation.

Deleting a Trigger Integration

Deleting a trigger integration permanently removes the trigger and its configuration, including the associated endpoint URL and authentication credentials. This operation is irreversible and will prevent any further events from being processed through this trigger.

To delete a trigger integration, send a POST request:

POST /api/v1/integration/trigger/{triggerIntegrationId}/delete
Content-Type: application/json

{}

http

Replace {triggerIntegrationId} with the unique identifier of the trigger you want to delete.

Important Considerations:

Before deleting a trigger integration, ensure that:

  • No external systems are actively sending events to this trigger
  • You have documented or backed up any important configuration details
  • Associated conversation history is preserved if needed (conversations remain in the system)
  • You understand that the trigger's secret key will be invalidated

What Gets Deleted:

  • The trigger integration configuration
  • The unique trigger endpoint URL
  • The authentication secret
  • Associated scheduled execution (if configured)

What Remains:

  • Historical conversation data from trigger events
  • The associated bot (unaffected by trigger deletion)
  • Any blueprint associations (not deleted)

Response:

{
  "id": "trigger_abc123"
}

json

After deletion, any attempts to send events to the trigger's endpoint URL will fail with an error. Update your external systems to stop sending events before or immediately after deletion to avoid failed requests.

Fetching a Trigger Integration

Retrieving a specific trigger integration provides detailed configuration information, including the secret key required for authentication, endpoint URL, and all associated settings. This is essential when you need to reference trigger credentials or verify configuration details.

To fetch a trigger integration, send a GET request with the trigger ID:

GET /api/v1/integration/trigger/{triggerIntegrationId}/fetch

http

Replace {triggerIntegrationId} with your trigger's unique identifier.

The response includes complete trigger configuration:

{
  "id": "trigger_abc123",
  "name": "Order Processing Trigger",
  "description": "Handles order processing events",
  "botId": "bot_xyz789",
  "secret": "1a2b3c4d5e6f...",
  "authenticate": true,
  "triggerSchedule": null,
  "sessionDuration": 3600000,
  "blueprintId": null,
  "meta": {},
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

json

Key Response Fields:

  • secret: The authentication secret for this trigger (store securely)
  • botId: The bot that processes events sent to this trigger
  • authenticate: Indicates whether authentication is required
  • triggerSchedule: Cron expression for scheduled execution (if configured)
  • sessionDuration: Conversation session persistence time in milliseconds

Constructing the Event Endpoint:

Use the trigger ID to construct the event endpoint URL:

https://api.chatbotkit.com/v1/integration/trigger/{triggerIntegrationId}/event

This is the URL your applications will use to send events to the trigger.

Invoking a Trigger Integration

The invoke endpoint manually triggers execution of a trigger integration, useful for testing, debugging, or forcing immediate execution outside of normal event flows. This bypasses the standard event endpoint and directly queues the trigger for processing with the configured schedule.

To invoke a trigger integration, send a POST request:

POST /api/v1/integration/trigger/{triggerIntegrationId}/invoke
Content-Type: application/json

{}

http

Replace {triggerIntegrationId} with your trigger's unique identifier.

Use Cases for Manual Invocation:

  • Testing: Verify that your trigger configuration works correctly
  • Debugging: Troubleshoot trigger behavior without external dependencies
  • Manual Execution: Force trigger execution outside of scheduled times
  • Development: Test trigger workflows during development and integration

How Invocation Works:

When you invoke a trigger, the system:

  1. Queues an invoke event for the trigger
  2. Processes the event using the trigger's configured schedule settings
  3. Executes the associated bot with the trigger context
  4. Records the interaction in conversation history

Invoke vs Event Endpoint:

The invoke endpoint differs from the standard event endpoint:

  • Invoke: Administrative operation for testing and manual execution
  • Event: Production endpoint for receiving external events with custom payloads

Use the event endpoint (/event) for normal trigger operations where you need to pass custom data and payloads. Use invoke for testing and manual execution scenarios.

Response:

{
  "id": "trigger_abc123"
}

json

The response confirms that the trigger has been queued for execution. The actual processing happens asynchronously in the background. Monitor the Conversations tab to see the results of the triggered execution.

Note: If the trigger has a configured schedule (triggerSchedule), the invocation will respect that schedule's settings during execution.

Setting Up a Trigger Integration

The setup endpoint performs initialization tasks for a trigger integration, preparing it for use with external systems. This operation validates the trigger configuration and performs any necessary setup procedures to ensure the integration is ready to receive and process events.

To set up a trigger integration, send a POST request:

POST /api/v1/integration/trigger/{triggerIntegrationId}/setup
Content-Type: application/json

{}

http

Replace {triggerIntegrationId} with your trigger's unique identifier.

When to Use Setup:

Call the setup endpoint after creating a trigger integration or when configuration changes require reinitialization. The setup process:

  1. Validates the trigger configuration
  2. Verifies bot association and permissions
  3. Initializes any required resources
  4. Prepares the trigger for event processing

Setup Process Details:

The setup operation is typically quick and returns immediately with a confirmation. If the trigger is already properly configured, the setup process will complete without making changes. This makes it safe to call setup multiple times.

Response:

{
  "id": "trigger_abc123"
}

json

After successful setup, the trigger is ready to receive events through its event endpoint. You can begin sending events immediately using the trigger's event URL and authentication credentials.

Note: Setup is optional for most use cases. Triggers are typically ready to use immediately after creation unless specific initialization is required for your integration scenario.

Updating a Trigger Integration

Update an existing Trigger Integration's configuration to modify its behavior, authentication requirements, scheduling, or linked resources. This endpoint allows you to adjust trigger settings without recreating the integration, preserving its unique endpoint URL and existing conversation history.

Updating a trigger integration is particularly useful when you need to: change the bot handling events, modify authentication requirements, adjust session duration for conversation persistence, or update the trigger schedule for recurring automated executions. All changes take effect immediately for new incoming events while preserving historical data.

POST /api/v1/integration/trigger/{triggerIntegrationId}/update
Content-Type: application/json

{
  "name": "Updated Order Processor",
  "description": "Enhanced order processing with fraud detection",
  "botId": "bot_xyz789",
  "authenticate": true,
  "triggerSchedule": "0 0 * * *",
  "sessionDuration": 7200000
}

http

Key Configuration Updates

Bot Switching: Changing the botId redirects all future events to a different bot. This is useful when upgrading to improved bot versions or splitting functionality across specialized bots. Existing conversations remain accessible in the original bot's history.

Authentication Changes: You can enable or disable authentication by updating the authenticate parameter. When enabling authentication on a previously open trigger, ensure you have the integration's secret key available. Disabling authentication makes the trigger publicly accessible.

Schedule Modifications: The triggerSchedule parameter accepts standard cron syntax for recurring trigger executions. Use this for periodic tasks like hourly data syncs (0 * * * *), daily reports (0 0 * * *), or custom intervals. Setting this to null disables scheduled execution.

Session Duration: Adjust how long the bot maintains conversation context between events. Longer durations (in milliseconds) enable more coherent multi-event workflows but consume more memory. Shorter durations are suitable for independent, stateless event processing.

Blueprint Reassignment: Updating the blueprintId allows you to switch between different resource configurations, applying new datasets, skillsets, or abilities to the trigger integration. This enables rapid deployment of configuration changes across multiple integrations.

Update Best Practices

Test Before Production: When changing critical settings like bot IDs or authentication, test the updated configuration with sample events before deploying to production workflows.

Gradual Migration: For major changes, consider creating a new trigger integration and gradually migrating traffic rather than updating a high-volume production trigger directly.

Monitor After Updates: Check conversation logs after updates to ensure events are processing correctly with the new configuration. Pay special attention to authentication-related changes that might block legitimate requests.

Document Changes: Maintain records of significant configuration changes, especially schedule modifications or bot switches, to aid troubleshooting and maintain operational history.

Warning: Changing authentication settings affects all future requests immediately. Ensure external systems are updated with proper credentials before enabling authentication, or you may block legitimate event submissions.

Listing Trigger Integrations

Retrieving your trigger integrations allows you to view all configured triggers, their settings, and associated secrets. This is useful for managing multiple triggers, auditing configurations, and retrieving endpoint URLs and authentication credentials.

To list all trigger integrations, send a GET request:

GET /api/v1/integration/trigger/list

http

The response includes comprehensive information about each trigger:

  • id: Unique identifier for the trigger integration
  • secret: Authentication secret (if authentication is enabled)
  • botId: The bot assigned to process trigger events
  • authenticate: Whether authentication is required
  • triggerSchedule: Cron schedule for recurring execution (if configured)
  • sessionDuration: How long conversation sessions persist
  • blueprintId: Associated blueprint (if any)

Pagination Support:

The list endpoint supports pagination using cursor-based navigation:

GET /api/v1/integration/trigger/list?cursor=abc123&take=20&order=desc

http
  • cursor: Pagination cursor for retrieving the next page
  • take: Number of items to retrieve (default varies)
  • order: Sort order - asc or desc (default: desc)

You can also filter results using blueprint association:

GET /api/v1/integration/trigger/list?blueprintId=blueprint_xyz

http
Go to cbk.ai