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 conversation variables, static variables, and action parameters:

{{ .variables.call.from }} — the caller's phone number
{{ .variables.call.to }} — the number the caller dialled
{{ .parameters.phone }} — a parameter the agent collects at runtime via the Parameters Schema

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

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

From number

The From number controls which caller ID the recipient sees on the transferred call:

Default (original caller) — passes through the original caller's phone number. This is the default. For SIP connections, this falls back to the inbound number because the outbound trunk is resolved by the from number.
Inbound number — uses the number the caller originally dialled (the DID).
A specific outbound number — uses one of your configured outbound trunk provider phone numbers. Only applies to SIP connections.

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. Templates can reference .variables.*, .static_variables.*, and .parameters.* (values collected via the Parameters Schema). The SIP target must always start with a literal sip: or sips: prefix, so only the part after it can be templated. With the INVITE method (the default, described below), the host must also be a literal — only the user part and any URI parameters may be templated, so the call can only be transferred to the host you configured. To route to a dynamic host, use REFER. For example, to route based on which number was dialled:

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

You can also route based on a substring match, using the contains, lower, and other string functions available to templates. For example, to route calls whose From header mentions "acme" to a dedicated queue:

sip:queue@pbx.example.com;campaign={{ if .variables.call.sip_headers.From | lower | contains "acme" }}1001{{ else }}9999{{ end }}

Inbound SIP headers are caller-controlled

SIP headers on an inbound call (such as From) are supplied by the caller or their carrier and are not trustworthy input. Use template conditionals on these headers only to choose among a fixed set of admin-defined destinations, as in the example above. Never use header values to construct the destination itself (for example, interpolating a header directly into the SIP URI), since that would let a caller influence where the call is transferred to.

Choose the transfer method:

INVITE: Keeps the call anchored through Stellar. This is the usual method and works with any trunk. It needs an auth connector for digest authentication if your PBX requires it. The host in the SIP target must be a literal (only the user part and URI parameters may be templated); a templated host is rejected when you save.
REFER: Hands the call off to the remote side, which then completes the transfer itself. On trunk-provider calls, this requires a trunk that allows REFER, a per-trunk setting a super admin controls that is off by default for new trunk providers. REFER allows a templated host, so use it when the transfer host itself must be chosen dynamically.

A REFER on a trunk-provider call whose trunk does not allow it fails the transfer, and there is no automatic fallback to INVITE, so select INVITE for those trunks. Tenant SIP credential calls do not use this per-trunk toggle; REFER remains subject to destination screening. See Call transfer for the trunk setting and details on how each method works.

Authentication connector

Optionally select a SIP digest authentication connector to provide credentials for the outbound INVITE. This applies when INVITE is selected as the SIP method. The REFER method does not use these credentials, since the remote PBX handles the outbound leg independently.

Outbound X-headers

Define custom SIP X-headers to include on the outgoing REFER or INVITE. Use these to pass conversation context — such as a case ID, caller intent, or summary — to your PBX or contact center.

Each header has a name and a value. The X- prefix is added automatically, so enter just the name (e.g., Case-Id, not X-Case-Id). Values support Go template syntax, so you can reference conversation variables, static variables, and action parameters:

Template variable	Source
`.variables.*`	Conversation variables (including call metadata)
`.static_variables.*`	Static variables defined on the agent
`.parameters.*`	Values the agent collects via the Parameters Schema

Example — passing a case ID and summary to a PBX:

Header name	Value
`Case-Id`	`{{ .parameters.case_id }}`
`Summary`	`{{ .parameters.summary }}`
`Caller`	`{{ .variables.call.from }}`

info

Header names may only contain letters, numbers, hyphens, and underscores. You can define up to 16 headers. Values are truncated at 1,024 bytes.

When outbound X-headers are configured, they replace the implicit variable-to-header mapping described below. If no outbound headers are configured, the gateway falls back to sending extra Parameters Schema fields as X-headers for backwards compatibility.

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 (with outbound X-headers): The explicitly configured outbound X-headers are sent on the REFER or INVITE. This is the recommended approach because it gives you full control over header names and supports template expressions.
SIP (without outbound X-headers): Extra Parameters Schema fields are sent as variables in the transfer event, and the SIP gateway maps them to X-headers automatically. This is the legacy behaviour and is used as a fallback when no outbound headers are configured.

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 Advanced 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

Type​

Queue routing​

Phone routing​

From number​

SIP routing​

Authentication connector​

Outbound X-headers​

Passing context to the contact center​

Fallback announcement​

Example: dynamic queue routing with context​

Fallback handover action​

Error context passed on fallback​

Next steps​