OpenAI Compatibility

ChatBotKit provides an OpenAI-compatible chat completions endpoint that allows you to use standard OpenAI client libraries, tools, and frameworks with ChatBotKit's AI infrastructure. This endpoint implements the OpenAI Chat Completions API specification, enabling drop-in compatibility with existing OpenAI integrations.

The compatibility layer translates OpenAI API requests into ChatBotKit conversation engine calls and converts the responses back to the expected OpenAI format. This means you can point any OpenAI-compatible client at the ChatBotKit base URL and immediately leverage ChatBotKit's capabilities including custom bots, knowledge bases, integrations, and advanced conversation management.

Creating Chat Completions

To create a chat completion, send a POST request to the OpenAI-compatible endpoint with your conversation messages. The endpoint accepts the standard OpenAI chat completions request format and returns responses in the same structure that OpenAI clients expect.

The response follows the standard OpenAI format, including the generated assistant message, token usage statistics, and completion metadata. Both streaming and non-streaming modes are fully supported.

Model Selection with Selectors

ChatBotKit extends the OpenAI model field with a flexible selector syntax that allows you to target specific ChatBotKit resources. Instead of using bare model names, you specify structured selectors that tell the platform exactly which resource to use for the completion.

The model/name=... selector routes your request to a specific AI model available on the ChatBotKit platform. For example, model/name=gpt-4o uses GPT-4o, while model/name=claude-sonnet-4 uses Claude Sonnet 4. This selector gives you direct access to any model in the ChatBotKit model catalog.

The bot/id=... selector routes your request through a specific ChatBotKit bot configuration. When you use a bot selector like bot/id=abc123, the completion inherits the bot's backstory, skillsets, connected knowledge bases, privacy settings, and all other configured behaviors. This allows you to use the OpenAI API format while leveraging the full power of ChatBotKit's bot management system.

Bare model names without the selector syntax are intentionally not supported. This design ensures explicit control over which ChatBotKit resources handle each request and prevents ambiguity about configuration sources.

Message Roles and Conversation Mapping

The endpoint automatically converts between OpenAI message formats and ChatBotKit's internal conversation structure. System messages are concatenated and applied as conversation backstory, extending any existing bot backstory rather than replacing it. User and assistant messages map directly to user and bot turns in the conversation history.

When using the bot/id=... selector, system messages from your request extend the bot's configured backstory. This allows you to provide request-specific context while preserving the bot's core instructions. For model/name=... selectors without an underlying bot configuration, the system messages become the entire backstory for that completion.

Assistant messages in the input conversation that contain function calls or tool calls are converted to request activity messages, preserving the function name and arguments. Tool role messages containing function results are converted to response activity messages, maintaining the correlation between calls and results through tool call IDs.

The conversation mapping ensures that complex multi-turn interactions with tool usage work seamlessly across the OpenAI compatibility layer.

Streaming Responses

Set stream: true in your request body to receive the completion as a server-sent event stream instead of a single JSON response. The streaming format follows the OpenAI specification exactly, delivering tokens as they are generated and enabling real-time display of responses in your application.

The streaming response delivers a sequence of data: events, each containing a completion chunk. The first chunk establishes the assistant role, subsequent chunks contain content tokens or tool call deltas, and the final chunk includes the finish reason. The stream ends with a data: [DONE] marker.

Token usage statistics are not available in streaming mode, as the response is generated incrementally without waiting for the complete token count.

Tool Calling and Function Support

The endpoint supports both the legacy functions parameter and the current tools parameter for declaring callable functions. Declared functions are presented to the AI model as available tools, and when the model decides to call one, the endpoint returns the tool call in the standard OpenAI format.

Function declarations follow the OpenAI specification, with a name matching the pattern ^[a-zA-Z0-9_-]{1,64}$, an optional description, and a JSON schema for parameters. The endpoint merges functions from both the functions and tools arrays, deduplicating by name if the same function appears in both.

When the model generates a tool call, the response includes the tool call details with a unique call ID, the function name, and the arguments as a JSON string. Your application is responsible for executing the function and submitting the result back in a follow-up completion request.

The stateless round-trip model means the endpoint does not automatically execute functions. It declares them to the model and returns the tool calls for your code to handle, maintaining full control over function execution and side effects.

Using Standard OpenAI Client Libraries

You can use official OpenAI client libraries by configuring them to point at the ChatBotKit base URL. The authentication mechanism remains the same: your ChatBotKit API token is passed as a bearer token in the Authorization header.

For the OpenAI Python client:

For the OpenAI Node.js client:

This compatibility allows you to migrate existing OpenAI integrations to ChatBotKit with minimal code changes, or to use ChatBotKit as a backend for tools and frameworks built for the OpenAI API.