Channels

Primary Use Case

While this endpoint can be used generically by ChatBotKit customers for pub/sub messaging, its primary purpose is to support remote function calling in conversational AI workflows.

How Remote Function Calling Works

1. Setup: When calling the /complete routes with function definitions, you can specify a channel name in the result configuration.

2. Function Invocation: If the AI model decides to call one of the defined functions, it returns a message item containing:

   • The function name
   • The function arguments
   • The channel name that was specified in the /complete request

3. Result Publishing: The caller then executes the function locally and pushes the result back to the model by publishing to this endpoint using the channel name provided by the model.

Publishing a Message

To publish a message to a channel, send a POST request with the message payload as a JSON object:

Workflow Example

Important Notes

• Channel ID Requirements: Channel IDs must be at least 16 characters long for security and collision avoidance.

• Channel ID Namespace: Channel IDs cannot be reused between different ChatBotKit sessions.

• Message Format: The message field accepts a string. For structured data (like function results), serialize to JSON

• Real-time Delivery: Messages are delivered in real-time to active subscribers.If no subscriber is listening, the message is not queued or persisted.

• Stateless: Channels do not maintain message history. Subscribers only receive messages published while they are actively connected.

Subscribing to Channel Messages

Channel subscription enables real-time message streaming, allowing you to receive messages as they are published to a channel. This creates a persistent connection that continuously delivers events, making it ideal for building real-time applications, live dashboards, and responsive integrations.

To subscribe to a channel, establish a streaming connection using the subscribe endpoint with the channel ID you wish to monitor:

The channel ID must be at least 16 characters long to ensure uniqueness and security. Once connected, the endpoint returns a streaming response that remains open, continuously sending message events as they occur.

Understanding the Streaming Response

The subscription endpoint uses Server-Sent Events (SSE) style streaming, returning JSON Lines (JSONL) format where each line represents a separate event. Each message event includes:

The streaming connection remains active until either:

• The client closes the connection
• A network error or timeout occurs
• The server terminates the connection due to inactivity

Real-Time Communication Pattern

Channels provide a pub-sub pattern where publishers send messages and subscribers receive them in real-time. This enables:

• Live updates: Receive immediate notifications when events occur
• Remote function calling: Trigger actions in response to published messages
• Multi-subscriber support: Multiple clients can subscribe to the same channel
• Decoupled communication: Publishers and subscribers don't need direct connections

The subscription endpoint works seamlessly with the channel publish endpoint, creating a complete real-time messaging system. When a message is published to a channel, all active subscribers immediately receive the event through their streaming connections.

Implementation Example

Here's how to implement a channel subscriber in JavaScript:

Important: Channel IDs should be treated as secure identifiers. Only share channel IDs with authorized clients that should receive the messages. Consider using randomly generated channel IDs for sensitive communications.