Channel Routes
Answer differently per surface and condition, without touching the channel default.
Overview
A route is (surface, conditions) → action — a row on one
channel. On every inbound message, after checking whether the
address has its own action, naturali loads the channel's
active routes, discards those whose surface disagrees and whose match
predicates do not all evaluate true, and answers with the most specific
survivor. No survivor falls back to the channel's default.
See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Channel Routes.
Data Model
ChannelRoute
| Field | Type | Description |
|---|---|---|
action | agent | oneshot | message | silence, nullable | What an inbound message becomes; null only on an address with no action of its own, which the route table then decides. agent is a dialogue: the identity behind the message gets a session, and every later message on it continues the same one. oneshot runs the agent once and keeps nothing — no address, no actor, no session, no conversation — so each message is answered on its own. Choose it for work that is filed rather than discussed; choose agent when the answer depends on what came before. message delivers fixed text without running an agent, and silence answers nothing. |
agent_id | string, nullable | The agent that answers, when action is agent or oneshot. |
text | string, nullable | The fixed text delivered, when action is message. |
repeat | every | once | object | How often a message fires: every (default), once, or { after_seconds }. Null unless action is message. |
language | string, nullable | Preferred reply language; null lets the agent decide. |
config | object, nullable | Conversation config bag — media handling, persona overrides, the Discord allowlist, and how a oneshot answers. discord.reply picks the delivery: react (the default) adds discord.reaction — \u2705 unless named — to the message that triggered the run, mention answers beside it addressing whoever asked, react_or_mention reacts when the agent writes nothing and answers like mention when it writes a line, thread opens a thread and answers inside it, and none delivers nothing at all. A run that fails delivers nothing in every mode, so a reaction always means the work was done; there is no failure marker. A mention with nothing else in it is ignored unless the action says otherwise, for any action. discord.use_replied_message: true takes the text of the message it replies to, so replying to a message with only the mention files that message. discord.empty_mention_text answers any other bare mention with that fixed text, addressing the sender, without running the agent. discord.forward_user_id: true hands the sender's Discord user id to the agent's tools as the discord_user_id tool context, which a tool's headers read as {{context:discord_user_id}}. It is the id Discord reported for the message's author, never text the model wrote, so a tool can act for whoever sent it. Off unless set, because tool context reaches every tool the agent has. Read only for oneshot. A conversational agent in a guild is its thread — that is what its session is keyed on — so it always opens one. |
id | string | Public route ID. |
project_id | string | The owning project. |
channel_id | string | The channel this route belongs to. |
surface | string, nullable | The surface this route matches, or null for "any" (GET /v1/channel-kinds). |
match | object | The predicate bag, ANDed. {} matches every message on this surface. |
priority | integer | Tiebreak only, after specificity and surface. |
status | active | disabled | |
created_at | string (date-time) | |
updated_at | string (date-time) | |
warnings | array of unreachable_surface | On a create or update response only, and only when non-empty. unreachable_surface: the channel's transport mode does not deliver this surface yet. |
Key Concepts
Specificity, most to least
When more than one active route matches, the winner is picked in this order:
highest count of matched predicates, then a route with surface set beats one
with surface null, then highest priority, then oldest created_at. An
address's own action (see Addresses) beats every route
outright, and a route always beats the channel's default.
One cell, one active route
Two active routes may not claim the identical (surface, match) combination —
creating or updating one into a collision is a 409 ROUTE_CONFLICT. A
disabled route never conflicts, so pausing one and creating its replacement
is always safe.
Surfaces and predicates come from the kind
surface and the keys match may use are declared per channel kind — see
Channel Kinds. An unknown surface is 400 UNKNOWN_SURFACE;
an unknown or wrong-typed predicate is 400 UNKNOWN_PREDICATE. Writing a route
for a surface whose transport mode is off (a Discord guild_thread route
before mention_threads is enabled) still succeeds, with unreachable_surface
in the response warnings — turning the mode on later never requires
rewriting the table.
A replace states what it keeps
PATCH /v1/projects/{project_id}/channels/{channel_id}/routes/{route_id}
replaces the whole route, and an omitted field takes its create default. Where
that default would widen the route, omission is 400 REPLACE_OMITS_FIELDS,
naming the fields in meta.fields, and nothing is written: a set surface,
a non-empty match, a non-empty config (the Discord allowlist lives there),
and status on a disabled route. Send each one — its value to keep it, or
"surface": null, "match": {}, "config": null, "status": "active" to
clear it. Turning a gated route into a oneshot while keeping its allowlist:
- CLI
- SDK
- curl
naturali replace-channel-route \
--project-id proj_V1StGXR8Z5jdHi6B \
--channel-id chan_V1StGXR8Z5jdHi6B \
--route-id route_V1StGXR8Z5jdHi6B \
--surface guild_thread \
--match '{ "guild_id": "9988776655" }' \
--action oneshot \
--agent-id agent_public_V1StGXR8Z5jdHi6B \
--config '{ "discord": { "allowed_user_ids": ["1290000000000000042"] } }'
const { data: route } = await naturali.channels.replaceChannelRoute({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
channel_id: 'chan_V1StGXR8Z5jdHi6B',
route_id: 'route_V1StGXR8Z5jdHi6B',
},
body: {
surface: 'guild_thread',
match: { guild_id: '9988776655' },
action: 'oneshot',
agent_id: 'agent_public_V1StGXR8Z5jdHi6B',
config: { discord: { allowed_user_ids: ['1290000000000000042'] } },
},
});
curl -X PATCH https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/channels/chan_V1StGXR8Z5jdHi6B/routes/route_V1StGXR8Z5jdHi6B \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"surface": "guild_thread",
"match": { "guild_id": "9988776655" },
"action": "oneshot",
"agent_id": "agent_public_V1StGXR8Z5jdHi6B",
"config": { "discord": { "allowed_user_ids": ["1290000000000000042"] } }
}'
Examples
Route Discord server threads in one guild to a public agent, leaving DMs on the channel default:
- CLI
- SDK
- curl
naturali create-channel-route \
--project-id proj_V1StGXR8Z5jdHi6B \
--channel-id chan_V1StGXR8Z5jdHi6B \
--surface guild_thread \
--match '{ "guild_id": "9988776655" }' \
--action agent \
--agent-id agent_public_V1StGXR8Z5jdHi6B
const { data: route } = await naturali.channels.createChannelRoute({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
channel_id: 'chan_V1StGXR8Z5jdHi6B',
},
body: {
surface: 'guild_thread',
match: { guild_id: '9988776655' },
action: 'agent',
agent_id: 'agent_public_V1StGXR8Z5jdHi6B',
},
});
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/channels/chan_V1StGXR8Z5jdHi6B/routes \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"surface": "guild_thread",
"match": { "guild_id": "9988776655" },
"action": "agent",
"agent_id": "agent_public_V1StGXR8Z5jdHi6B"
}'
Read every route across a project in one call:
- CLI
- SDK
- curl
naturali list-project-channel-routes --project-id proj_V1StGXR8Z5jdHi6B
const { data } = await naturali.channels.listProjectChannelRoutes({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
});
curl https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/channel-routes \
-H "Authorization: Bearer $NATURALI_TOKEN"