Conversation channels

Conversation channels connect an external messaging channel, such as Telegram or Slack, to a durable Xema agent session. People write to your organization where they already are; an agent answers in the same chat, and the conversation keeps its history between messages.

The feature is provided by the conversation-channels base biome. A channel is not a fixed list: it is any connector that can receive messages and answer the outbound send action. Telegram and Slack ship today. Adding a channel means installing a connector for it, with no change to this biome.

How a message flows

  1. In. The connector receives the provider's message, verifies it and normalizes it into a standard message envelope. See the Telegram and Slack connectors for what each one accepts.
  2. Routed. The message goes to the channel account it arrived on. It joins the durable session that belongs to that conversation, or starts one if this is a new conversation.
  3. Answered. The agent's reply streams out of the session. Xema coalesces the stream into whole channel-native messages rather than sending every fragment, and sends them through the connector's connector:channel.send-message@1 capability using the connection the account is bound to.

Channel accounts

A channel account represents one bot or workspace on one provider. Admins manage accounts:

TaskWhat it does
CreateNeeds the provider key (for example TELEGRAM or SLACK), a display name, the provider's own account id (bot username or Slack team id, unique per provider in an org) and the org-level connector connection it sends through. An unregistered provider key is refused with UNKNOWN_CHANNEL_PROVIDER. You can name the bot owner's sender id, who is paired as owner at once, and the agent every routed session uses.
ListLists the organization's accounts.
Activate and deactivateActivating gives the account a fresh durable delegation of authority, and deactivating revokes it.
DeleteRemoves the account and revokes its delegation.

An account is PENDING, ACTIVE, DISABLED or ERRORED. When it is not active it shows a reason: DEACTIVATED, or one of the DELEGATION_* reasons (DELEGATION_ABSENT, DELEGATION_RENEWAL_REFUSED, DELEGATION_REFUSED_AT_USE, DELEGATION_REFUSED, DELEGATION_ENDED). The delegation reasons need an org admin to activate the account again.

Who the agent talks to

The people writing to a channel are external contacts, not Xema users, and the session runs under the organization's authority rather than theirs. For that reason the default channel agent, the Channel Assistant, runs at the sandbox reach tier with no armed capabilities. It answers people but cannot act with your organization's authority, so nobody who can message the bot can use the bot to do so.

An organization that wants a channel agent with more reach binds its own launch definition to the conversation-channel role, or names a different agent on the account. That is a deliberate, visible choice and never the default.

When a reply might not have arrived

Each reply has a delivery state: PENDING, SENDING, SENT, UNCERTAIN, EMPTY or FAILED. UNCERTAIN means the send was attempted and its outcome is unknown, for example when a connection dropped mid-send. An admin can list an account's uncertain replies and resend one. Resend is idempotent: a reply that was already sent is returned as it is, so it is never delivered twice.

Previous: ← Connectors Next: Biomes →