Setting Up Human Handover

Human Handover gives your Agent a way to pull a real person in. You write rules in plain English that describe the situations your team wants to hear about, and you say where each one should go: an email to your front desk, or a ticket in Freshdesk. When the Agent meets one of those situations and can't resolve it itself, it files the handover with a summary, the guest's details, and the full chat transcript.

Why You'd Want This

Your Agent will meet things it shouldn't handle alone. A guest with a genuine complaint. A booking problem that needs someone with access to the PMS. A request that's perfectly reasonable and simply outside what you've given the Agent to work with.

Without handover, the Agent's best move in those moments is an apology. With it, the Agent can take the guest's problem, package it up, and put it in front of someone who can actually fix it. Some of what that buys you:

• Catch the conversations that matter instead of finding out days later in a review.
• Give your team the whole story. A summary, the guest's booking details, and the full transcript, so nobody has to ask the guest to explain again.
• Route by situation. A complaint can go to your guest relations inbox while a billing question opens a Freshdesk ticket in the right queue.
• Keep the guest talking. Filing a handover doesn't end the Conversation. The Agent carries on helping with whatever else it can.
• Decide the threshold yourself. You write the conditions, so you control what's worth a human's time.

How It Works

Human Handover is built out of rules. A rule is three things: a name, a plain-English condition describing when it applies, and a destination.

1. You write the conditions. For example, "the guest reports a problem with their room that needs staff attention" or "the guest disputes a charge on their bill."
2. The Agent matches against them. Your condition text goes into the Agent's instructions. When a Conversation looks like one of your conditions, and the Agent can't resolve it itself, it files that rule.
3. The Agent gives the guest one heads-up. A handover goes out once and can't be updated, so the Agent tells the guest that anything they want your team to know is best mentioned now.
4. The handover goes out, carrying a short summary the Agent writes (always in English, so your team can triage it), whatever guest details are known, and the transcript in the guest's own language.
5. The Conversation continues. Nothing closes, nothing locks.

Two things about this are worth knowing up front, because they surprise people.

There are no keywords. The Agent reads your condition and judges. You don't get a trigger word list, and you don't need one, but it does mean the wording of your condition is the entire control surface. A vague condition produces vague behavior.

A guest asking for a human isn't enough on its own. This is deliberate, and it's written into the Agent's instructions: "A guest asking for a human, a phone number, or to 'create' / 'open' a support ticket is NOT by itself a reason to file." The Agent needs an actual problem that matches one of your conditions and that it can't solve. Otherwise every guest who typed "agent please" would open a ticket.

Before You Start

Decide two things:

What do you want to hear about? Start with two or three situations that genuinely warrant a person. You can add more later.

Where should each one go? You have two destinations, and each rule picks its own:

• Email. Just an address. Nothing else to set up.
• Freshdesk. Creates a real ticket. Needs a Freshdesk connector on your Organization first, and the guest's email address.

You can mix them. One rule can email the front desk while another opens a Freshdesk ticket.

Note: If you're going to use Freshdesk, set the connector up before you start, or you'll have to come back. Go to Connectors, add a Freshdesk connector, then return here.

Step 1: Turn On the Feature

Open your Agent, go to the Features tab, and select Human Handover. Switch it to Enabled. The switch saves right away. Everything below it (the connection and the rules) is greyed out until you do.

Enabling on its own does nothing yet. Until at least one rule exists and is enabled, the Agent isn't given the handover tool at all, so it has no way to escalate. That's a safe default rather than a limitation: an Agent that can't file is better than one that files into a void.

Step 2: Connect Freshdesk (If You're Using It)

Skip this if all your rules go to email.

Above the rules you'll find a Connection panel. If nothing is connected yet it reads: "This feature sends its output through a connector. Connect one of your organization's connectors to activate it."

Select Connect and pick your Freshdesk connector. Only active connectors can be connected, and only one connector can be bound at a time. To switch, use Replace. To remove it, use Disconnect.

If a Freshdesk rule fires and no connector is connected, the Agent can't file. It tells the guest it can't connect them to a human right now and points them to a support route from its own instructions.

Note: Keep an eye on connector health. If the connector fails verification or becomes inactive later, this panel shows Connector error or Connector not active. While it's in that state, Freshdesk tickets fail to send, and the guest isn't told: the Agent already confirmed the handover. If you see either warning, select View connector and fix it straight away.

Step 3: Add a Rule

Select Add rule. Each rule card has:

Field	What it's for
Rule enabled	Turn a rule off without deleting it. A disabled rule stays configured but the Agent can't use it.
Rule name	An identifier. Must have no spaces, and must be unique.
Trigger condition	Plain English. This is what the Agent matches against.
Delivery backend	Freshdesk or Email.

Rule names are strict on purpose, because the Agent refers to the rule by name when it files. If you break the rules, Save stays disabled and the editor shows "Rule names must be non-empty and contain no whitespace." or "Rule names must be unique." Use something like guest-complaint or billing-dispute.

New rules start on Freshdesk. You can reorder rules with Move rule up and Move rule down (the order is only for your overview, it doesn't change which rule the Agent picks), and delete one with Remove rule. Rule changes only take effect when you select Save.

Note: Every rule needs a trigger condition and a subject template. The editor doesn't flag a blank one, so if saving fails with "Failed to save feature configuration.", check those two fields first.

Writing a Condition That Works

The condition is the whole game. It's the only thing standing between "my team gets the escalations they need" and "my team gets a ticket every time someone says hello."

Describe the situation, not the words. The Agent isn't pattern-matching on phrases, so listing phrases doesn't help.

• Weak: "guest says complaint or unhappy or angry"
• Better: "The guest reports a real problem with their stay, such as a room fault, a cleanliness issue, or poor service, that needs staff to act."

Say what doesn't count. Conditions that exclude are as useful as conditions that include, and they stop a rule swallowing everything nearby.

• Better still: "...that needs staff to act. Not general questions about facilities or opening hours."

Keep rules distinct. If two conditions overlap, the Agent has to guess which one you meant, and it may pick differently on different days. If you can't tell them apart in one sentence, neither can the Agent.

One situation per rule. A rule that covers complaints and billing and lost property will fire for all three and land in one inbox. Split them and route each where it belongs.

Step 4: Set the Destination

Email

Field	Notes
Sender email	A bare address, like alerts@example.com.
Sender display name	Optional. What recipients see as the sender's name.
Recipients (one per line)	At least one. Commas work too. Each gets their own copy.
Subject template	See below.

Saving is blocked with "Every email rule needs at least one recipient." if you leave recipients empty.

Freshdesk

Field	Notes
Subject template	See below.
Priority	Low, Medium, High, or Urgent. Defaults to Low.
Status	Open, Pending, Resolved, or Closed. Defaults to Open.
Source ID	Optional. Defaults to the chat source. Change it if your Freshdesk uses a custom source.
Group ID	Optional. Sends the rule's tickets to a specific Freshdesk group, so a rule can land in its own queue.
Email config ID	Optional.

The guest's email address is required for Freshdesk. Freshdesk needs a requester, so if the Agent doesn't already know the guest's email, it asks the guest for it before filing. If you'd rather never ask, use email delivery for that rule instead.

The Subject Template

Both destinations take a subject template using $placeholder syntax. Available placeholders:

$summary, $rule_name, $guest_name, $guest_email, $language_code, $language_name, $reservation_id, $confirmation_number, $arrival_date, $departure_date, $hotel_name, $channel

A good subject tells your team what they're looking at before they open it:

Guest complaint, $hotel_name: $summary

$summary is the Agent's own short description of the problem, a few words, always in English.

The subject can't be blank, and a lone $ at the end isn't allowed. If you need a literal dollar sign, write $$.

Note: A placeholder with no value becomes an empty string, and a misspelled one does too. Nothing errors. If your subjects come through with gaps in them, check your spelling first.

Step 5: Route Tickets with Custom Fields (Freshdesk Only)

Freshdesk rules have five extra tools for getting a ticket into the right queue with the right metadata. All optional.

Static fields. Key/value pairs sent on every ticket from this rule. Good for constants like a department code. Whole numbers are sent as numbers.

Guest context mapping. Maps a Freshdesk custom field to a guest attribute, so the ticket carries the booking data. Available attributes: guest name, guest email, language code, language name, reservation ID, confirmation number, arrival date, departure date, hotel name, and channel. Every mapped field needs an attribute, or saving is blocked with "Every mapped Freshdesk field needs a guest attribute."

Channel field and channel value mapping. Records which Channel the Conversation came from, translating internal values (web, whatsapp, sms, email, voice) into whatever your Freshdesk dropdown accepts. If a channel isn't mapped, the field is simply left off.

Conversation link field. Put the backoffice link to the Conversation into a Freshdesk field, so whoever picks up the ticket can read the whole thing in context.

Note: If two settings target the same Freshdesk field, the more specific one wins. A static value beats a mapped one, the Agent's custom field choice beats both, and the Conversation link beats everything. In the key/value lists, a repeated key keeps only its last value.

Custom Field Choices

This one is different, and it's the most powerful of the lot. The backoffice describes it as "Categorical Freshdesk fields the assistant picks a value for at handover time."

You define a Freshdesk field, a description telling the Agent what it's choosing, and a list of options. At handover time the Agent picks one.

The obvious use is routing by property or by topic. Give it your list of hotels, or your list of complaint categories, and let the Agent classify the ticket as it files.

Each entry needs:

• Freshdesk field name, the field key on the ticket
• Description for the assistant, which the Agent reads to know what it's picking. Write this like you'd brief a new colleague.
• Options, each a value (what Freshdesk receives) and a label (a readable name that helps the Agent choose)

All three are required, and saving is blocked with "Custom fields need a name, a description, and at least one option." otherwise.

The Agent must pick a value for each custom field, and only from your options. It sends the option's value, and the label only helps it choose. If it skips a field or sends something you didn't declare, the attempt is refused with an explanation, and it tries again. Nothing reaches your team until the values are right, and a refused attempt doesn't use up the rule's one handover. A wrong guess doesn't produce a broken ticket.

Note: TrustYou can also tie a custom field to a guest attribute, such as the hotel name. The Agent then doesn't have to guess: when the guest's booking data matches one of your option labels, that option is used. The guest's actual booked hotel beats the Agent's inference about which hotel they mean. A field tied this way is no longer required from the Agent. If the booking data doesn't match any option, the Agent's pick is used. You can't set this up in the backoffice yet, so ask your TrustYou contact if you need it.

What Your Team Receives

By email: each recipient gets their own message with the summary, a Guest section listing whatever is known (name, email, language, reservation ID, arrival, departure, hotel, and channel), the rule that fired along with its condition text, an Open conversation in Backoffice button, and the full transcript inline.

In Freshdesk: a ticket whose description carries the summary and the guest context as a list, with your custom fields populated, and the transcript attached as a text file in the guest's language. The ticket doesn't name the rule, so use the subject or a static field if your team needs to know which one fired. For the reservation, the ticket shows the guest-facing confirmation number, while the email shows the reservation ID. If your team searches by confirmation number, add $confirmation_number to the email subject. The transcript file is named after the guest's language, like chat-transcript-de.txt.

The guest details come from what the Agent already knows about the Conversation, plus anything the guest stated in the chat.

The transcript is built from messages that were actually sent, so it can't contain anything the guest never saw. It's laid out as [Guest] and [Agent] lines, with [Staff] for anything your team posted into the Conversation. It leaves out Agent messages from before the guest's first message, hidden messages, system messages, and messages the guardrails flagged.

Testing It

There's no test button for handover, so test it by having the conversation.

1. Open your Agent in Preview and play the situation your condition describes. Use a guest's words, not your condition's words. If you wrote "disputes a charge," try "why am I being charged twice?"
2. Check it fired. Look in the destination inbox or Freshdesk queue. Check the subject rendered properly, with no gaps where placeholders should be.
3. Check it didn't fire when it shouldn't. Ask an ordinary question. Ask for a human with no actual problem attached. Neither should produce a ticket. If a plain request for a human files one, your condition is too loose.
4. Try each rule separately, and confirm each lands where you intended. This is where you catch two rules whose conditions overlap.
5. Check the routing fields if you set up custom field choices. File from a couple of different situations and confirm the Agent classified each correctly.

Note: Each rule fires at most once per Conversation, so you can't test the same rule twice in one chat. Start a new Conversation for each attempt.

What Handover Doesn't Do

Worth knowing before you rely on it:

• The Conversation doesn't close. The guest keeps chatting with the Agent, which is usually what you want. To find Conversations with a handover, look for the Handover tag in the Conversations list, or filter with handover:true.
• A filed handover can't be updated. If the guest adds important detail afterwards, it does not reach the ticket. That's why the Agent gives the guest a heads-up before it files. After filing, it doesn't ask more questions about that request. If the guest adds something anyway, the Agent tells them plainly that it couldn't pass it on and points them to a contact route from its instructions. A different rule can still fire in the same Conversation.
• There's no Insights metric. You can't see a count of handovers in your dashboard today. Your inbox and your Freshdesk queue are where you measure this.
• Your team replies in your tools, not here. Answering the email or the Freshdesk ticket reaches the guest through those systems, not through the Agent's chat.

What's Next

Handover is the safety net. These help with everything that happens before it:

• How the Agent Works -- see where Features sit alongside the Knowledge Base
• Understanding Places and Resources -- the better the Agent's knowledge, the less it needs to escalate
• Agent Settings to Review Before Going Live -- work through the pre-launch checklist