Channels
The Channels screen lets you list the inbound channels that turn messages into agent runs, read the sessions of a channel, send a test message, change the owner or the status of a channel, and delete it. Portal path: /capabilities/channels. Developers and application owners register channels; tenant administrators delete them. The screen is drawn by portal/src/screens/capabilities.tsx.
What the screen shows
- Channels table, read with
GET /v1/channels(every channel in one call). Columns: Name, Type, Agent (the agent the channel serves), Status, Updated. Empty: No channel, hint Apply a Channel manifest below. - A click on a row, or View details, opens a side panel with
GET /v1/channels/{name}. - Apply a manifest panel prefilled with a Channel manifest sample (
portal/src/samples/channel-manifest.json), with Reset example and Apply.
Actions
| Button or action | What it does | API call | Roles |
|---|---|---|---|
| Refresh (icon) | Reloads the list. | GET /v1/channels | Any tenant member |
| Row click or View details | Opens the channel record. | GET /v1/channels/{name} | Any tenant member |
| Row menu Sessions | Shows the sessions of the channel (500 most recent). | GET /v1/channels/{name}/sessions | Any tenant member |
| Row menu Send message | Form Text (required), User, Conversation id; sends the message as an inbound message of the channel and shows the answer. | POST /v1/channels/{name}/inbound | tenant_admin, developer, agent |
| Row menu Edit | Form Owner and Status (active, disabled). | PATCH /v1/channels/{name} | tenant_admin, developer, application_owner |
| Row menu Delete | Opens Confirm a destructive action; type the channel name, then Confirm. | GET /v1/lineage/graph, then DELETE /v1/channels/{name} | tenant_admin |
| Reset example / Apply | Restores the sample / applies the Channel manifest. | POST /v1/manifests/apply | tenant_admin, developer |
| Retry (error state) | Sends the failed read again. | Same call | Same roles |
Send message sends this body; empty optional fields are left out:
{"text": "Where is my invoice INV-2026-118?", "user": "jane.doe", "conversation_id": "conv-42"}
The channel checks the message size and the rate limits, runs the DLP on the text, finds or opens the session of the user and the conversation, stores the message and, when the agent of the channel is active, starts a run with the trigger channel. The answer gives session_id, session_created, message_id, run_id, and run_skipped when the agent is not active.
Roles
The portal hides no button. In services/control-plane/src/eai/domains/channels/routes.py: an inbound message needs OPS_ROLES (tenant_admin, developer, agent); edit needs WRITE_ROLES (tenant_admin, developer, application_owner); delete needs tenant_admin; reading needs a tenant. platform_admin passes every role check.
Typical tasks
Test a channel end to end
- Send a message. The test goes through the same checks as a real user message. In the row menu, click Send message, type the Text, a User and a Conversation id, then click Send message. Expected result: a side panel with
session_id,message_idand arun_id. If it fails:run_skippedmeans the agent of the channel is not active;dlp_blocked(403) means the DLP blocked the text. - Follow the run. The run belongs to the session of the conversation. Open the Runs screen and filter on the agent. Expected result: a run with the trigger
channel. If it fails: check the status of the agent in the Registry. - Read the session. The session keeps the messages. In the row menu, click Sessions. Expected result: the session of the conversation is listed. If it fails: click Refresh and try again.
Close a channel for a while
- Disable it. A disabled channel refuses inbound messages. Click Edit, choose
disabledin Status, then click Edit. Expected result: the status Disabled; Send message answerschannel_disabled. If it fails:forbiddenmeans you lacktenant_admin,developerorapplication_owner.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
channel_not_found (404) | The name is wrong or the channel was deleted. | Copy the name from the table. |
channel_disabled (409) | The status is disabled. | Set it back to active with Edit. |
message_too_large (413): "The message exceeds ... bytes." | The text is above the size limit of the channel. | Send a shorter text. |
rate_limited (429) | The limit of user messages per minute of the channel (rate_per_minute) is reached for this user. | Wait, then send again. |
too_many_sessions (429) | The channel reached its maximum of concurrent open sessions. | Close sessions, or raise the limit in the manifest. |
dlp_blocked (403) | The text holds data the DLP blocks. | Remove the sensitive data. |
run_skipped in the answer | The agent of the channel is suspended or killed. | Resume the agent. |