AI Agent Behaviour

Handoff via Prompts — Team & Agent Routing

Copy page

One of the most powerful capabilities of an AI Agent in Chatmo is its ability to route conversations to the right human team or specific human agent automatically — without the customer having to explicitly request it. By writing clear handoff instructions within the behavior prompt, you can make your Agent intelligently determine when, to which team, and to which agent a conversation should be transferred.

This page explains how to write effective handoff prompts, with example scenarios for a variety of routing needs — including both team-based and agent-based routing.

How Automatic Handoff Works

A handoff is the process of transferring a conversation from the AI Agent to a human agent. In Chatmo, a handoff occurs when the AI Agent determines that a conversation requires human involvement and forwards it to the appropriate team or specific human agent.

There are two types of handoff:

• On-demand handoff — The customer explicitly asks to speak with a human. Chatmo handles this automatically without any special configuration.
• Automatic handoff via prompt — The Agent detects certain conditions based on the conversation context and proactively transfers to the right team or agent. This is what we cover on this page.

Automatic prompt-based handoff enables sophisticated routing — for example, directing a customer in London to the UK Support Team, routing billing disputes to the Billing Team, escalating VIP customers to the Priority Team, or assigning a conversation directly to a specific human agent like "John Smith".

Routing Options

Chatmo supports two types of routing targets:

Routing Type	Description	Use Case
Team-based	Routes the conversation to a team. Any available member of that team can pick it up.	General routing by department, location, or topic
Agent-based	Routes the conversation directly to a specific human agent by name.	VIP handling, account managers, specialist agents

You can combine both in the same prompt — for example, route most conversations to a team but assign VIP customers to their dedicated account manager.

Prerequisites

Before writing handoff prompts, make sure the following are in place:

1. Teams Must Already Exist

You must have already created the teams that will receive handoffs. This is done in Human Agent > Team Management. For example, if you want the Agent to route conversations to "UK Support Team", that exact team name must already exist in Chatmo.

See the Team Management guide for instructions on creating teams.

2. Teams Must Have Members

Every target team must have at least one human agent assigned. A handoff to an empty team will leave the conversation unassigned and unanswered.

3. Agent and Teams Share the Same Inbox

The AI Agent and the target handoff teams must have access to the same inbox (device/channel). If the Agent handles messages from WhatsApp Device A, the target team must also have access to that inbox.

4. Human Agents Must Exist (for Agent-Based Routing)

If you want to route conversations to a specific human agent, that agent must already exist as an active user in your organization. The name you use in the prompt must match the agent's full name as registered in Chatmo (case-insensitive). For example, if the agent's name is "John Smith", you can write transfer to agent "john smith" or transfer to agent "John Smith".

Writing Handoff Prompts

Handoff instructions are written as part of the AI Agent's behavior prompt (system prompt). The basic format is a conditional instruction: "If [condition is met], transfer to [team name]" or "If [condition is met], transfer to agent [agent name]."

Basic Format — Team Routing

Code
=== HANDOFF RULES ===
Transfer the conversation to a human team under the following conditions:

1. If [condition A] → transfer to "[Team A Name]"
2. If [condition B] → transfer to "[Team B Name]"
3. If [condition C] → transfer to "[Team C Name]"

Before transferring:
- Let the customer know they are being connected to the right team
- Provide a brief summary of what has been discussed

Do not transfer if the question can still be answered by you.

Basic Format — Agent Routing

Code
=== HANDOFF RULES ===
Transfer the conversation to a specific human agent under the following conditions:

1. If [condition A] → transfer to agent "[Agent Full Name]"
2. If [condition B] → transfer to agent "[Agent Full Name]"
3. For all other handoff cases → transfer to "[Team Name]"

Before transferring:
- Let the customer know they are being connected to the right person
- Provide a brief summary of what has been discussed

Basic Format — Combined Team + Agent Routing

Code
=== HANDOFF RULES ===
Transfer the conversation using the following rules:

1. If the customer is a VIP account → transfer to agent "Sarah Johnson"
2. If the issue is about billing → transfer to "Billing Team"
3. If the customer asks for their account manager by name → transfer to
   agent "[the agent name mentioned by customer]"
4. For all other handoff cases → transfer to "General Support Team"

Key Principles

• Use the exact team name as it appears in Chatmo. If the team is named "Billing Support Team", write exactly that in the prompt — not "Billing Team" or "Billing Support".
• Define clear, unambiguous conditions. Avoid overly broad triggers like "if the customer needs help" since virtually every conversation meets that condition.
• Set priorities for overlapping conditions. For example, if a customer in London has a billing issue, should the conversation go to the UK Team or the Billing Team? Make the priority explicit.

---

Handoff Scenarios and Example Prompts

Below are four common handoff scenarios, each with a full example prompt you can adapt for your business.

Scenario 1: Location-Based Routing

Best for businesses with regional teams that serve customers based on geography.

When to use this scenario:

• Businesses with offices or branches in multiple cities or countries
• Services that depend on location (delivery, installation, field service)
• Companies with regional sales or support teams

Example prompt:

Code
=== LOCATION-BASED ROUTING ===
When a conversation requires human assistance, route to the regional team
based on the customer's location.

How to determine location:
- Ask the customer for their city or region if it hasn't been mentioned
- Use any address information the customer has shared during the conversation
- If the customer mentions a suburb or neighborhood, match it to the nearest city

Routing rules:
1. Customer in London, Manchester, or Birmingham → transfer to "UK Support Team"
2. Customer in New York, Boston, or Philadelphia → transfer to "US East Team"
3. Customer in Los Angeles, San Francisco, or Seattle → transfer to "US West Team"
4. Customer in Sydney, Melbourne, or Brisbane → transfer to "Australia Team"
5. Customer in Singapore or Malaysia → transfer to "SEA Support Team"
6. Customer in any other location → transfer to "Global Support Team"

Before transferring, say:
"I'll connect you with our team in [region] who can assist you further.
One moment, please."

If the customer declines to share their location, route to Global Support Team.

Scenario 2: Topic-Based Routing

Best for businesses with specialist teams that handle different types of issues.

When to use this scenario:

• Companies with separate departments (billing, technical, logistics)
• Businesses that need different escalation paths for different issue types
• Organizations with structured issue-handling workflows

Example prompt:

Code
=== TOPIC-BASED ROUTING ===
Route conversations to specialist teams based on the topic or issue type.

Routing rules:

TECHNICAL ISSUES
Condition: customer is experiencing an error, bug, feature malfunction,
login problems, or other technical difficulties
Action: transfer to "Technical Support Team"
Message: "I'll connect you with our technical team who can help
resolve this issue."

BILLING / PAYMENT ISSUES
Condition: questions about invoices, refunds, failed payments, subscription
changes, or payment disputes
Action: transfer to "Billing Team"
Message: "For billing-related matters, let me connect you with our
billing team."

COMPLAINTS
Condition: customer is expressing dissatisfaction, frustration, or describing
a negative experience; customer is using an angry or upset tone
Action: acknowledge their feelings first, apologize, then transfer
to "Customer Care Team"
Message: "I'm sorry to hear about this experience. Let me connect you
with our dedicated customer care team who can help make this right."

SALES INQUIRIES
Condition: prospect asking about enterprise pricing, product demos,
custom plans, or partnership opportunities
Action: transfer to "Sales Team"
Message: "I'll connect you with our sales team who can put together
the best offer for your needs."

SHIPPING / LOGISTICS ISSUES
Condition: package not delivered, damaged in transit, wrong shipping
address, or other logistics-related problems
Action: transfer to "Logistics Team"
Message: "For shipping issues, let me connect you directly with
our logistics team."

Priority order (when an issue falls into multiple categories):
1. Complaints (always prioritized)
2. Technical issues
3. Billing issues
4. Shipping issues
5. Sales inquiries

Scenario 3: Urgency-Based and Customer Tier Routing

Best for businesses that provide different service levels based on customer type or the severity of the issue.

When to use this scenario:

• Businesses with customer tiers (standard, premium, VIP, enterprise)
• Situations requiring immediate attention
• Different SLAs based on subscription level

Example prompt:

Code
=== URGENCY-BASED ROUTING ===
Some conversations require priority handling. Use the following rules:

HIGH PRIORITY — transfer to "Priority Support Team"
Immediately transfer with minimal back-and-forth if:
- Customer identifies as a VIP, enterprise, or premium subscriber
- Customer mentions a high-value transaction (above $10,000)
- Customer states they have contacted support multiple times without resolution
- Customer threatens to cancel their subscription or switch to a competitor
- The issue directly impacts the customer's business operations (e.g., service outage, data loss)
Message: "I'm connecting you with our priority support team right away
for immediate assistance."

MEDIUM PRIORITY — transfer to "Support Team"
Transfer after you've attempted to help but cannot resolve the issue:
- Technical issues requiring backend or admin-level access
- Requests that need managerial approval
- Questions whose answers are not available in the knowledge base
Message: "For this particular issue, I need to connect you with our
support team. One moment, please."

LOW PRIORITY — handle independently
Continue handling without handoff:
- General questions that can be answered from the knowledge base
- How-to and feature usage questions
- Standard pricing and plan information
- Order status checks available through tools

Scenario 4: Language-Based Routing

Best for international businesses or platforms that serve a multilingual customer base with dedicated language-specific support teams.

When to use this scenario:

• Businesses operating in multiple countries
• Platforms serving users across different languages
• Companies with language-dedicated support teams

Example prompt:

Code
=== LANGUAGE-BASED ROUTING ===
Detect the customer's language and route to the appropriate team when
a handoff is needed.

Routing rules:
1. Customer communicates in English → transfer to "Support Team - EN"
2. Customer communicates in Bahasa Indonesia → transfer to "Support Team - ID"
3. Customer communicates in Mandarin → transfer to "Support Team - CN"
4. Customer communicates in Spanish → transfer to "Support Team - ES"
5. Customer communicates in any other language → transfer to "Support Team - EN" (fallback)

Notes:
- Determine the language based on the dominant language used by the customer
  throughout the conversation
- If the customer mixes languages, route based on the language used most frequently
- Deliver the handoff message in the customer's language

Handoff messages:
- EN: "Let me connect you with our support team. Please hold on for a moment."
- ID: "Baik, saya akan menghubungkan Anda dengan tim support kami. Mohon tunggu sebentar."
- CN: "Let me connect you with our Mandarin-speaking support team. Please hold on."
- ES: "Permítame conectarlo con nuestro equipo de soporte. Un momento, por favor."

Scenario 5: Agent-Based Routing (Assign to Specific Person)

Best for businesses that assign dedicated agents to specific customers or need specialist individuals to handle certain cases.

When to use this scenario:

• VIP customers with dedicated account managers
• Technical issues requiring a specific specialist
• Ongoing cases where a customer should always talk to the same person
• Businesses with named advisors or consultants

Example prompt:

Code
=== AGENT-BASED ROUTING ===
In some cases, conversations should be routed to a specific human agent
rather than a team.

DEDICATED ACCOUNT MANAGERS
Condition: customer identifies as a VIP or enterprise client,
or mentions their account manager by name
Action:
- If customer mentions "Sarah" or is from Acme Corp → transfer to agent "Sarah Johnson"
- If customer mentions "David" or is from GlobalTech → transfer to agent "David Chen"
- If customer is a VIP but no specific manager is known → transfer to "Priority Support Team"
Message: "I'll connect you directly with [agent name], your dedicated
account manager. One moment please."

SPECIALIST ROUTING
Condition: customer has a highly specialized technical issue
Action:
- API integration issues → transfer to agent "Mike Torres"
- Database migration support → transfer to agent "Lisa Park"
- Security-related concerns → transfer to agent "James Wilson"
Message: "For this type of issue, I'll connect you with [agent name],
one of our specialists in this area."

RETURNING CUSTOMER
Condition: customer mentions they've been working with a specific agent
Action: transfer to the agent mentioned by the customer
Message: "Let me reconnect you with [agent name]. One moment."

FALLBACK
If the specified agent is not available or not found, transfer to
the relevant team instead (e.g., "Technical Support Team" or
"Priority Support Team").

Scenario 6: Combined Team + Agent Routing

Best for businesses that need both general team routing and specific agent assignment within the same prompt.

When to use this scenario:

• Businesses that have general teams for most cases but dedicated agents for VIPs
• Organizations with specialist agents embedded within larger teams
• Companies that want flexible routing based on context

Example prompt:

Code
=== COMBINED ROUTING RULES ===

AGENT-SPECIFIC ROUTING (check these first):
- Customer from Acme Corp or mentions "account manager" → transfer to agent "Sarah Johnson"
- Customer has an active escalation case → transfer to agent "David Chen"
- Customer asks for a specific person by name → transfer to agent "[name mentioned]"

TEAM-BASED ROUTING (for all other cases):
- Technical issues → transfer to "Technical Support Team"
- Billing questions → transfer to "Billing Team"
- General inquiries → transfer to "General Support Team"

Priority: Always check agent-specific rules first. If no specific agent
applies, fall back to team-based routing.

---

Recommended Handoff Prompt Template

Based on the scenarios above, here is a combined template that incorporates multiple routing types into a single behavior prompt section. Use this as a starting point and keep only the sections relevant to your business.

Code
=== HANDOFF RULES ===

General principles:
- Always attempt to answer the customer's question yourself before transferring
- Do not transfer for simple questions you can handle
- Before transferring, inform the customer that they will be connected to the right team or agent
- Provide a brief summary of the customer's issue to the receiving team/agent

=== AGENT-SPECIFIC ROUTING (check these first) ===

1. VIP ACCOUNT MANAGER
   Condition: customer identifies as VIP or enterprise, or mentions their account manager
   Action: transfer to agent "Sarah Johnson" (Acme Corp, GlobalTech accounts)
   Action: transfer to agent "David Chen" (StartupX, MegaCorp accounts)
   Fallback: if no specific manager matches, transfer to "Priority Support Team"

2. SPECIALIST AGENT
   Condition: customer has a highly specialized issue that requires a known expert
   Action: transfer to the relevant specialist agent by name

3. RETURNING CUSTOMER
   Condition: customer mentions they've been working with a specific person
   Action: transfer to the agent mentioned by name

=== TEAM-BASED ROUTING (for all other cases) ===

4. COMPLAINT ESCALATION
   Condition: customer expresses a complaint, anger, or dissatisfaction
   Action: acknowledge their feelings, apologize, then transfer to "Customer Care Team"

5. ADVANCED TECHNICAL ISSUES
   Condition: technical problems that cannot be resolved with standard guidance
   Action: collect issue details (screenshots, error messages, steps to reproduce),
   then transfer to "Technical Support Team"

6. SALES / ENTERPRISE REQUESTS
   Condition: questions about enterprise plans, custom pricing, or partnerships
   Action: gather basic info (company name, requirements, estimated volume),
   then transfer to "Sales Team"

7. PAYMENT ISSUES
   Condition: disputes, refunds, or payment errors
   Action: transfer to "Billing Team"

8. CUSTOMER REQUEST
   Condition: customer explicitly asks to speak with a human
   Action: transfer to "Support Team" immediately without resistance

9. OUTSIDE BUSINESS HOURS
   Condition: customer needs a handoff but it's outside team working hours
   Action: let the customer know the team is currently offline and will
   reach out during business hours
   Team hours: Monday-Friday 9:00 AM - 6:00 PM, Saturday 9:00 AM - 1:00 PM

What you MUST do before any handoff:
- Greet the customer and acknowledge their issue
- Attempt an initial answer or solution if possible
- Inform the customer that you're connecting them with the right team or person
- Collect relevant information so the receiving team/agent doesn't have to ask again

What you must NOT do during handoff:
- Do not transfer without notifying the customer
- Do not give specific response time estimates (e.g., "they'll reply in 5 minutes")
- Do not promise specific outcomes that the receiving team may not deliver

---

Tips and Best Practices

Use Consistent Team and Agent Names

The team names in your behavior prompt must exactly match the team names configured in Chatmo — including capitalization and spacing. Agent names are matched case-insensitively against the user's full name in Chatmo.

Name in Chatmo	Write in Prompt
Technical Support Team (team)	transfer to "Technical Support Team"
Billing Team (team)	transfer to "Billing Team"
CS-Premium (team)	transfer to "CS-Premium"
Sarah Johnson (agent)	transfer to agent "Sarah Johnson"
David Chen (agent)	transfer to agent "David Chen"

Avoid Over-Handoff

Too many handoffs defeat the purpose of having an AI Agent in the first place. Make sure the Agent genuinely attempts to answer before transferring. Add an explicit instruction:

Code
IMPORTANT: Always try to answer the customer's question yourself first
using the available knowledge base. Only transfer if:
- The question is outside the scope of your knowledge base AND behavior prompt
- The customer explicitly asks to speak with a human
- The situation matches one of the handoff conditions above

Collect Context Before Handoff

An effective handoff includes context. Instruct the Agent to gather relevant information before transferring, so the human agent does not have to start the conversation from scratch.

Code
Before transferring to any team, make sure you've collected:
- Customer's name
- Summary of the issue or question
- Steps already attempted (if applicable)
- Any relevant identifiers (order number, account ID, screenshot, etc.)

Write Natural Transition Messages

Avoid robotic handoff messages. Craft transitions that feel natural and reassure the customer.

Code
AVOID:
"This conversation will now be transferred to Technical Support. Ticket ID: #12345."

USE:
"I understand the issue, and I want to make sure you get the best help possible.
Let me connect you with our technical team — they'll be able to dig into this
and get it sorted for you. Just a moment."

Test Every Handoff Scenario

Before activating the Agent with handoff prompts, use the Testing feature to simulate each scenario. Verify that:

• The Agent transfers to the correct team for each condition
• The Agent routes to the correct specific agent when agent-based rules apply
• Transition messages sound natural and appropriate
• The Agent does not perform unnecessary handoffs
• The Agent collects sufficient context before transferring

---

Complete Prompt Example with Integrated Handoff

Below is a full behavior prompt that includes Agent identity, communication style, responsibilities, and handoff rules (both team and agent routing) in a single cohesive prompt. You can copy and adapt this for your own use.

Code
You are Sam, a virtual assistant for FixRight — a home appliance repair
and maintenance service company.

FixRight operates in New York, Chicago, Los Angeles, and Miami. You help
customers with service information, repair cost estimates, and scheduling
technician visits.

=== COMMUNICATION STYLE ===
- Friendly and professional
- Address customers by first name when available
- Show technical knowledge but explain things in plain language
- Be concise and solution-oriented

=== RESPONSIBILITIES ===
- Answer questions about available repair services
- Provide cost estimates based on the type of appliance and issue
- Help schedule technician visits
- Share warranty and service policy information
- Answer frequently asked questions

=== BOUNDARIES ===
- Do not guarantee exact repair costs — always use "estimate"
- Do not provide DIY repair instructions that could void warranties or pose safety risks
- Do not diagnose issues definitively without a physical inspection

=== HANDOFF RULES ===
Transfer conversations to a human team or specific agent under the
following conditions:

AGENT-SPECIFIC ROUTING (check these first):
- Customer from Acme Corp or identifies as enterprise client
  → transfer to agent "Sarah Johnson" (Enterprise Account Manager)
- Customer mentions ongoing case with a specific technician
  → transfer to agent "[technician name mentioned]"
- Customer asks for their account manager by name
  → transfer to agent "[name mentioned by customer]"

LOCATION-BASED ROUTING (when customer needs a technician visit or wants
to visit a service center):
- New York, New Jersey, Connecticut → transfer to "NYC Service Center"
- Chicago, Milwaukee, Indianapolis → transfer to "Chicago Service Center"
- Los Angeles, San Diego, Orange County → transfer to "LA Service Center"
- Miami, Fort Lauderdale, Tampa → transfer to "Miami Service Center"
- Other locations → transfer to "Central Support" and let the customer
  know that on-site service is not yet available in their area,
  but they can ship their appliance for repair

TOPIC-BASED ROUTING:
- Complaint about a previous repair → transfer to "Quality Assurance Team"
- Warranty claim → transfer to "Warranty Team"
- B2B or partnership inquiry → transfer to "Business Development Team"
- Special parts request (not in standard inventory) → transfer to "Parts Team"

URGENCY-BASED ROUTING:
- Customer mentions an urgent breakdown (commercial kitchen equipment down,
  medical equipment, critical business appliance) → transfer to "Emergency
  Response Team" and mark as URGENT
- Customer has been waiting more than 3 days without an update → transfer
  to "Quality Assurance Team"

HANDOFF PROCEDURE:
1. Inform the customer that you will connect them with the right team or person
2. Mention the team/agent name and reason for the transfer
3. Make sure you've collected: customer name, appliance type, issue
   description, and service ID (if they have one)
4. Execute the handoff

Example transition messages:
"Got it — for this type of repair, let me connect you directly with our
service center in [city]. They'll be able to help you schedule an
inspection and get a detailed quote. One moment."

"I'll connect you directly with Sarah, your dedicated account manager.
She'll be able to help with your enterprise account. One moment please."

---

What's Next

• AI Agent Behavior Examples — See full behavior prompt examples for various industries.
• Team Management — Learn how to create and configure the teams that receive handoffs.
• Testing Your AI Agent — Test your handoff scenarios before going live.