.d8888b. 888888b. 888 d8P
d88P Y88b 888 "88b 888 d8P
888 888 888 .88P 888 d8P
888 8888888K. 888d88K
888 888 "Y88b 8888888b
888 888 888 888 888 Y88b
Y88b d88P 888 d88P 888 Y88b
"Y8888P" 8888888P" 888 Y88b .ai

ChatBotKit Python SDK

The official async Python SDK for ChatBotKit - a platform for building and deploying conversational AI applications. With ChatBotKit you can create bots and agents with custom data, skillsets, and integrations while keeping AI orchestration on the ChatBotKit platform.

Why ChatBotKit?

Build lighter, future-proof AI agents. When you build with ChatBotKit, the heavy lifting happens on our servers, not in your application. This architectural advantage delivers:

• 🪶 Lightweight Agents: Your agents stay lean because complex AI processing, model orchestration, and tool execution happen server-side. Less code in your app means faster load times and simpler maintenance.

• 🛡️ Robust & Streamlined: Server-side processing provides a more reliable experience with built-in error handling, automatic retries, and consistent behavior across all platforms.

• 🔄 Backward & Forward Compatible: As AI technology evolves with new models, new capabilities, and new paradigms, your agents automatically benefit. No code changes required on your end.

• 🔮 Future-Proof: Agents you build today will remain capable tomorrow. When we add support for new AI models or capabilities, your existing agents gain those powers without any updates to your codebase.

This means you can focus on building great user experiences while ChatBotKit handles the complexity of the ever-changing AI landscape.

Installation

pip install chatbotkit

You can also install directly from GitHub:

pip install "chatbotkit @ git+https://github.com/chatbotkit/python-sdk.git"

Requires Python 3.10 or later. The SDK is fully async and built on httpx.

To use the optional agent helpers, install the agent extra:

pip install "chatbotkit[agent]"

Or install the agent extra directly from GitHub:

pip install "chatbotkit[agent] @ git+https://github.com/chatbotkit/python-sdk.git"

Then import from chatbotkit.agent:

fromchatbotkit.agentimportTool, execute

Development Checks

From sdks/python, run the same checks used by CI:

pip install -e ".[dev]"
python -m pytest tests
python -m compileall -q chatbotkit examples
python -m build
python -m twine check dist/*

The GitHub Actions workflow builds and checks publishable sdist and wheel artifacts. Publishing is manual and disabled by default until PyPI trusted publishing is configured.

Quick Start

importasynciofromchatbotkitimportChatBotKitfromchatbotkit.typesimportConversationCompleteStreamItemTypeasyncdefmain():
asyncwithChatBotKit(secret="your-api-key") ascbk:
completion=cbk.conversation.complete(
None,
{
"messages": [
{"type": "user", "text": "Hello! Tell me a joke."},
],
},
)
asyncforeventincompletion.stream():
ifevent.type==ConversationCompleteStreamItemType.TOKEN:
print(event.data.token, end="", flush=True)
asyncio.run(main())

SDK Client

Create a client with your API key and access resources as attributes:

fromchatbotkitimportChatBotKitcbk=ChatBotKit(
secret="your-api-key",
base_url="https://api.chatbotkit.com", # optionalrun_as_user_id="user-id", # optionaltimezone="America/New_York", # optional
)
cbk.bot# Bot managementcbk.conversation# Conversation managementcbk.dataset# Dataset management (cbk.dataset.record)cbk.skillset# Skillset management (cbk.skillset.ability)cbk.file# File managementcbk.contact# Contact management (cbk.contact.conversation/secret/space/task)cbk.secret# Secret managementcbk.memory# Memory managementcbk.blueprint# Blueprint management (cbk.blueprint.resource/bulletin)cbk.task# Task management (cbk.task.execution)cbk.team# Team managementcbk.space# Space management (cbk.space.storage)cbk.partner# Partner management (cbk.partner.user.token)cbk.policy# Policy managementcbk.portal# Portal managementcbk.usage# Usage reporting (cbk.usage.series)cbk.magic# Magic AI generation (cbk.magic.prompt)cbk.event# Event log access (cbk.event.log)cbk.graphql# GraphQL operationscbk.channel# Channel publish/subscribecbk.platform# Platform content (doc, example, manual, model, tutorial, ...)cbk.integration# Integrations (widget, slack, discord, whatsapp, telegram,# messenger, instagram, notion, sitemap, support, extract,# twilio, email, mcp_server, microsoft_teams, google_chat,# trigger)

The client manages an underlying httpx.AsyncClient. Use it as an async context manager (async with ChatBotKit(...) as cbk:) or call await cbk.aclose() when you are done to release the connection pool.

Every resource method returns an awaitable Response. await it to parse a normal JSON response, or call .stream() to iterate over a JSONL stream:

# Awaiting a response parses the JSON body into a typed objectbots=awaitcbk.bot.list({"take": 10})
# Streaming iterates over typed stream items as they arriveasyncforitemincbk.bot.list({"take": 10}).stream():
print(item.type, item.data.id)

Methods accept either a generated request/params object from chatbotkit.types or a plain dict. Generated objects are serialized automatically.

Resource Operations

Bots

# List botsbots=awaitcbk.bot.list({"take": 10})
# Fetch a botbot=awaitcbk.bot.fetch("bot-id")
# Create a botbot=awaitcbk.bot.create({
"name": "My Bot",
"description": "A helpful assistant",
"backstory": "You are a friendly AI assistant.",
})
# Update a botbot=awaitcbk.bot.update("bot-id", {"name": "Updated Bot Name"})
# Delete a botresult=awaitcbk.bot.delete("bot-id")

Conversations

# Create a conversationconversation=awaitcbk.conversation.create({})
# List conversationsconversations=awaitcbk.conversation.list({"take": 10})
# Continue an existing conversationresult=awaitcbk.conversation.complete("conversation-id", {
"messages": [{"type": "user", "text": "Hello!"}],
})
# Or use the stateless endpoint by passing None as the conversation idresult=awaitcbk.conversation.complete(None, {
"messages": [{"type": "user", "text": "Hello!"}],
})

Datasets

# Create a datasetdataset=awaitcbk.dataset.create({"name": "Knowledge Base"})
# Add a recordrecord=awaitcbk.dataset.record.create("dataset-id", {
"text": "Important information...",
})
# Search the datasetresults=awaitcbk.dataset.search("dataset-id", {"text": "search query"})

Integrations

Each integration is reachable under cbk.integration and follows the same CRUD shape, with a few integration-specific extras (setup, initiate, sync):

# List Slack integrationsslack=awaitcbk.integration.slack.list({"take": 10})
# Create a widget integrationwidget=awaitcbk.integration.widget.create({"name": "Website Widget"})
# Trigger a sync for a sitemap integrationawaitcbk.integration.sitemap.sync("integration-id")

The full list of resources is shown under SDK Client above.

Streaming

Completions and list endpoints support streaming. Call .stream() on the returned Response to get an async iterator of typed stream items. Each item has a type (an enum) and a data payload:

fromchatbotkit.typesimportConversationCompleteStreamItemTypecompletion=cbk.conversation.complete(None, {
"messages": [{"type": "user", "text": "Write a short poem."}],
})
asyncforeventincompletion.stream():
ifevent.type==ConversationCompleteStreamItemType.TOKEN:
print(event.data.token, end="", flush=True)
elifevent.type==ConversationCompleteStreamItemType.RESULT:
print("\nDone!")

Configuration Options

Options can be passed as keyword arguments or via a ClientOptions instance.

Option	Description
secret	API authentication token (required)
base_url	Custom API base URL
run_as_user_id	Execute requests as a specific user
run_as_child_user_email	Execute requests as a specific child user
timezone	Timezone for timestamp handling
headers	Extra headers to send with every request
timeout	Request timeout in seconds
transport	Custom httpx transport (useful for testing)

fromchatbotkitimportChatBotKit, ClientOptionscbk=ChatBotKit(ClientOptions(secret="your-api-key", timezone="UTC"))

Error Handling

Failed requests raise APIError, which carries the message, code, status, and URL returned by the API:

fromchatbotkitimportAPIErrortry:
bot=awaitcbk.bot.fetch("invalid-id")
exceptAPIErroraserror:
print(error.status_code, error.code, error.message)

Types

The chatbotkit.types module contains all request, response, and stream item types, generated from the ChatBotKit OpenAPI specification. Each type provides from_dict and to_dict helpers, and passing typed objects to resource methods is fully supported:

fromchatbotkit.typesimportBotCreateRequestbot=awaitcbk.bot.create(BotCreateRequest.from_dict({
"name": "My Bot",
"description": "Description",
}))

Documentation

• Platform Documentation: Comprehensive guide to ChatBotKit here.
• Platform Tutorials: Step-by-step tutorials for ChatBotKit here.

Contributing

Encounter a bug or want to contribute? Open an issue or submit a pull request on our official GitHub repository.

chatbotkit/types.py is generated and should not be edited by hand. To regenerate it from the latest API specification, run the type sync script from the platform repo:

pnpm --dir sites/main script:sync-types:python

Install the development dependencies and run the test suite with:

pip install -e ".[dev]"
pytest

License

See LICENSE for details.