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:

POST /api/v1/channel/{channelId}/publish
Content-Type: application/json

{
  "message": { "temperature": 72, "conditions": "sunny" }
}

http

Workflow Example

// Step 1: Call /complete with function definitions and channel
POST /v1/conversation/complete
{
  "model": "...",
  "messages": [...],
  "functions": [
    {
      "name": "get_weather",
      "parameters": {...},
      "result": {
        "channel": "my-function-channel-abc123"
      }
    }
  ]
}

// Step 2: Model responds with function call
// Response includes: function="get_weather", args={city: "NYC"}, channel="my-function-channel-abc123"

// Step 3: Execute function locally
const result = await getWeather("NYC")

// Step 4: Publish result back via this endpoint
POST /v1/channel/my-function-channel-abc123/publish
{
  "message": { "temperature": result.temperature, "conditions": result.conditions }
}

javascript

Important Notes

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

  • Channel ID Namespace: Channel IDs are scoped to your session, so they cannot conflict across different ChatBotKit sessions.

  • Message Format: The message field accepts any JSON object. For function results, pass the result data directly as a JSON object.

  • Real-time Delivery: Messages are delivered in real-time to active subscribers. If no subscriber is listening at the time of publish, the message is not delivered to late-joining subscribers unless those subscribers use the historyLength option to request history replay.

  • Message History: In system-managed workflows (such as dispatch-based function calling), messages are persisted in a Redis Stream for up to one hour. Subscribers can replay these stored messages by passing historyLength to the subscribe endpoint. This allows subscribers to catch up on messages published before the connection was established.

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:

POST /api/v1/channel/{channelId}/subscribe
Content-Type: application/json

{}

http

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.

Replaying Historical Messages with historyLength

When subscribing to a channel, you can request that the server first replay recent messages that were published before your connection was established. This is useful in dispatch-style workflows where messages may have been published during the brief window between initiating a request and establishing the subscription connection.

To enable history replay, include historyLength in the request body with the maximum number of past messages you want to receive:

POST /api/v1/channel/{channelId}/subscribe
Content-Type: application/json

{ "historyLength": 100 }

http

When historyLength is set, the server will:

  1. First deliver up to that many recent historical messages in chronological order (oldest to newest), each as a message event in the stream.
  2. Then continue streaming new live messages as they are published.

The historyLength value must be an integer between 0 and 10000. History is stored for up to one hour (3600 seconds) by default, so very old messages may no longer be available. If fewer historical messages are available than requested, only the available messages are replayed before live streaming begins.

Understanding the Streaming Response

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

{"type":"message","data":"your message content here"}

json

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, including replaying the last 50 historical messages before receiving live events:

const response = await fetch('/api/v1/channel/my-channel-id-12345/subscribe', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_TOKEN'
  },
  body: JSON.stringify({ historyLength: 50 })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { value, done } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');

  for (const line of lines) {
    if (line.trim()) {
      const event = JSON.parse(line);
      if (event.type === 'message') {
        console.log('Received:', event.data);
        // Handle the message
      }
    }
  }
}

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.

Go to cbk.ai