Skip to content

Human Handoff

Human Handoff lets an agent stop replying and route a live user to a person when the conversation should no longer be handled by AI.

Use it for cases where the agent can recognize the need for escalation, but the next response should come from your team.

Choose the response mode before configuring handoff

Open Advanced → Response mode in Agent Editor and choose how external client messages should be handled:

Mode What happens Use it when
AI replies The Agent answers normally and can hand selected conversations to a person when Human Handoff is enabled. AI should handle the approved scope and escalate exceptions.
Human replies only Every external message is saved for a person. The Agent sends no automatic reply, handoff message, or handoff notification. Your team should answer every external message and only use Codeer to receive and operate the conversations.

Human replies only is an overall operating choice for this Agent, not a handoff triggered by the Agent. It does not turn Live Test into a human queue. After changing the response mode, click Apply, publish the new Agent version, and verify the behavior in a real or staging Channel.

When to use it

Good handoff rules usually cover situations like:

  • the user asks to speak with a person
  • the case is urgent, sensitive, or outside the approved scope
  • the agent has gathered enough context and the next step requires manual follow-up
  • the conversation is stuck after repeated clarification

Do not use Human Handoff as a replacement for normal routing. If another agent can handle the work, use Call Agent. If you only need structured details before follow-up, use Request Form.

Configure it in Agent Editor

Open the agent in Editor, find Human Handoff, and set:

  • Enable human handoff: allows the agent to enter human-only mode for live users.
  • Idle timeout (minutes): optional. When set, the user returns to AI mode after this many idle minutes. Leave it blank when a person should switch the user back manually.
  • Handoff instructions: tells the agent when it should stop answering and hand the client to a person.

After changing the setting, use Apply to save a new version. Publish the version only after the handoff path has been tested.

Where handoff is available

The handoff tool is only available in live end-user conversations where Codeer can identify the external user. It is not the same as using Live Test inside the editor.

Notify your team when handoff happens

The Handoff notifications area in Agent Editor is a read-only summary of this agent's current notification mode and effective destinations. It does not create, edit, or delete destinations.

Select Manage workspace notifications to open the Agent handoff event and this agent in Workspace Notifications. Agents without an individual setting use the workspace rule automatically. Add an individual setting only to configure one of these exceptions:

  • Custom destinations: select existing compatible destinations for this agent.
  • Notifications off: do not notify the team when this agent hands off.

Changing an existing setting to Notifications off removes its custom destination selections. To resume custom notifications later, edit the setting and select the destinations again.

Delete the individual setting to return the agent to the workspace rule. If the deleted setting had Notifications off, notifications resume when the workspace rule is available. Custom destinations only changes which existing destinations this agent uses. To add, edit, test, verify, enable, disable, or delete a destination, use the Destinations tab in Workspace Notifications.

The effective destinations summary excludes disabled, unverified, or incompatible destinations. If the workspace rule is missing, disabled, or has no available destination, agents using the default do not send notifications. Delivery resumes when the workspace rule becomes available again.

Keep webhook URLs private

A Slack webhook URL is a secret. Create and manage it only in Workspace Notifications, and do not paste it into public documents, issue comments, screenshots, or source code.

Write narrow handoff instructions

The instructions should say exactly when the agent should stop and hand over. Avoid broad rules such as "handoff when needed".

Example:

Request human handoff when the user asks for a person, reports an urgent billing or safety concern, or has already answered the qualification questions and wants a callback. Before handing off, summarize the reason in one sentence and do not continue troubleshooting.

What users experience

When the agent triggers handoff, the platform sends a short message telling the user that the conversation has been handed to a human teammate. After that, the agent stops generating AI replies for that user and agent.

While human-only mode is active:

  • new user messages are still saved in the conversation history
  • the agent does not answer those messages
  • file attachments remain attached to the recorded user turn
  • if an idle timeout is set, each new message extends the timeout window

When the timeout expires, the next user message can be handled by AI again. If no timeout is set, an operator needs to switch the user back to AI mode.

Operate handoffs from Customers

After a user has interacted with an agent, open that user from Customers. The user detail page shows agent routing information, including the current interaction mode, why it changed, and when human mode expires.

Operators with edit permission can:

  • switch an agent interaction from AI to Human
  • switch an active human interaction back to AI
  • see whether the current human mode came from the agent, a manual CRM change, or an automatic timeout

Manual Human mode is only available when the agent is published and handoff is enabled for that agent.

Test before publishing

Use a real channel or staging experience when possible, because Human Handoff depends on end-user identity. Confirm these paths:

  • the agent hands off when the configured condition appears
  • the handoff message is clear
  • follow-up user messages are recorded but not answered by AI
  • the user returns to AI after the timeout, or can be switched back manually