Handover Actions

Handover actions transfer the conversation to a human agent. The same handover configuration is also used when a supervisor triggers a takeover via Listen & intervene.

Type

Choose the handover method:

• Phone: Transfer to a specific phone number
• Queue: Transfer to a queue in your contact center system (e.g., a Genesys queue)
• SIP: Transfer via a SIP URI

Queue routing

The most common approach is to define the queue ID in the Parameters Schema rather than hardcoding it in the action itself. This lets a single handover action cover multiple queues — the agent decides which queue to route to based on the conversation, and passes the queue ID when calling the action.

Parameters Schema example (multiple queues, one action):

{
  "type": "object",
  "properties": {
    "queue_id": {
      "type": "string",
      "description": "The queue to route the customer to. Use 'sales' for sales enquiries, 'support' for technical issues, 'billing' for payment questions."
    }
  },
  "required": ["queue_id"]
}

Set a fallback Queue ID even when using this approach. When a handover is triggered by a guardrail or a supervisor takeover via Listen & intervene, there is no agent call to supply the parameter — the fallback Queue ID is used instead. For agent-initiated handovers, the runtime value from the agent takes precedence.

Alternatively, if you always route to the same queue, enter a static Queue ID directly in the action configuration. This is useful when you have separate handover actions per team or intent.

customer_support_tier2

Phone routing

Enter the phone number to route the call to, including the country code:

+31612345678

To route dynamically, use Go template syntax in the Phone number field. You can reference any conversation variable, including built-in call metadata:

• {{ .variables.call.from }} — the caller's phone number
• {{ .variables.call.to }} — the number the caller dialled

For example, to route based on which number was dialled:

{{ if eq .variables.call.to "+31970XXXXXXX" }}+31970XXXXXXY{{ else }}+31612345678{{ end }}

SIP routing

Enter the SIP URI to transfer the call to:

sip:queue@pbx.example.com

To route dynamically, use Go template syntax in the SIP target field. For example, to route based on which number was dialled:

{{ if eq .variables.call.to "638472019" }}sip:sales@pbx.example.com{{ else }}sip:support@pbx.example.com{{ end }}

Choose the transfer method:

• REFER: Hands off the call to the remote side. Completes quickly but relies on the remote side to complete the transfer.
• INVITE: Keeps the call anchored through Stellar. More reliable but requires an auth connector for digest authentication if your PBX requires it.

If REFER is rejected, the gateway automatically falls back to INVITE. See Call transfer for details on how each method works.

Authentication connector

Optionally select a SIP digest authentication connector to provide credentials for the outbound INVITE. This applies both when INVITE is selected as the SIP method and when REFER is rejected and falls back to INVITE. The REFER itself does not use these credentials — the remote PBX handles the outbound leg independently.

Passing context to the contact center

Any extra fields you define in the Parameters Schema are forwarded to the receiving system alongside the routing target. This lets you pass conversation context — such as a summary, reason, or priority — so the human agent receiving the call already has relevant background.

How context is forwarded:

• Genesys (queue): Extra fields are sent as output variables in the disconnect message, available as context data on the incoming interaction.
• SIP: Extra fields are sent as variables in the transfer event, which the SIP gateway maps to X-headers on the REFER or INVITE.

Parameters Schema example (queue ID + summary):

{
  "type": "object",
  "properties": {
    "queue_id": {
      "type": "string",
      "enum": ["sales", "support", "billing"]
    },
    "summary": {
      "type": "string",
      "description": "A brief summary of the conversation and the reason for the handover."
    }
  },
  "required": ["queue_id", "summary"]
}

The agent will collect both values before initiating the transfer. The receiving agent in Genesys (or the SIP endpoint) gets the summary as part of the interaction context — no screen pop or manual note-taking needed.

You can add any number of extra fields this way, for example reason, priority, customer_id, or language.

Fallback announcement

Used when a handover is triggered by a guardrail or a supervisor takeover via Listen & intervene. In these cases, the agent will first speak the specified message before initiating the transfer. For handovers triggered in the normal flow of a conversation (not by a guardrail or supervisor), the agent follows its regular instructions to decide what to say before transferring. Leave this blank if you want these handovers to happen immediately without a spoken message.

I'm transferring you to a human representative.

Example: dynamic queue routing with context

Name: transfer_to_team
Description: Transfer the customer to the appropriate team. Use when the customer needs specialist help or requests a human agent.
  - Use queue 'sales' for purchase or upgrade enquiries
  - Use queue 'support' for technical or account issues
  - Use queue 'billing' for payment or invoice questions
  Before transferring, summarise the conversation in the 'summary' field.

Type: Queue
Queue ID: support
Parameters Schema:
{
  "type": "object",
  "properties": {
    "queue_id": {
      "type": "string",
      "enum": ["sales", "support", "billing"]
    },
    "summary": {
      "type": "string",
      "description": "A brief summary of the conversation and the reason for the handover."
    }
  },
  "required": ["queue_id", "summary"]
}
Fallback announcement: I'm transferring you to a human representative.

Fallback handover action

In your agent's Settings tab, you can designate one handover action as the Fallback Handover Action. This action triggers automatically when an unrecoverable error occurs during a conversation (e.g. voice provider connection lost, internal server error), preventing the caller from being silently disconnected.

If no fallback handover action is configured, fatal errors result in the call being disconnected.

Error context passed on fallback

When a fallback handover is triggered by an error, the following variables are passed to the receiving system (e.g. available as output variables in a Genesys Architect flow):

Variable	Description	Example
stellar.error.code	Machine-readable error code	voice_provider_connection_error
stellar.error.message	User-facing error message	An unexpected error occurred during conversation
stellar.error.severity	Error severity level	fatal
stellar.error.correlation_id	Unique ID for log correlation by Stellar support	550e8400-e29b-41d4-a716-446655440000

You can use these in your call routing logic to route error handovers to a specific queue, surface context to the human agent, or log the correlation ID for troubleshooting with Stellar support.

Next steps

• Configure guardrails that automatically trigger this handover action when certain conditions are met
• Test the handover in the Playground
• Use Listen & intervene to manually trigger a takeover during live calls