--- title: Bots description: Bots are intelligent conversational agents that can interact with users, answer questions, and perform tasks using AI models and connected resources like datasets and skillsets. category: Resources/Bots tags: - bot - ai-agent - chatbot index: 1 source: - pages/api/v1/bot/create.js - pages/api/v1/bot/list.js - pages/api/v1/bot/[botId]/fetch.js - pages/api/v1/bot/[botId]/update.js - pages/api/v1/bot/[botId]/delete.js - pages/api/v1/bot/[botId]/clone.js --- Bots are the core entities in ChatBotKit that represent your conversational AI agents. Each bot combines an AI language model with custom instructions (backstory), knowledge bases (datasets), and capabilities (skillsets) to create intelligent, context-aware conversational experiences. Bots can be configured for various use cases including customer support, content generation, data analysis, and interactive assistants. They support multiple AI models, privacy controls, content moderation, and can be integrated across different communication channels. ## Creating Bots Creating a bot is the first step in building a conversational AI agent. When you create a bot, you define its personality through a backstory, select the underlying AI model that powers its intelligence, and optionally connect it to knowledge bases (datasets) and capabilities (skillsets) that extend what it can do. The bot creation process requires a name and allows you to specify various configuration options that control its behavior, capabilities, and security settings. You can configure privacy settings to prevent conversation data from being used in model training, enable content moderation to filter inappropriate content, and set visibility levels to control who can access and use the bot. ```http POST /api/v1/bot/create Content-Type: application/json { "name": "Customer Support Bot", "description": "Helpful assistant for customer inquiries", "model": "gpt-4o", "backstory": "You are a friendly customer support representative who helps users with product questions and technical issues.", "datasetId": "dataset_abc123", "privacy": true, "moderation": true } ``` The backstory is a critical parameter that defines your bot's personality, behavior, and conversational style. It provides instructions to the AI model about how to respond, what tone to use, and what information to prioritize. A well-crafted backstory ensures consistent and appropriate responses across all conversations. ## Listing Bots Retrieving a list of all bots in your account allows you to manage, organize, and access your conversational AI agents programmatically. The list endpoint supports pagination and filtering to help you efficiently work with large collections of bots. The listing operation returns comprehensive information about each bot, including its configuration, connected resources, and metadata. This is particularly useful for building administrative interfaces, monitoring bot deployments, or implementing bot selection features in your applications. ```http GET /api/v1/bot/list ``` The response includes all bots associated with your account, returned as an array of bot objects. Each bot object contains its identifier, name, description, backstory, model configuration, connected dataset and skillset IDs, and visibility settings. You can use the returned data to display bot information in user interfaces or to make programmatic decisions about which bot to use for specific tasks. Advanced filtering is supported through query parameters. You can filter bots by blueprint association to retrieve only bots that belong to a specific project or workflow. The `meta` parameter allows filtering based on custom metadata fields you've attached to your bots, enabling sophisticated organizational schemes. Pagination parameters (`cursor`, `order`, and `take`) help you efficiently retrieve large bot collections. Use the cursor-based pagination to iterate through results, and the `take` parameter to control the number of items returned per request. The `order` parameter allows sorting bots by creation date in ascending or descending order. **Tip:** Use metadata filtering to organize bots by environment (production, staging), purpose (support, sales), or any custom categorization scheme that matches your workflow. ## Fetching Bot Details Retrieving detailed information about a specific bot allows you to access its complete configuration, including the backstory, model settings, connected resources, and all customization options. This operation is essential for displaying bot information in user interfaces, verifying bot settings before starting conversations, or retrieving configuration data for programmatic bot management. The fetch operation returns the full bot object with all properties, including the AI model being used, the backstory that defines its behavior, connections to datasets and skillsets, privacy and moderation settings, and any custom metadata you've attached to the bot. ```http GET /api/v1/bot/{botId}/fetch ``` Replace `{botId}` with the unique identifier of the bot you want to retrieve. The bot ID is returned when you create a bot and can also be obtained from the bot listing endpoint. You can use either the bot's unique identifier or a custom identifier you've defined in the bot's metadata. The response includes comprehensive information about the bot's configuration. You'll receive the bot's name and description, its backstory instructions, the AI model it uses, and references to any connected datasets or skillsets. The response also includes visibility settings, privacy options, moderation settings, and timestamps indicating when the bot was created and last updated. This endpoint is particularly useful when you need to verify bot configuration before initiating conversations, display bot details to users for selection or management purposes, or retrieve specific settings like the model or backstory for auditing or analysis. **Security Note:** Only bots that belong to your account can be fetched. Attempting to retrieve a bot that doesn't exist or belongs to another user will result in an error response. ## Updating Bots Updating a bot allows you to modify its configuration, behavior, and connected resources after creation. This is essential for refining bot performance, adjusting its personality, changing the underlying AI model, connecting or disconnecting datasets and skillsets, or updating security and visibility settings. You can update any aspect of your bot including its name, description, backstory, model, connected resources, privacy settings, moderation options, and visibility. The update operation is flexible, allowing you to modify only the specific fields you want to change while leaving others unchanged. ```http POST /api/v1/bot/{botId}/update Content-Type: application/json { "name": "Advanced Support Bot", "backstory": "You are an expert technical support representative with deep product knowledge.", "model": "gpt-4o", "datasetId": "dataset_xyz789", "privacy": true, "moderation": true } ``` Updating the backstory is a powerful way to refine your bot's behavior without creating a new bot. You can adjust the tone, add new instructions, or modify how the bot should handle specific scenarios. Changes to the backstory take effect immediately for all new conversations. Switching the AI model can significantly impact your bot's capabilities and performance characteristics. Different models offer varying levels of intelligence, response quality, speed, and cost. Consider testing model changes in a development environment before applying them to production bots that are actively serving users. Connecting or disconnecting datasets and skillsets allows you to dynamically adjust your bot's knowledge base and capabilities. When you connect a new dataset, the bot gains access to that information for answering questions. Similarly, connecting skillsets enables new abilities that the bot can use during conversations. ## Deleting Bots Deleting a bot permanently removes it from your account along with its configuration and settings. This operation is irreversible and should be used carefully, especially for bots that are actively deployed or integrated into production systems. When you delete a bot, the bot entity itself is removed, including its name, description, backstory, model configuration, and all associated settings. However, the operation does not delete connected resources like datasets or skillsets, which remain available for use with other bots or applications. ```http POST /api/v1/bot/{botId}/delete Content-Type: application/json {} ``` The deletion process handles cleanup of bot-related data, including conversation associations and session tokens. Any active conversations using this bot will be affected, so it's important to ensure that the bot is not currently serving users before deletion. Consider archiving or disabling bots instead of deleting them if you want to preserve historical data or maintain the ability to restore bot functionality in the future. You can use visibility settings to make a bot private or update its configuration to prevent it from being used while keeping it available for reference. Before deleting a bot that's integrated into applications or communication channels, make sure to update or remove those integrations to prevent errors or service disruptions. Check for any dependencies on the bot in your workflows, automation rules, or API integrations. **Warning:** Bot deletion is permanent and cannot be undone. Make sure you have backups of any critical configuration data, including the backstory and settings, before proceeding with deletion. Consider exporting bot configuration or cloning the bot before deletion if you might need to recreate it later. ## Cloning Bots Cloning a bot creates an exact duplicate with the same configuration, backstory, model settings, and connected resources. This operation is useful for creating variations of existing bots, testing configuration changes without affecting production bots, or quickly deploying similar bots for different purposes or environments. The cloning process copies all bot properties including the name, description, backstory, AI model, dataset and skillset connections, privacy settings, moderation configuration, and custom metadata. The cloned bot receives a new unique identifier and is created as an independent entity that can be modified without affecting the original. ```http POST /api/v1/bot/{botId}/clone Content-Type: application/json {} ``` After cloning, you'll receive the ID of the newly created bot, which you can immediately use for conversations or update with different settings. The cloned bot starts with identical configuration but operates independently, allowing you to experiment with changes or deploy it to different channels without risk to the original bot. This feature is particularly valuable when creating bot variations for different departments, languages, or use cases. You can clone a well-tuned bot and then modify specific aspects like the backstory or connected datasets to adapt it for new purposes while maintaining the core functionality that works well. Cloned bots are not associated with any blueprint, even if the original bot was part of one. This ensures that clones remain independent and don't inherit blueprint-level constraints or relationships. If you need the cloned bot to be part of a blueprint, you can update it after creation to establish that connection. Common use cases for bot cloning include creating development and production versions of the same bot, deploying regional variations with localized instructions, building A/B testing scenarios to compare different approaches, and quickly spinning up multiple specialized bots based on a proven template. **Tip:** After cloning, update the bot's name and description to clearly distinguish it from the original and prevent confusion when managing multiple bots.