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 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 performs the transfer, it immediately disconnects the call with the bot, regardless of whether the transfer succeeded or not. If needed, VoiceAI Connect 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:

By default, when the SBC device receives information to transfer the call from VoiceAI Connect, the SBC translates the telephone number ('tel' URI) into a SIP URI ('sip:xxx@x.x.x.x'). For example, if the SBC receives "transferURL": "tel:+14077511320" from VoiceAI Connect, the SBC changes the 'tel' URI to "Refer-To: <sip:+14077511320@<IP Address of SBC>:5060>" in the SIP message. If you want the SBC to preserve the 'tel' URI, the Administrator should configure the VAICPreserveTelURI parameter on the SBC to 1.

For details on configuring call transfer on Live Hub, click here.

How do I use it?

AudioCodes Bot API

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"
  }
}

Microsoft Bot Framework

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"
    }
  }
}

Microsoft Copilot Studio

VoiceAI Connect supports Copilot Studio 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 'Message to agent' text.

The target of the transfer should be specified in the transferTarget parameter.

For example:

{
  "activityParams": {
    "transferTarget": "tel:+123456789"
  }
}

Microsoft Copilot Studio legacy bot

VoiceAI Connect 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"
  }
}

Dialogflow CX

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"
    }
  }]
}

Dialogflow ES

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
`transferTarget`	String	URI to where the call should be transferred call to. Typically, the URI is a "tel" or "sip" URI.
`handoverReason`	String	Conveys a textual reason for the transfer. The value of this parameter will appear on the CDR of the call.
`transferSipHeaders`	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. For more information, see Adding SIP headers below.
`transferReferredByURL`	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.
`transferNotifications`	Boolean	Enables VoiceAI Connect to notify the bot on the outcome of call transfer attempts. true false (default) For more information, see Handling call transfer failures below. VoiceAI Connect Enterprise supports this parameter from Version 2.4 and later.
`transferNotificationsHangupMS`	Number	Defines a grace period (in milliseconds) for disconnecting the call after a successful transfer. This parameter is only applicable when `transferNotifications` is set to true. 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":

AudioCodes Bot API

{
  "type": "event",
  "name": "transfer",
  "activityParams": {
    "transferTarget": "sip:john@host.com",
    "transferSipHeaders": [
      {
        "name": "X-My-Header",
        "value": "my_value"
      }
    ]
  }
}

Microsoft Bot Framework

{
  "type": "event",
  "name": "transfer",
  "channelData": {
    "activityParams": {
      "transferTarget": "sip:john@host.com",
      "transferSipHeaders": [
        {
          "name": "X-My-Header",
          "value": "my_value"
        }
      ]
    }
  }
}

Microsoft Copilot Studio

{
  "activityParams": {
    "transferTarget": "sip:john@host.com",
    "transferSipHeaders": [
      {
        "name": "X-My-Header",
        "value": "my_value"
      }
    ]
  }
}

Microsoft Copilot Studio legacy bots

{
  "activityParams": {
      "transferTarget": "sip:john@host.com",
      "transferSipHeaders": [
        {
          "name": "X-My-Header",
          "value": "my_value"
        }
      ]
    }
}

Dialogflow CX

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"
      }
    ]
  }
}

Dialogflow ES

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

VoiceAI Connect Enterprise supports this feature from Version 2.4 and later.

By default, once VoiceAI Connect 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 notifies the bot on the outcome of call transfer attempts. If the transfer succeeded, VoiceAI Connect 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 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.

For example, the following event can be used to enable handling of call transfer failures:

AudioCodes Bot API

{
  "type": "event",
  "name": "transfer",
  "activityParams": {
    "transferTarget": "sip:john@host.com",
    "transferNotifications": true
  }
}

Microsoft Bot Framework

{
  "type": "event",
  "name": "transfer",
  "channelData": {
    "activityParams": {
      "transferTarget": "sip:john@host.com",
      "transferNotifications": true
    }
  }
}

Microsoft Copilot Studio

{
  "activityParams": {
      "transferTarget": "sip:john@host.com",
      "transferNotifications": true
    }
}

Microsoft Copilot Studio legacy bots

{
  "activityParams": {
      "transferTarget": "sip:john@host.com",
      "transferNotifications": true
    }
}

Dialogflow CX

The "Live agent handoff" fulfillment content can be used to specify the transferNotifications parameter:

{
  "activityParams": {
    "transferTarget": "sip:john@host.com",
    "transferNotifications": true
  }
}

Dialogflow ES

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 after each transfer attempt.

See Receiving transfer status notification for more details on this event.