Trigger

ChatBotKit Trigger Integration is a powerful feature that allows users to seamlessly send events and other types of information to their bots using a dedicated API endpoint. Once activated, the bot processes incoming information, decides on the required action, executes it - potentially using one of many available ChatBotKit Skillsets - and records the result. This integration is particularly valuable in the context of agent workflows.

You can dispatch any number of events to the trigger, and the bot will respond with appropriate actions accordingly. All activities from the interaction are logged in the Conversations tab as usual.

How to Invoke the Trigger

Invoking a trigger is done through standard HTTP POST requests using the endpoint URL provided on the ChatBotKit Trigger configuration page. Here is an example:

Replace {triggerId} and {SECRET} with your actual integration ID and secret from the trigger configuration page. The Authorization header is required when the Authenticate option is enabled for the integration (see Advanced Options below).

The request body is passed directly to your bot as the event payload. You can use any JSON structure that makes sense for your workflow.

Optional Query Parameters

You can pass these query parameters in the request URL to control session behavior and associate contacts:

• session: If provided, the bot will attempt to continue the existing conversation that matches this session ID, subject to the configured session duration. If no session is provided or the previous one has expired, a new conversation is created.
• contact.name, contact.email, contact.phone: If provided, the bot associates the event with the matching contact. If no session is used, one of these unique identifiers is used to determine the session.

All interactions, including trigger event histories, can be viewed in the Conversations tab of the dashboard.

Advanced Options

When creating or editing a trigger integration, the Advanced Options section exposes additional settings:

• Authenticate: When enabled, the integration requires an Authorization: Bearer {secret} header on every request. Disable this only in trusted, private network environments. The integration secret is shown on the trigger configuration page.
• Trigger Schedule (Pro and Team plans): Optionally configure a cron schedule so the trigger fires automatically at a set interval, without any external request. This is useful for periodic agent workflows that do not depend on inbound events.
• Timezone: The timezone used to evaluate cron and local-time schedules.
• Session Duration: Controls how long the bot keeps the same conversation open for a given session. After this period, the next event starts a new conversation. Useful when you want continuity across multiple events sent in quick succession.
• Meta: Custom key-value metadata you can attach to the integration for organizational purposes.

Triggers vs API Calls

ChatBotKit Trigger integration and Direct API Calls both serve unique needs and environments. They share many similarities but differ in key areas such as how they process events and interactions. Understanding these differences can help you utilize the right one for your specific needs.

ChatBotKit Trigger Integration

The main strength of ChatBotKit Trigger integration lies in its ability to process events in the background. Once the trigger receives an event, it schedules it for processing and immediately sends back a response, freeing up your application to continue other tasks without waiting for the bot response. This makes the trigger integration particularly suitable for scenarios where an immediate response from the bot is not required, or when you want to offload certain tasks to the background to enhance the performance of your application or simply to perform some type of job in the case of agent workflows.

In other words, it's particularly efficient for sending events and performing background tasks without the need for additional infrastructure.

Direct API Calls

Invoking direct API endpoints, on the other hand, is a synchronous process. When you send a request to a specific bot conversation endpoint via an API call, you have to wait for the bot to process the request and return a response before your application can continue. While this might potentially introduce a delay into your workflows, it also ensures that you receive an immediate response from the bot, making it suitable for scenarios where immediate feedback is required.

Summary

Using the ChatBotKit Trigger integration forms an essential part of the enhanced ChatBotKit experience. By facilitating communication to and from bots, it powerfully extends the potential applications and workflows that chatbots can be incorporated into. As such, mastering this integration will certainly open up new frontiers in your ChatBotKit usage.