Call transfer

Sometimes the bot needs to hand off the call to another party. This occurs if the bot cannot handle the call by itself, it therefore 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. Live Hub 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 or REFER messages.

Live Hub offers two ways to perform the transfer. The first one is by initiating a new call towards the transfer target, this is used when the SIP server that initiated the original call doesn’t support the SIP REFER message and will end up with two SIP calls that are anchored on Live Hub. This is typically used when the call was originated from a SIP trunk or by a phone number provided by AudioCodes. It also requires a routing rule as described in the routing rule section.

The following diagram presents the flow for call transfer with a SIP INVITE:

If the SIP server that originated the call support the SIP REFER message (typically supported for contact centers), the transfer will be performed by sending a SIP REFER message, after a successful transfer the remote SIP server will disconnect the call with Live Hub, to initiate REFER the remote SIP server should be configured with REFER as the transfer method on the SIP connection advanced tab

The following diagram presents the flow for call transfer with a SIP REFER:

By default, once Live Hub performs the transfer, it immediately disconnects the call with the bot, regardless of whether the transfer succeeded or not. If needed, Live Hub 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.

By default, Live Hub translates the telephone number ('tel' URI) into a SIP URI ('sip:xxx@x.x.x.x'). For example, if the Live Hub receives "transferURL": "tel:+14077511320", it 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 to 1.

Trigger call transfer

{
  "type": "event",
  "name": "transfer",
  "activityParams": {
    "transferTarget": "tel:+123456789"
  }
}

{
  "type": "event",
  "name": "transfer",
  "channelData": {
    "activityParams": {
      "transferTarget": "tel:+123456789"
    }
  }
}

{
  activityParams: {
    transferTarget: "tel:+123456789",
    transferNotifications: true
  }
}

{
  activityParams: {
    transferTarget: Topic.variable,
    transferNotifications: true
  }
}

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

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

{
  "activities": [{
    "type": "event",
    "name": "transfer",
    "activityParams": {
      "transferTarget": "tel:+123456789"
    }
  }]
}

{
  "activities": [{
    "type": "event",
    "name": "transfer",
    "activityParams": {
      "transferTarget": "tel:+123456789"
    }
  }]
}

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

Event parameters

The following table lists the parameters associated with this event:

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:

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

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

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

If Live Hub is configured to handle transfer by sending a SIP INVITE message, it will contain the header, for example:

X-My-Header: my_value

If Live Hub 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 Live Hub 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, Live Hub notifies the bot on the outcome of call transfer attempts. If the transfer succeeded, Live Hub 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 Live Hub 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 Live Hub.

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

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

{
  "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 Live Hub after each transfer attempt.

Set the transfer target number

The transfer target phone number can be specified either by the bot developer on the transfer action, or through Live Hub when you configure the bot.

To configure the transfer target number in Live Hub for the specific bot:

1. In the Navigation pane, select Bots.

2. Select the bot for which you want to enable call transfer, and then click Edit.

3. Click the Features tab.

4. Under Call Transfer, in the 'Transfer number' field, enter the transfer target phone number.

Create a routing rule

You only need to configure a special routing rule for call transfer if the SIP Connection to which Live Hub forwards the bot request is performed with a new call (SIP INVITE). If the SIP Connection supports SIP REFER requests, a routing rule is not needed, and Live Hub simply sends the bot call transfer request as a SIP REFER message to the SIP Connection.

The following describes the specific configuration required for configuring a routing rule for call transfer. For complete instructions for creating routing rules, see information on Add a routing rule.

To configure a routing rule for call transfer:

1. In the Navigation pane, select Routing, and then click the Routing Rules tab.

2. Click Add new routing rule.

3. Under General, from the 'Type' drop-down list, select Transfer.

4. Under Call criteria, from the 'Transferred by' drop-down list, choose the bot that initiated the transfer.

5. Under Route to, from the 'Call destination' drop-down list, select either the phone number used to transfer the call, or the relevant SIP Connection.

Viewing Transferred Call History

The following procedure describes how you can view your transferred calls.

1. In the Navigation pane, select Call History.

   

2. Select a call.

3. Select Search for related call records; the transferred calls are displayed.

4. If the selected call is part of a transfer call scenario, the records of the incoming and the outgoing transfer calls are displayed to the user.