Configuring call transfer

Initiating call transfers

In Version 1.0.0.2 and later, call transfer is initiated in the Watson Assistant service by defining the vgwActTransfer action tag in the JSON node definition.

{
  "output": {
    "vgwAction": {
      "command": "vgwActTransfer",
      "parameters": {
        "transferHeader": "User-to-User",
        "transferHeaderVal": "12a345b6c7d8901234e5;encoding=hex;purpose=foo;content=bar",
        "transferTarget": "tel:+18883334444"
      }
    }
  }
}

If you define a SIP URI as the transfer target, be sure to escape the @ character in the URI so that the value isn't processed by Watson Assistant.

  ...
  {
    "transferHeader": "User-to-User",
    "transferHeaderVal": "12a345b6c7d8901234e5;encoding=hex;purpose=foo;content=bar",
    "transferTarget": "sip:12345556789\\@myhost.com"
  }
...

Previous Voice Gateway versions used the vgwTransfer state variable initiate the call transfer. Although this state variable continues to function, its use is now deprecated in favor of the vgwActTransfer action tag. For more information, see Deprecated state variables.

Determining if a transfer succeeds or fails

When a transfer process succeeds, Watson Assistant receives a text update with the word "vgwCallTransferred" and the vgwCallTransferred state variable set to Yes.

When a transfer fails and the vgwDisconnectCallOnTransferFailure state variable is set to No, Watson Assistant receives a text update from Voice Gateway with the string "vgwCallTransferFailed". This string indicate that a transfer failed. See Transferring upon failure to configure your Watson Assistant service instance and Voice Gateway deployment to respond to transfer failures.

Transferring upon hang up

By default, Voice Gateway performs a transfers calls by using a SIP REFER request. Depending on the IVR service provider, you might need to configure call transfer to use a SIP BYE method instead. See Integrating Voice Gateway with IVRs and contact centers to find more information about IVR service providers.

In the vgwActTransfer action, use the transferMethod attribute to specify how to transfer the call, either REFER or HANGUP. When set to HANGUP, the behavior of the transfer action changes. Instead of sending a SIP REFER request, Voice Gateway plays back any associated text, and then hangs up the call by sending a SIP BYE request.

After the hang up, Voice Gateway passes the transfer destination that is specified in the transferTarget attribute to the call anchor in the BYE message. The header field that contains the transfer target is determined by the transferTargetHeader attribute. If the transferTargetHeader attribute isn't specified, Voice Gateway uses Transfer-Target. If you don't include the transferMethod attribute when you configure your call transfer action, vgwActTransfer uses the REFER method by default.

{
  "output": {
     "vgwAction": {
      "command": "vgwActTransfer",
      "parameters": {
        "transferTarget": "tel:18883334444",
        "transferTargetHeader": "Transfer-Target",
        "transferMethod": "HANGUP"
      }
    }
  }
}

Transferring upon failure

You can configure the voice gateway to automatically transfer a call to a static endpoint if a failure occurs. Failures can occur, for example, if the voice gateway loses connectivity to one of the configured Watson services.

The following state variables can be set on the first turn of the conversation and are used if a failure occurs during the call. See Defining actions and states.

For example, the following state variable tells Voice Gateway that starting from this node response, if a call transfer fails, the vgwTransferFailedMessage is streamed to the caller before ending the call.

{
  "context": {
    "vgwDisconnectCallOnTransferFailure": "Yes",
    "vgwTransferFailedMessage": "Call transfer to an agent failed. Please try again later. Good bye."
  }
}

If the voice gateway can't reach Watson Assistant, the following configuration environment variables can be used to force a transfer to a static phone number.

Configuring Voice Gateway to process error codes as successful responses

When Voice Gateway processes a SIP NOTIFY request during a call transfer, the transfer process fails if the response code that is specified in a NOTIFY request isn't in [200-299] range. Some IVR systems might send an error code in a NOTIFY request even though the transfer was successful. You can configure a list of error codes that Voice Gateway handles as successful responses with the ACCEPT_TRANSFER_REJECT_CODES configuration attribute or with the vgwActTransfer attribute, acceptTransferRejectCodes.

In the following configuration attribute example, if a NOTIFY request contains 410 or 500 error codes, Voice Gateway processes the NOTIFY request as a successful request, and proceeds with the transfer process.

ACCEPT_TRANSFER_REJECT_CODES=410,500

You can use the acceptTransferRejectCodes attribute in the vgwActTransfer action to specify the list of the error codes that are treated as successful responses when processing NOTIFY requests. The following example shows how to use the vgwActTransfer action to configure Voice Gateway to process a NOTIFY request that contains 410 or 500 error codes as a successful request.

{
"command": "vgwActTransfer",
"parameters": {
"transferTarget": "tel:999",
"acceptTransferRejectCodes": "410,500"
}
}

Sending User-to-User Information (UUI) data in call transfers

Voice Gateway can send User-to-User Information (UUI) data in a SIP REFER message, a SIP BYE request, or a SIP INFO request.

When Voice Gateway transfers a call, it can send UUI data in the SIP REFER message. In Version 1.0.0.4c and later, Voice Gateway supports the following header fields for sending UUI data in a REFER request:

• User-to-User
• Contact
• Refer-To

If you transfer a call using a SIP BYE request, UUI data is sent in a User-to-User header field in Version 1.0.0.7 and later.

{
  "output": {
    "vgwAction": {
      "command": "vgwActTransfer",
      "parameters": {
        "transferTarget": "sip:+18883334444@example.com",
        "uuiData": "59a390f3d2b7310023a2;encoding=hex;purpose=abc;content=123",
        "uuiSendMethod": "contactHeader"
      }
    }
  }
}

{
  "output": {
    "command": "vgwActSendSIPInfo",
    "parameters": {
            "sipHeaders": {
              "Content-Type": "multipart/mixed;boundary=unique-boundary-1"
            },
            "messageBody": "--unique-boundary-1\r\nContent-Type: application/dtmf-relay\r\nSignal=999#\r\nDuration=250\r\n--unique-boundary-1--"
          }
        }
}

{
  "vgwSIPFailureReason": {
    "sipMessage": "INFO",
    "failureReason": "A 400 Bad Request error response message was received"
  }
}

Contact: <sip:+18883334444@example.com?User-to-User=59a390f3d2b7310023a2%3Bencoding%3Dhex%3Bpurpose%3Dabc%3Bcontent%3D123>

Tracking calls by passing GUIDs

Enterprise telephony systems can be configured to add a globally unique ID (GUID) as a User-to-User header to incoming SIP calls. The GUID is used to track a call throughout its lifetime within the enterprise network. The voice gateway can be configured to extract the GUID from the initial SIP invite and pass the same GUID as a header in a subsequent REFER message. Passing the GUID ensures a call can be properly tracked as it propagates to a contact center agent.

The CUSTOM_SIP_INVITE_HEADER configuration environment variable identifies the custom header that is pulled out of the initial SIP INVITE message that establishes the call. When you specify this environment variable, the specified SIP header is passed to Watson Assistant in the vgwSIPCustomInviteHeader state variable.

To set the custom header in the outgoing REFER message, you can use the action tags and state variables for UUI data or the custom transfer header state variables as described in the previous section.