←back to manuals

Channel Publishing

Learn about publishing messages to channels for remote function calling in conversational AI and more.

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.