Skip to main content

Handover

Moveo allows you to transfer the conversation to a live agent when necessary. This can be useful if the AI agent does not understand the user's questions or if the user brings up a sensitive topic.

To perform a handover, add the handover action in the dialog. All conversations where the AI agent has left the chat and have not been assigned to an agent are available in the Chat menu, under the Unassigned section.

A dialog that sends a text message and then runs the Handover action.A dialog that sends a text message and then runs the Handover action.

Zendesk department routing​

Choose which Zendesk department handles the conversation when the handover action is triggered. To do this, copy the department ID from the Zendesk integration settings. Then, in the handover action of the dialog, select Zendesk department routing and paste the ID in Department routing.

Zendesk DepartmentsDialog
The Departments card of the Zendesk integration, with the Copy id link for each Zendesk department.The Departments card of the Zendesk integration, with the Copy id link for each Zendesk department.The Handover action with Zendesk department routing selected and a department ID.The Handover action with Zendesk department routing selected and a department ID.

Routing methods​

The handover action chooses the Zendesk department in this order:

  1. The zendesk_department_id key in the metadata of the action.
  2. The department_id of the action, which is the Department routing field in the console.
  3. The department that the chat comes from. Moveo transfers the chat only when that department is online in Zendesk.

A handover with no department ID keeps the department of the chat. This is the Default option in the console:

{ "type": "handover" }

To route to a fixed department, select Zendesk department routing and enter the ID in Department routing. The console saves the action as:

{ "type": "handover", "department_id": "12345" }

To route to a department that the conversation decides, put a context variable in metadata.zendesk_department_id. The AI agent replaces {{$zendesk_department}} with the value of the variable when the action runs:

{
  "type": "handover",
  "metadata": { "zendesk_department_id": "{{$zendesk_department}}" }
}

The console does not show the metadata field. Set it with PUT /v1/brains/{brain_id}/dialogs/{dialog_id} or the Moveo MCP server. Set the variable before the handover, for example with a Set variables action. If the variable is not set, the AI agent sends %UNKNOWN% as the department ID.

Send new chats to the AI agent first​

To let the AI agent answer first and then hand over to your team, use two Zendesk departments:

  1. In Zendesk, create a department for the AI agent that holds only the Zendesk agent of Moveo.
  2. In the Moveo Zendesk integration, under Departments, turn on Moveo for that department. See Zendesk Chat.
  3. In the handover action, select Zendesk department routing. In Department routing, enter the ID of the department of your human agents.
  4. On your website, add a script that selects the department of the AI agent for each new chat.

This script uses the Zendesk Web Widget Classic API. Replace AI agent with the name of your department, and fill in the details of the signed-in user. Add zESettings before the Web Widget snippet, and the zE calls after it:

<script type="text/javascript">
  window.zESettings = {
    webWidget: {
      chat: {
        departments: { select: 'AI agent' },
      },
    },
  };
</script>
<!-- The Zendesk Web Widget snippet goes here -->
<script type="text/javascript">
  zE('webWidget', 'identify', { name: 'Jordan Lee', email: 'jordan.lee@example.com' });

  zE('webWidget:on', 'open', function () {
    if (!zE('webWidget:get', 'chat:isChatting')) {
      zE('webWidget', 'chat:send', 'Hello');
    }
  });
</script>
  • departments.select sends each new chat to the department of the AI agent.
  • identify passes the name and email of the user to Zendesk Chat.
  • The open handler sends a first message, so that the chat starts and the AI agent greets the user.

See departments.select, identify, and chat:send in the Zendesk documentation.

Facebook Messenger handover​

Hand the conversation over to Facebook Messenger inbox by enabling the respective field in the dialog.

Voice handover​

When configuring handover for voice agents on Twilio Voice or Telnyx Voice, the active call leg is transferred to a destination you specify in the handover action's settings. Provide either:

  • An E.164 phone number (for example, +12025551234), or
  • A SIP URI (for example, sip:agent@example.com)

Transfer method​

Choose how the active call is transferred:

  • Standard transfer (default): Moveo stays on the call and connects the caller to the agent. Recording continues. Works with a phone number or a SIP destination.
  • SIP REFER: Moveo hands the call to your phone system and drops off; recording continues on your side. Requires a SIP destination, and the incoming call must have arrived over SIP. SIP REFER cannot transfer a caller who reached you over a phone line.

See Voice call transfer for how each method works, a comparison, and when to use which.

The Handover action with Voice handover, a SIP destination, and Standard transfer selected.The Handover action with Voice handover, a SIP destination, and Standard transfer selected.
Pause before handover

Add a Pause action of 1–2 seconds immediately before Handover so the caller hears the AI agent's last sentence in full before the call is transferred.

Custom SIP headers​

When the destination is a SIP URI, you can attach custom SIP headers to the transfer through the SIP Headers field of the handover action. Each attribute is a key–value pair sent as a SIP header on the outgoing call leg, allowing the receiving system to route or label the call based on context from the AI agent.

Allowed header names:

  • Any X-* custom header, except headers starting with the prefix your provider reserves: X-Twilio on Twilio Voice and X-Telnyx on Telnyx Voice.
  • The following standard SIP headers: User-to-User, Remote-Party-ID, P-Preferred-Identity, P-Called-Party-ID.

Headers outside the allow-list are silently dropped before the transfer. The combined size of all header names and values, after URL encoding, must not exceed 1024 characters.

Attributes are ignored when the destination is a phone number. SIP headers only apply to SIP URI destinations.

Example handover attributes for a SIP destination:

KeyValue
X-Customer-Id12345
User-to-Userpriority=high;origin=ai-agent

Limitations​

  • Browser calls on Twilio Voice do not support handover. The transfer is rejected by the provider because a browser-origin call has no caller ID to use on the transferred leg. Gate the Handover action in your workflow so it does not run on these calls.
  • Web Voice calls are not transferred. On a handover, the call ends and a human agent continues the conversation in the chat of the widget. See Handover during a call.
  • Standard transfer keeps both legs billed. The original inbound leg stays open while the new outbound leg to the destination is dialled, so both are billed. With SIP REFER, Moveo leaves the call path once the transfer succeeds and is not part of the onward call.
  • Recording on a Standard transfer continues into the transferred call. With SIP REFER, Moveo's recording stops at the handoff (the onward call is between the caller and your system). See Voice call transfer.
  • No automatic retry. If the destination is busy, does not answer, or rejects the transfer, the call drops. There is no built-in fallback. Handle this in your AI agent workflow if needed.

Zendesk voice handover setup​

An example of a successful implementation for voice handover is shown below, using Twilio Voice as the provider. It uses two separate numbers configured in Zendesk.

The same pattern applies with Telnyx Voice: forward the calls to the Telnyx number connected to the integration, and Moveo transfers the call to the agent number on handover.

To configure these numbers in Zendesk, navigate to Admin settings → Channels → Talk → Lines.

Number configuration​

Number 1: "Forwarding Number" (user entry point)Number 2: "Agent Number" (handover target)

This is the primary number the user calls to initiate a conversation.

  • It is configured in Zendesk with an overflow rule
  • This rule immediately forwards all incoming calls to the Twilio number associated with the Moveo integration
Zendesk overflow rule

This is a separate Zendesk number.

  • It is configured to route calls directly to a specific department or group of available agents
Zendesk routing rule

Handover flow​

  1. Call initiated: The user dials the forwarding number (#1)

  2. Moveo connects: The Zendesk overflow rule instantly forwards the call to the Moveo Twilio integration. The user begins their conversation with the Moveo voice assistant

  3. Handover triggered: When a handover event is triggered (via dialog configuration), the Moveo platform executes the next step

  4. Twilio API transfer: Moveo makes a Twilio API call on the active call leg. This API call instructs Twilio to dial and transfer the user to the agent number (#2)

  5. Call received in Zendesk:

    • If agents are available: The call is routed to the configured department, and available agents are notified to pick up the call
    • If no agents are available: The call is dropped. However, Zendesk provides native options to manage this scenario, such as:
      • Sending the user to voicemail
      • Automatically creating a ticket for the abandoned call
      • Offering the user a callback when an agent becomes available

Next steps​

Last updated on