Tasks

Tasks represent automated actions that can be executed on a schedule or triggered on-demand within the ChatBotKit platform. They enable you to build powerful automation workflows by allowing bots to perform operations at specific times or in response to events, without manual intervention.

A task combines a bot with a schedule and optional contact, creating an automated workflow that executes according to your defined parameters. Tasks are particularly useful for periodic notifications, scheduled data processing, automated reporting, or any operation that needs to run at regular intervals or be triggered programmatically.

Creating Tasks

Creating a task establishes an automated workflow by connecting a bot with a schedule and optional configuration parameters. Tasks can be scheduled to run at regular intervals (quarterhourly, halfhourly, hourly, daily, weekly, monthly) or triggered manually through the API.

When creating a task, you specify the bot that will handle the execution, the schedule defining when it should run, and optional parameters like session duration and contact associations. The system automatically manages task execution based on your schedule configuration.

To create a task, send a POST request with the required parameters:

The schedule parameter accepts predefined intervals: quarterhourly, halfhourly, hourly, daily, weekly, monthly, or a custom cron expression for more complex scheduling needs. The sessionDuration parameter (in milliseconds) controls how long the conversation session remains active, with a maximum of one hour.

Important: The botId is required and cannot be null or empty. The bot must exist and be accessible by your account before creating the task. Once created, the task will automatically calculate the next run time based on your schedule.

Listing Tasks

Retrieving a list of your tasks allows you to view all automated workflows configured in your account. The list endpoint provides pagination support and filtering capabilities to help you manage large collections of tasks efficiently.

The list endpoint returns tasks in reverse chronological order by default (most recently created first), with support for cursor-based pagination to handle large datasets. Each task in the response includes its configuration details, schedule information, and associated resource identifiers.

To retrieve your tasks, send a GET request:

For paginated results, you can specify query parameters:

The take parameter controls how many tasks to retrieve per page (default behavior applies if not specified). The order parameter accepts asc or desc to control sorting direction. The cursor parameter is used for pagination, allowing you to fetch subsequent pages of results by providing the cursor from the previous response.

Each task object in the response includes essential fields like id, name, description, schedule, botId, contactId, and timestamps. You can use this information to display task dashboards, monitor active automation workflows, or build management interfaces for your task automation system.

Note: Tasks are automatically filtered to show only those belonging to your account. Pagination cursors are designed for forward traversal through your task collection.

Exporting Tasks

The export endpoint provides a convenient way to extract your task configurations in multiple formats, enabling backup, migration, or integration with external systems. Unlike the list endpoint, export is specifically designed for bulk data retrieval and format conversion.

This endpoint supports multiple output formats including JSON, JSONL (JSON Lines), and CSV, making it easy to integrate task data with spreadsheets, data processing pipelines, or backup systems. The JSONL format is particularly useful for streaming large datasets, while CSV provides compatibility with spreadsheet applications.

To export your tasks in JSON format:

For CSV export, which is ideal for spreadsheet applications:

The export endpoint includes the same pagination parameters as the list endpoint, allowing you to export tasks in batches. However, exported data includes additional formatting for the specified output type. For example, in CSV format, the meta field is serialized as YAML for better readability and compatibility.

Pagination parameters work identically to the list endpoint, supporting cursor, order, and take query parameters. This allows you to export large task collections in manageable chunks or create incremental backups of your automation configurations.

Use Case: Export is particularly valuable when migrating between environments, creating backups of your automation workflows, or integrating task data with external monitoring and reporting systems.

Fetching a Task

Retrieving a specific task by its ID allows you to inspect the complete configuration and current state of an automated workflow. This is essential for monitoring task execution, debugging scheduling issues, or displaying task details in user interfaces.

The fetch endpoint returns comprehensive information about a single task, including all configuration parameters, schedule settings, associated resources (bot and contact IDs), and metadata. This detailed view enables you to verify task configuration, check execution status, and ensure your automation workflows are properly configured.

To retrieve a specific task, use its unique identifier:

For example, to fetch a task with ID "task_abc123":

The response includes all task properties such as name, description, schedule, botId, contactId, sessionDuration, and meta, along with timestamps indicating when the task was created and last updated. You can also check the nextRunAt field to see when the task is scheduled to execute next.

This endpoint is particularly useful when you need to display task details in a management interface, verify task configuration before making updates, or retrieve task metadata for monitoring and logging purposes. The returned data provides everything needed to understand and manage the automated workflow.

Updating a Task

Modifying an existing task allows you to adjust automation workflows as your requirements evolve. You can change schedules, update bot associations, modify session parameters, or adjust any other task configuration without recreating the entire task.

The update endpoint accepts the same parameters as task creation, applying only the fields you provide while preserving existing values for omitted fields. This partial update capability makes it easy to modify specific aspects of a task without affecting its other configurations.

When you update a task's schedule, the system automatically recalculates the next run time based on the new schedule. This ensures that schedule changes take effect immediately and tasks execute at the correct times according to your updated configuration.

To update a task, send a POST request with the fields you want to modify:

For example, to change a task's schedule and session duration:

Important: Updating the schedule will immediately recalculate the next run time. If the task is currently scheduled to run, the update will take effect after the current execution completes.

Deleting a Task

Removing a task permanently deletes the automation workflow and stops all future executions. This operation is irreversible and should be used when a task is no longer needed or needs to be completely removed from your automation configuration.

When a task is deleted, the system immediately stops scheduling it for future execution. Any pending executions that haven't started yet will be cancelled. However, if the task is currently executing at the time of deletion, that execution will be allowed to complete before the task is fully removed.

Deleting a task does not affect the associated bot or any conversations that were created by the task. These resources remain intact and can continue to be used by other tasks or directly through the API. Only the task automation configuration itself is removed.

To delete a task, send a POST request with an empty body:

For example, to delete a task with ID "task_abc123":

The endpoint returns the ID of the deleted task in the response, confirming the deletion was successful. After deletion, attempting to fetch, update, or trigger the task will result in a "not found" error.

Warning: This operation cannot be undone. If you need to preserve task configuration for future reference, consider exporting your tasks before deletion or temporarily disabling the task by setting its schedule to "never" instead of deleting it entirely. Always verify you're deleting the correct task before confirming the operation.

Triggering a Task

Manually triggering a task executes it immediately, bypassing the configured schedule. This is valuable for running tasks on-demand in response to external events or executing workflows outside their normal schedule without modifying the task configuration.

When you trigger a task, it queues for immediate execution while maintaining its regular schedule for future automated runs. The trigger operation doesn't modify the task's schedule or next run time - it simply creates an additional execution instance that runs as soon as resources are available.

Task triggering is asynchronous. The API endpoint queues the task for execution and returns immediately, confirming that the trigger request was received. The actual task execution happens in the background, creating a conversation with the configured bot and processing the task's instructions.

To trigger a task manually, send a POST request:

For example, to trigger a task with ID "task_abc123":

The task executes with the same configuration and context as scheduled runs, including the associated bot, contact, session duration, and any configured metadata. The execution creates or reuses a conversation session according to the task's session management settings.

Use Cases: Manual triggering is ideal for responding to external events like webhooks or user actions, running maintenance tasks on-demand, or executing tasks that don't require a regular schedule. The lastRunAt timestamp is updated when triggered executions complete.

Note: Task triggering is subject to your account's conversation limits and plan restrictions. Ensure you have sufficient quota before triggering tasks, especially when triggering multiple tasks simultaneously.