Routing Colleague Action Codes

What a routing colleague does

Think of a routing colleague as the front desk. It doesn't answer guest questions itself — it reads the latest message, decides what the guest is asking about, and hands the conversation to the right specialist:

• A message about WiFi → routed to your WiFi colleague (or a template that replies with the network and password).
• A message about late checkout → routed to your check-in/checkout specialist.
• An emergency, refund demand, or anything the colleague can't confidently classify → escalates to your team.

Open the routing colleague editor

1. In the admin dashboard, go to AI Agents → AI Colleagues.
2. Pick a routing colleague from the list. (If you don't have one yet, click Hire a colleague and choose the Advanced: create a routing bot link at the bottom of the catalog.)
3. Open the Instructions tab.

You'll see an Action codes panel — the heart of the editor — and an Escalation triggers panel below it. The list of codes is where you spend most of your time.

Anatomy of an action code

Each code has a short uppercase name and three fields. Together they describe what the code means and when the colleague should pick it:

Naming your codes

• Uppercase with underscores. The editor auto-uppercases as you type. No spaces, no hyphens, no dots.
• Two or three tokens, max. DEPOSIT_RETURN not AFTER_CHECKOUT_DEPOSIT_RETURN_INQUIRY. Long names hurt readability without helping the classifier.
• Shape: domain then intent. DEPOSIT_EXPLAIN, DEPOSIT_RETURN, WIFI_PROBLEM, LATE_CHECKOUT all follow this pattern.

Add a new code

1. At the bottom of the Action codes list, click Add action code.
2. Type the code name. The editor auto-uppercases as you type — type wifi_problem and you'll see WIFI_PROBLEM.
3. Click Add action code to confirm. The new card opens with empty When, Examples, and Not when fields.
4. Fill in When — one sentence about the trigger.
5. Add 2–4 Examples. Use the Add example button to add more rows, or the trash icon next to a row to remove it.
6. Optionally add a Not when note pointing at a sibling code that this one might be confused with.
7. Click Save code.

Edit an existing code

Click any code card to expand it, then click Edit. You see the same three structured fields. Make your changes and click Save code — only that one code is updated; the rest of the colleague is untouched.

To remove a code, expand the card and click Delete code.

Reserved codes — handled for you

Two codes are built into the platform. You'll see them as small chips above the Action codes list. Don't add them to your list — the platform handles them automatically:

• ESCALATE — sent automatically when the guest reports an emergency, demands a refund, threatens a chargeback, raises a formal complaint, refuses to provide personal data on data-privacy grounds (after one polite reply), or asks for something the colleague isn't confident about. An escalation opens a support case and notifies your team.
• NO_MESSAGE — sent when nothing in the message matches any of your codes. The colleague stays silent and waits for the next message.

Customise when to escalate

Below the Action codes list there's a collapsible When to escalate panel. The standard escalation triggers (emergencies, refund demands, formal complaints, data-privacy refusals) are already built in — you don't need to repeat them.

Use this panel only when you want to add tenant-specific escalation triggers. For example: “Any message about a stove issue in winter must escalate because we can't ship a replacement part quickly.”

Migrating an older routing colleague

Routing colleagues created before the structured editor existed used a flat format that looked like You reply "CODE" if .... When you open one of those colleagues you'll see a yellow banner at the top:

1. Click Migrate to structured format.
2. Review the side-by-side preview. The original content is on the left; the converted structure is on the right.
3. Click Confirm to save the structured version. Cancel leaves the original untouched.

Connecting a code to a handler

Once the routing colleague is emitting a code, you decide what happens next. The platform looks for a handler in this order:

1. An AI Colleague whose Action code field matches the emitted code → that colleague takes over the reply.
2. A Message template whose Action code matches → the template's text is sent directly.
3. If neither exists → the code is logged but no reply is sent.

To connect a code, open the AI Colleague (or template) that should handle it and set its Action code field to the same uppercase name.

Related: Colleague Triggers & Routing covers the full dispatch flow from the platform's perspective.

Test your colleague

Once you've added or edited a code, use the Test button in the header and send a sample message that represents the new trigger. It shows you the code the colleague emitted, plus a confidence score and a one-sentence reason for the pick.

When you don't need a routing colleague

If you only have one AI Colleague covering everything, you don't need a routing colleague — every message flows straight to that colleague. Routing colleagues become useful when you want to split different topics across different colleagues (or templates), or when you want a small message — like a deposit policy or check-in code — to be sent automatically instead of generated.