How to route by role, channel, language, and session state

Back to how-to guides Use this pattern when the same request must reach a different agent by channel, language, user role, or session state.

Concept

A HANDOFF route can test any value in the session data. Write the test as an expression in WHEN. On each customer message, the platform checks the routes in the order you write them. It does this before the model reasons. The first route with a true expression takes the conversation. The model does not run for that message. The check skips a WHEN: true route and a route with a plain-language WHEN. The model can still call them. When no expression route is true, the model runs. The platform evaluates the WHEN of any route the model calls, and it refuses the route when the expression is false. Context routing differs from intent routing in one way. The classifier does not run when the supervisor has no intent.category condition and no INTENTS: section. Two tools control which routes can fire.

Tool	What it does
`WHEN`	Takes the conversation when true. Refuses a route that the model calls when false.
`ENABLED_WHEN`	Removes the route from the check and from the model’s choices while the condition is false.

Values you can test

Value	Path	Notes
Channel	`session.channel`	The channel type, such as `web_chat`, `voice`, `whatsapp`, or `api`. The value is `digital` when the channel sets none.
Language	`session.interaction.current.language`	The primary language code, such as `es`.
Locale	`session.interaction.current.locale`	The full tag, such as `es-MX`.
Time zone	`session.interaction.current.timezone`	An IANA name, such as `America/Mexico_City`.
Detected language	`session.languageDetection.language`	The language of the customer’s message. Present only when the project turns on language detection. See Route on detected language.
Identity	`session.identityTier`	`0` anonymous, `1` asserted, `2` verified.
Role, tier, entitlements	`session.<name>`	Caller data from your channel or SDK. Also readable as `<name>`.
State	A session variable	A gathered field, a value mapped back from a child, or a value you set.

The platform provides channel, language, locale, time zone, and identity. It provides no role. Your channel, SDK, or a lookup must supply the role. Treat caller data from a browser as unverified. Pair a role test with session.identityTier == 2. Use session.channel for the channel. The paths channel.name and system.channel belong to other features. They do not resolve in a HANDOFF WHEN, and channel.name compiles without a warning. The path session.interaction.current.channel does not exist. Voice has several channel types: voice, voice_twilio, voice_livekit, voice_realtime, voice_pipeline, voice_vxml, korevg, audiocodes, and genesys_audio_connector. A test for "voice" matches only the first one. Use IN [...] to match the family.

Order and ties

The position of an entry sets its priority. The first entry has the highest priority. The PRIORITY: field is read and then ignored. Several expression routes can be true at once, for example a Spanish speaker on a voice channel. The first true route in the list wins. The model does not choose between them. Put the most specific route first. See Combine conditions.

Minimal working example

This supervisor routes verified administrators, Spanish speakers, and voice callers. A WHEN: true route handles everyone else. Put the supervisor and all agents in the same project. The target agents are short stand-ins. agents/context-routing-supervisor.agent.abl

SUPERVISOR: Context_Routing_Supervisor
GOAL: "Route each customer by role, language, and channel, then fall back to standard service"

BEHAVIOR:
  ROLE: router

HANDOFF:
  # Role: verified administrators only.
  - TO: Admin_Support_Agent
    WHEN: session.identityTier == 2 AND session.user_role == "admin"
    CONTEXT:
      pass: [customer_id, account_id]
      summary: "Verified administrator needs privileged support."

  # Language: Spanish speakers.
  - TO: Spanish_Service_Agent
    WHEN: session.interaction.current.language == "es"
    CONTEXT:
      pass: [customer_id]
      summary: "Customer should be served in Spanish."

  # Channel: voice callers.
  - TO: Voice_Support_Agent
    WHEN: session.channel IN ["voice", "voice_twilio", "voice_livekit", "voice_realtime", "voice_pipeline", "voice_vxml", "korevg", "audiocodes", "genesys_audio_connector"]
    CONTEXT:
      pass: [customer_id]
      summary: "Voice caller needs short spoken answers."

  # Fallback: everyone else.
  - TO: Standard_Service_Agent
    WHEN: true
    CONTEXT:
      pass: [customer_id]
      summary: "Customer needs standard service."

agents/admin-support-agent.agent.abl

AGENT: Admin_Support_Agent
GOAL: "Handle privileged support requests from verified administrators"

agents/spanish-service-agent.agent.abl

AGENT: Spanish_Service_Agent
GOAL: "Serve customers in Spanish"

agents/voice-support-agent.agent.abl

AGENT: Voice_Support_Agent
GOAL: "Serve voice callers with short spoken answers"

agents/standard-service-agent.agent.abl

AGENT: Standard_Service_Agent
GOAL: "Handle standard support requests"

Project-local assumptions:

session.user_role is caller data that your SDK or channel sends, for example the value admin.
customer_id and account_id follow the same rules as in How to route users by detected intent. The platform passes the supervisor’s value when it has one. Otherwise the model fills the field from the conversation.

How it works

The supervisor keeps the conversation until a route fires.
On each customer message, the platform checks the expression routes in the order you wrote them. It skips WHEN: true routes, plain-language routes, and routes that ENABLED_WHEN hides.
The first true route takes the conversation. The model does not run.
When no expression route is true, the model runs. The model can call any available route. The platform evaluates that route’s WHEN at the call and refuses a false one.
The target receives the PASS values, the summary, and the history that history allows. The default is full.
With EXPECT_RETURN: false, the target keeps the conversation. With EXPECT_RETURN: true, the supervisor resumes when the target returns.
A missing value makes a test false. session.user_role == "admin" is false when the role is absent.
The model chooses the WHEN: true route. With ROLE: router, the supervisor must call a route or ask one question. Without BEHAVIOR, the supervisor can answer in text instead.

A route without an intent.category test never reads the category.

Common variations

Combine conditions

Join tests with AND and OR. Put the combined route before the single-test routes. Here, Spanish voice callers reach a dedicated agent.

  - TO: Spanish_Voice_Agent
    WHEN: session.channel == "voice" AND session.interaction.current.language == "es"
    CONTEXT:
      pass: [customer_id]
      summary: "Spanish-speaking voice caller."

  - TO: Voice_Support_Agent
    WHEN: session.channel == "voice"
    CONTEXT:
      pass: [customer_id]
      summary: "Voice caller needs short spoken answers."

Do not join a test with a quoted phrase. In session.channel == "voice" AND "the user is a VIP", the compiler warns with CEL_CONDITION_UNRESOLVED_CALL. At runtime the phrase is a string that is always true, so the route fires for every voice caller. Test a field instead, for example session.customer_tier == "vip".

Route on locale

Use the locale when the dialect matters.

  - TO: Mexico_Service_Agent
    WHEN: session.interaction.current.locale == "es-MX"
    CONTEXT:
      pass: [customer_id]
      summary: "Mexican Spanish customer."

Route on detected language

Use the detected language when the customer’s words decide the language, not the channel or profile setting. This needs the project setting for language detection. With the setting off, the value is absent and every test on it is false.

  - TO: Spanish_Service_Agent
    WHEN: session.languageDetection.status == "detected" AND session.languageDetection.language == "es"
    CONTEXT:
      pass: [customer_id]
      summary: "Customer wrote in Spanish."

The platform detects the language of each customer message. It stores the result before it checks the routes, so the route reads the current message.

Field	Meaning
`status`	`detected`, `low_confidence`, `no_language`, `failed`, `unavailable`, or `skipped`.
`language`	The language tag, only when `status` is `detected`.
`confidence`	A number from 0 to 1.
`candidate`	The best guess when `status` is `low_confidence`.

The project settings set the confidence threshold, the minimum text length, and the allowed languages. A message that is too short, a keypad entry, or secure input does not give a detected status. An agent hook can also set the language with SET_INTERACTION_LANGUAGE. That changes session.interaction.current.language only when the agent’s before_turn hook runs. The check on the same message still reads the earlier value. Route on session.languageDetection for a decision on the current message.

Route on state that a child returns

Use EXPECT_RETURN: true when another agent collects the value first. This route asks for a language preference once. It then routes on the answer.

  - TO: Language_Choice_Agent
    WHEN: preferred_language IS NOT SET
    EXPECT_RETURN: true
    CONTEXT:
      summary: "Ask the customer which language they prefer."
      history: none
    ON_RETURN:
      action: resume_intent
      map:
        chosen_language: preferred_language
    ON_FAILURE: RESPOND "I could not check your language preference. Please try again."

  - TO: Spanish_Service_Agent
    WHEN: preferred_language == "es"
    CONTEXT:
      pass: [customer_id]
      summary: "Customer chose Spanish."

map copies the child’s chosen_language into the supervisor’s preferred_language. Write the child field first. The child must gather or produce chosen_language. Without a value, the first route fires again on the next message. After the child returns, resume_intent replays the customer’s request. The replay skips the check, so the model picks the route, and the route’s WHEN still applies. The next customer message goes through the check again. Use IS NOT SET on a plain variable such as preferred_language. Do not use it on a dotted path such as session.interaction.current.language. The path holds a null value when the language is unknown, and IS NOT SET is false for null.

Hide a route on other channels

Add ENABLED_WHEN when a channel must never see a route. The route is out of the check and out of the model’s choices while the condition is false.

  - TO: Voice_Support_Agent
    WHEN: session.channel IN ["voice", "voice_twilio"]
    ENABLED_WHEN: session.channel IN ["voice", "voice_twilio"]
    CONTEXT:
      pass: [customer_id]
      summary: "Voice caller needs short spoken answers."

Write ENABLED_WHEN as an expression over data that exists before the turn. A condition that reads intent or plain language fails to compile with ENABLED_WHEN_SEMANTIC_REFERENCE. A condition that reads a missing value counts as false.

Add ON_FAILURE

ON_FAILURE runs when the handoff fails before the target accepts it.

  - TO: Voice_Support_Agent
    WHEN: session.channel == "voice"
    CONTEXT:
      pass: [customer_id]
      summary: "Voice caller."
    ON_FAILURE: RESPOND "I cannot reach the voice team right now. I will help you directly."

The values are CONTINUE, ESCALATE, and RESPOND "message". A bare quoted string fails with INVALID_HANDOFF_FAILURE_ACTION.

Verification

Start a voice session and send a message. Open the trace. Find the deterministic_routing event. Confirm target is Voice_Support_Agent and condition shows the voice test.
If the route does not fire, the model path runs. Find the handoff_condition_check event for a route the model called. Read evaluatedContext to see the value of session.channel that your channel reports.
Send a Spanish message on a web channel. Confirm deterministic_routing names Spanish_Service_Agent. For the detected-language route, find the language_detection event. Confirm status is detected.
Start a session with caller data user_role set to admin and an identity tier of 2. Confirm Admin_Support_Agent. Repeat with tier 0. Confirm the route does not fire.
Send a message that matches no condition. Confirm the model calls Standard_Service_Agent. Find its handoff_condition_check event.
For a route with EXPECT_RETURN: true, find the handoff_completed event. Read outcome and durationMs.
Check that each target receives the pass values and the summary.

Production readiness checklist

Every value in a WHEN has a source: the platform, caller data, a lookup, or a child’s return.
Role tests also require a verified identity, for example session.identityTier == 2.
Channel tests list every channel type in the family, or you confirm the exact value in a trace.
Overlapping routes are ordered with the most specific route first.
A WHEN: true route covers every other message, and BEHAVIOR with ROLE: router stops the supervisor from answering in text.
Detected-language routes test status. A fallback route handles the case where detection is off.
Quoted phrases never appear inside an AND or OR test.
ON_FAILURE is set on routes where a missing target must produce a reply.
Tests cover each channel, each language, each role, and one message with no match.

Common mistakes

Mistake	Why it happens	How to avoid it
Using `channel.name` or `system.channel` in a route.	Other features use these paths.	Use `session.channel`.
Using `session.interaction.current.channel`.	The channel seems to belong to the interaction.	The path does not exist. Use `session.channel`.
Testing `session.channel == "voice"` for all voice.	Voice looks like one channel.	Use `IN [...]` with the voice channel types.
Trusting a role from the browser.	The role is easy to read from caller data.	Add `session.identityTier == 2`, or look the role up on the server.
Joining a test with a quoted phrase.	The phrase seems to add a semantic check.	The phrase is always true. Test a field.
Setting `PRIORITY:` to resolve overlaps.	The field looks like it orders routes.	The platform ignores it. Reorder the entries.
Expecting the model to choose between two true routes.	The model reads the route descriptions.	The first true expression route wins. Order the entries.
Putting the broad route first.	The order looks like a list of equals.	The broad route wins every time. Put the specific route first.
Using `IS NOT SET` on `session.interaction.current.language`.	The language can be unknown.	Compare the value, or test a plain variable.
Routing on `session.languageDetection` with detection off.	The path reads like a built-in value.	Turn on the project setting, and keep a fallback route.
Writing `map` as `parent: child`.	The parent field seems to come first.	Write `child: parent`. The compiler reports `UNKNOWN_HANDOFF_RETURN_FIELD`.

Troubleshooting

Symptom	Likely cause	What to check
The channel route never fires.	The channel type differs from your test.	`session.channel` in `evaluatedContext`. Compare it with your list.
The language route never fires.	The language is unresolved or differs.	`session.interaction.current.language`. The value is the primary code, such as `es`, not `es-MX`.
The detected-language route never fires.	Detection is off, or the status is not `detected`.	The `language_detection` event: `status`, `reason`, and `language`.
The role route never fires.	The role or the identity tier is missing.	The caller data and `session.identityTier`.
The role route fires for the wrong user.	The route tests only the caller’s role.	Add `session.identityTier == 2`.
A voice route fires for every caller.	A quoted phrase sits inside an `AND` test.	The `WHEN` text. Replace the phrase with a field test.
Two routes could match, and the wrong one runs.	An earlier route is also true.	The entry order. The first true route wins. Move the specific route up.
A route is missing from the model’s choices.	`ENABLED_WHEN` is false or reads a missing value.	The `ENABLED_WHEN` expression and its data.
No route matches and the supervisor answers directly.	The supervisor has no `ROLE: router`, or no `WHEN: true` route.	Add a fallback route and `BEHAVIOR` with `ROLE: router`.

Get started

Build

Optimize

Deploy

Analyze

References