Transferring the call
There are cases when the bot needs to hand off the call to another party. Usually, it will happen if the bot cannot handle the call by itself, so it needs to escalate the call to a live (human) agent. In other cases, the normal flow of the call is for the bot to perform only a fraction of the conversation, and then hand off the call to another bot or a live agent for the rest of the conversation.
VoiceAI Connect Enterprise allows the bot to actively transfer (hand-off / escalate) the call at any stage of the conversation.
If necessary, the bot can specify SIP headers that will be added to the generated SIP INVITE messages.
By default, once VoiceAI Connect Enterprise performs the transfer, it immediately disconnects the call with the bot, regardless of whether the transfer succeeded or not. If needed, VoiceAI Connect Enterprise can be configured to allow the bot to regain control over the call after a failed transfer attempt. In such a scenario, the bot can use its logic to select its next action, like playing a prompt or transferring the call to another target.
The following diagram presents a high-level flow for call transfer:
VAICPreserveTelURI
parameter on the SBC to 1
.For details on configuring call transfer on Live Hub, click here.
How do I use it?
To transfer the call, the bot should send a transfer event (or a handover event which is a synonym for the transfer event).
The target of the transfer should be specified in the transferTarget
parameter.
For example:
{ "type": "event", "name": "transfer", "activityParams": { "transferTarget": "tel:+123456789" } }
To transfer the call, the bot should send a transfer event (or a handover event which is a synonym for the transfer event).
The target of the transfer should be specified in the transferTarget
parameter.
For example:
{ "type": "event", "name": "transfer", "channelData": { "activityParams": { "transferTarget": "tel:+123456789" } } }
VoiceAI Connect Enterprise supports Copilot Studio native 'Transfer to agent'.
Before using the native option, the transfer details needed to be stored as a record:
Insert the transfer parameters as a formula (see example for basic format):
Specify the target of the transfer in the transferTarget
parameter:
After saving the transfer parameters as a record, create a transfer conversation (under Topic management):
Add the variable in the dialog box:
Example:
{ activityParams: { transferTarget: "tel:+123456789", transferNotifications: true } }
Note: To use Copilot variable as transferTarget
, switch the string to a variable:
{ activityParams: { transferTarget: Topic.variable, transferNotifications: true } }
VoiceAI Connect Enterprise supports Copilot Studio legacy bot native 'Transfer to agent'. To transfer the call, select the Transfer to agent in the desired topic.
You can add all the transfer event parameters in the 'Private message to agent' text.
The target of the transfer should be specified in the transferTarget
parameter.
For example:
{ "activityParams": { "transferTarget": "tel:+123456789" } }
For Dialogflow CX, call transfer is done by adding the "Live agent handoff" fulfillment, as shown in the following example of configuration through the Dialogflow CX user interface:
The "Live agent handoff" fulfillment content is used to specify parameters like the target of the transfer (the transferTarget
parameter):
{ "activityParams": { "transferTarget": "tel:+123456789" } }
As an alternative, transfer can be initiated by adding a "Custom Payload" fulfillment with the transfer
event:
{ "activities": [{ "type": "event", "name": "transfer", "activityParams": { "transferTarget": "tel:+123456789" } }] }
To transfer the call, the bot should send a transfer event (or a handover event which is a synonym for the transfer event).
The target of the transfer should be specified in the transferTarget
parameter.
This is done by adding a Custom Payload response with the following content:
{ "activities": [{ "type": "event", "name": "transfer", "activityParams": { "transferTarget": "tel:+123456789" } }] }
Event parameters
The following table lists the parameters associated with this event:
See Changing call settings for details on how these parameters can be applied.
Parameter |
Type |
Description |
---|---|---|
String |
URI to where the call should be transferred call to. Typically, the URI is a "tel" or "sip" URI. |
|
String |
Conveys a textual reason for the transfer. The value of this parameter will appear on the CDR of the call. |
|
Array of Objects |
Array of objects listing SIP headers that should be sent to the transferee. Each object comprises a name and a value attribute. The total length must not exceed 12,000 characters. Up to 100 SIP headers can be defined. For more information, see Adding SIP headers below. |
|
String |
Defines the party (URL) who initiated the call referral. If this parameter exists, the SBC adds a SIP Referred-By header to the outgoing INVITE or REFER message. If the SBC handles locally (termination), the SBC adds it to a new outgoing INVITE. If not handled locally (regular), the SBC adds it to the forwarded REFER message. |
|
Boolean |
Enables VoiceAI Connect Enterprise to notify the bot on the outcome of call transfer attempts.
For more information, see Handling call transfer failures below. VoiceAI Connect Enterprise supports this parameter from Version 2.4 and later.
|
|
Number |
Defines a grace period (in milliseconds) for disconnecting the call after a successful transfer. This parameter is only applicable when The valid value is 0 to 10000. The default is 5000. VoiceAI Connect Enterprise supports this parameter from Version 2.4 and later.
|
Adding SIP headers
When the bot performs a call transfer, it can add data to be sent as SIP headers in the generated SIP message (REFER or INVITE). This is done by the transferSipHeaders parameter. This parameter contains an array of JSON objects with the following attributes:
Attribute |
Type |
Description |
---|---|---|
name |
String |
Name of the SIP header. |
value |
String |
Value of the SIP header. |
For example, the following event can be used to add the header "X-My-Header" with the value "my_value":
{ "type": "event", "name": "transfer", "activityParams": { "transferTarget": "sip:john@host.com", "transferSipHeaders": [ { "name": "X-My-Header", "value": "my_value" } ] } }
{ "type": "event", "name": "transfer", "channelData": { "activityParams": { "transferTarget": "sip:john@host.com", "transferSipHeaders": [ { "name": "X-My-Header", "value": "my_value" } ] } } }
{ "activityParams": { "transferTarget": "sip:john@host.com", "transferSipHeaders": [ { "name": "X-My-Header", "value": "my_value" } ] } }
{ "activityParams": { "transferTarget": "sip:john@host.com", "transferSipHeaders": [ { "name": "X-My-Header", "value": "my_value" } ] } }
The "Live agent handoff" fulfillment content can be used to specify the transferSipHeaders parameter:
{ "activityParams": { "transferTarget": "sip:john@host.com", "transferSipHeaders": [ { "name": "X-My-Header", "value": "my_value" } ] } }
Add a Custom Payload response with the following content:
{ "activities": [{ "type": "event", "name": "transfer", "activityParams": { "transferTarget": "sip:john@host.com", "transferSipHeaders": [ { "name": "X-My-Header", "value": "my_value" } ] } }] }
If VoiceAI Connect Enterprise is configured to handle transfer by sending a SIP INVITE message, it will contain the header, for example:
X-My-Header: my_value
If VoiceAI Connect Enterprise is configured to handle transfer by sending a SIP REFER message, it will contain the value in the URI of the Refer-To header, for example:
Refer-To: <sip:john@host.com?X-My-Header=my_value>
Handling call transfer failures
By default, once VoiceAI Connect Enterprise performs the transfer, it immediately disconnects the call with the bot, regardless of whether the transfer succeeded or not.
By using the transferNotifications
parameter, you can allow the bot to regain control over the call after a failed transfer attempt.
When enabled, VoiceAI Connect Enterprise notifies the bot on the outcome of call transfer attempts. If the transfer succeeded, VoiceAI Connect Enterprise disconnects the call with the bot after the notification. If the transfer fails, the call with the bot resumes (not disconnected).
In addition, you can configure VoiceAI Connect Enterprise with a grace period (using the transferNotificationsHangupMS parameter) for disconnecting the call after a successful transfer. This provides the bot with some time to perform additional actions (for example, sending metadata) before the call is disconnected by VoiceAI Connect Enterprise.
For example, the following event can be used to enable handling of call transfer failures:
{ "type": "event", "name": "transfer", "activityParams": { "transferTarget": "sip:john@host.com", "transferNotifications": true } }
{ "type": "event", "name": "transfer", "channelData": { "activityParams": { "transferTarget": "sip:john@host.com", "transferNotifications": true } } }
{ "activityParams": { "transferTarget": "sip:john@host.com", "transferNotifications": true } }
{ "activityParams": { "transferTarget": "sip:john@host.com", "transferNotifications": true } }
The "Live agent handoff" fulfillment content can be used to specify the transferNotifications
parameter:
{ "activityParams": { "transferTarget": "sip:john@host.com", "transferNotifications": true } }
Add a Custom Payload response with a transfer
event:
{ "activities": [{ "type": "event", "name": "transfer", "activityParams": { "transferTarget": "sip:john@host.com", "transferNotifications": true } }] }
Receiving call transfer notifications
The notifications to the bot are done using the transferStatus event, which is sent by VoiceAI Connect Enterprise after each transfer attempt.
See Receiving transfer status notification for more details on this event.