Channel Publishing

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.

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": JSON.stringify({ 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 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:

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.

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:

{"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:

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({})
});

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