Channels

Channels connect external messaging platforms to your AI agents, transforming them into conversational assistants available wherever your users are.

Supported providers: Telegram and Slack.

How it works

1. Create a channel: specify the provider and credentials (bot token, signing secret).
2. Activate: the Core registers a webhook with the messaging platform.
3. Link identities: users link their messaging account to their RootCX identity for RBAC enforcement.
4. Message routing: incoming messages are mapped to agent sessions. The agent processes the message and replies through the same channel.

Providers

Both providers support:

• Typing indicators while the agent processes a message.
• Message debouncing for long responses (2000ms debounce, triggered at 4096+ characters).
• Tool approval buttons/prompts when the agent requires human approval.
• Agent switching (multiple agents per channel).
• Media attachments on inbound messages.

Account linking

Users must link their messaging identity to a RootCX account for the agent to process their messages with proper RBAC enforcement.

Flow

1. A logged-in user requests a link token via POST /api/v1/channels/{channelId}/link. Returns a token valid for 5 minutes.
2. Telegram: the user opens https://t.me/{botUsername}?start={token} (deep link). Telegram sends /start {token} to the bot.
3. Slack: the user sends /link {token} in the Slack channel.
4. The Core validates the token and links the messaging chat ID to the RootCX user.
5. The bot confirms the link and the user can start chatting with agents.

Unlinked users receive a prompt to complete the linking process.

Check link status

GET /api/v1/channels/{channelId}/identity

Returns whether the current authenticated user is linked to this channel.

Creating a channel

POST /api/v1/channels

{
  "provider": "telegram",
  "name": "Support Bot",
  "config": {
    "bot_token": "123456:ABC..."
  }
}

For Slack:

{
  "provider": "slack",
  "name": "Internal Bot",
  "config": {
    "bot_token": "xoxb-...",
    "signing_secret": "abc123..."
  }
}

Response includes the channel id and a webhook_secret used for the webhook URL.

Activating a channel

POST /api/v1/channels/{channelId}/activate

Optional body to update credentials:

{ "bot_token": "new-token-if-rotating" }

On activation, the Core:

1. Registers the webhook URL with the messaging provider (Telegram setWebhook, Slack via app configuration).
2. Syncs bot commands (Telegram: /newsession, /agent).
3. Sets the channel status to active.

Deactivating a channel

POST /api/v1/channels/{channelId}/deactivate

Unregisters the webhook with the provider and sets the channel status to inactive. Messages stop being routed.

Webhook endpoint

POST /api/v1/channels/{provider}/{channelId}/webhook

This is the URL registered with the messaging platform. It receives all incoming messages and events. No RootCX authentication required (each provider uses its own verification: Telegram via X-Telegram-Bot-Api-Secret-Token header, Slack via HMAC request signing).

The Core parses the webhook, identifies the user via their linked identity, resolves the active agent, and invokes it with the message. The agent's response is sent back through the channel.

Agent interaction

When a linked user sends a message:

1. The Core looks up which agent is bound to this channel (or the user's last active agent).
2. The message is sent to the agent as an invocation with session continuity (same session per chat).
3. The agent streams its response. Text chunks are sent back to the user in real-time.
4. If the agent calls a tool that requires approval, approval buttons/prompts are sent to the user.
5. The user can approve or deny directly in the messaging platform.

Agent switching

Users can switch between agents using the /agent command (Telegram) or equivalent interaction. The channel maintains separate sessions per agent per user.

Deleting a channel

DELETE /api/v1/channels/{channelId}

Unregisters the webhook with the provider and removes the channel record and all associated identity links and sessions.

Technical details

Database tables

API endpoints summary