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.

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.

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