Phone integration configuration

After you have set up the phone integration for your assistant, you can modify the phone integration settings to customize the call behavior.

Handling call and transfer failures

You can configure the phone integration to transfer the caller to a live agent if the phone connection fails for any reason. To transfer the caller to a human automatically, go to the Advanced tab in the phone integration settings, and make the following configuration selections:

  • SIP target when a call fails: Add the SIP endpoint for your support agent service. Specify a SIP or telephone URI for a general call queue that can redirect requests to other queues. For more information, see Configuring a backup service desk solution.

  • Call failure message: Add the message you want the assistant to say to a caller before it transfers the call to a live agent.

If, after you transfer the call to a human, the connection to a live agent fails for any reason, you can configure what to do.

  • Transfer failure message: Add the message you want the assistant to say to a caller if transfer to a live agent fails. The message can be up to 150 characters in length.

  • Disconnect call on transfer failure: Choose whether to disconnect the call after the failure message. This option is enabled by default. If this option is disabled, when a call transfer fails, your assistant can disconnect or process a different action.

    If you choose to leave a call connected despite a transfer failure, Watson Assistant initiates a new turn to determine the next step. It's important that the Assistant be configured with an Action or webhook that can handle this scenario.

The phone integration supports disaster recovery by providing the ability to do a fast failover to another region instead of routing the call to a live agent when a service outage occurs. This is accomplished by sending a SIP 503 response to the upstream SIP trunking provider, instead of auto referring the call to a live agent when failures happen during the setup of a call. This 503 response can then be used by the SIP trunking provider to reroute the call to another region. If you want to take advantage of this capability, open a service ticket against the Watson Assistant service instance that requires disaster recovery.

Secure the phone connection

You can add security to the phone connection by going to the Advanced options tab in the phone integration settings, and selecting one or both of the following options:

  • Force secure trunking: Select this option to use Secure Real-Time Transfer Protocol (SRTP) to secure the audio that is transmitted over the phone. For more information about RTP, see Call routing details.

  • Enable SIP authentication: Select this option if you want to require SIP digest authentication.

    When SIP authentication is required, all inbound traffic (meaning requests from the SIP provider to your assistant) is authenticated using SIP digest authentication, and must be sent using Transport Layer Security (TLS). If this option is selected, the SIP digest user name and password must be configured, and the SIP trunk being used to connect to Assistant must be configured to use only TLS.

    If you use Twilio as your SIP trunk provider, you cannot enable SIP authentication for outbound SIP trunks to Watson Assistant.

Applying advanced SIP trunk configuration settings

To configure how your assistant interacts with a SIP trunk from an external provider, go to the SIP trunk tab in the phone integration settings, and update the following options in the SIP trunking integration section:

  • SIP INVITE headers to extract: List the headers that you want your assistant to use.

    The SIP INVITE request can include metadata about the call in headers that can be extracted and sent to your assistant using context variables. For example, many companies use Interactive Voice Response (IVR) systems that pass information about an incoming call by using SIP headers. If you want to make use of any of these headers, list the header names here.

    The specified headers, if present in the request, are stored in the context variable sip_custom_invite_headers, along with other related metadata that is automatically extracted from the SIP INVITE. This variable is an array in which each key/value pair represents a header from the request, as in this example:

    {
      "input": {
        "text": "",
          ...
      },
      "context" : {
        "global" : {...},
        "skills" : {...},
        "integrations" : {
          "voice_telephony": {
            "private":{
              "user_phone_number":"+18594213456",
            },  
            "sip_call_id": "Aob2-2743-5678-1234",
            "assistant_phone_number":"+18882346789",
            "sip_custom_invite_headers": {
              "X-customer-name": "my_name",
              "X-account-number": "12345"
            }
          }
        }
      }
    }
    

    You can then reference these headers in your assistant. For example, you might check the header value in a step condition to determine the next step. You can also use these headers when searching the assistant logs; for example, you might search for a custom header to find all the messages associated with particular account.

  • Disable the ring that callers hear while the assistant is contacted: Choose whether you want the caller to hear a signal that indicates the assistant is being contacted.

    A 180 Ringing response is sent from the assistant back to the SIP trunk provider while your assistant processes the incoming call invitation. The ringing response is sent by default.

  • Don't place callers on hold while transferring to a live agent: Choose whether the phone integration puts the caller on hold.

    If your SIP trunk provider manages holds, disable this feature. For example, some SIP trunk providers prefer to have the assistant send a SIP REFER request, so they can put the call on hold themselves.

For more information about the SIP protocol, see RFC 3261 and about the RTP protocol, see RFC 3550.

Configuring a backup service desk solution

When you use the phone integration as the first line of assistance for customers, it's a good idea to have a live agent backup available. You can design your assistant to transfer a call to a human in case the phone connection fails, or if a user asks to speak to someone.

Your company might already have one or more phone numbers that connect to an automatic call dispatcher (ACD), which can queue callers until an appropriate agent is available. If not, choose a service desk solution to use as your backup.

A conversation cannot be transferred from one integration type to another. For example, if you use the web chat integration with service desk support, you cannot transfer a phone call to the service desk that is set up for the web chat.

You must provide the service desk SIP URI for the service desk support solution you use. You must specify this information in your assistant when you enable a call transfer from a dialog node or action step. For more information, see Transferring a call to a live agent.

Optimize your actions for phone interaction

For the best customer experience, design your dialog with the capabilities of the phone integration in mind:

  • Do not include HTML elements in your action responses. To add formatting, use Markdown. For more information, see Formatting responses.

  • You can use a search extension to include search results in actions that the phone integration will read. When search results are returned, the phone integration reads the introductory message (for example, I found this information that might be helpful), and then the body of only the first search result.

    The entire search response (meaning the introductory message plus the body of the first search result) must be less than 5,000 characters long or the response will not be read at all. Be sure to test the search results that are returned and curate the data collection that you use as necessary.

For more information about using the search integration, see Leveraging existing help content.

For more information about how to implement common actions from your dialog, see Handling phone interactions.

Creating a SIP trunk

If you do not use the option to generate a free phone number, you must set up the SIP trunk that is used by the phone integration. Find a provider and create a SIP trunk account, for which you must pay per usage.

You can set up a SIP trunk in the following ways:

Setting up a Twilio SIP trunk

Before you begin the setup of a Twilio SIP Trunk, do the following prerequisite steps:

If you already created a SIP trunk, follow steps in Configure a SIP Trunk.

Create a SIP trunk

  1. Login to your Twilio account and go to Explore Products.

    Note: If you do not see Explore Products on the sidebar, do the following:

    1. Search for 'Elastic SIP Trunking' in the Search Bar.
    2. Click Elastic SIP Trunking Dashboard.
    3. Go to step 3.
  2. Click Elastic SIP Trunking dashboard.

  3. On the Elastic SIP Trunking Dashboard page, click Get Started.

  4. Click Create a SIP Trunk button to open Create A New SIP Trunk dialog box.

  5. Enter a name for your SIP trunk in the FRIENDLY NAME field.

  6. Click Create button.

For configuration of a SIP trunk, follow steps in Configure a SIP Trunk.

Configure the SIP trunk

To configure a SIP trunk do the following:

  1. From the Elastic SIP Trunking Dashboard page, go to Elastic SIP Trunking.

  2. Click Manage.

  3. Click Trunks and select the SIP trunk that you created.

  4. Click Origination from the navigation bar of your SIP trunk.

  5. To add the origination SIP URI, click the Add new Origination URI button and provide the values for the following fields:

    • Origination SIP URI - You can get the SIP URI for your phone integration from the assistant's phone integration configuration page. To do this in assistant, launch the tooling and Create Assistant. Choose Add integration and select Phone. From your assistant, copy the SIP URI and paste it in Origination SIP URI field of Twilio.
    • Priority - Priority ranks the importance of the URI. A lower number represents the highest importance.
    • Weight - Weight is used to determine the share of load when more than one URI has the same priority. The higher the value, the more load a URI is given.
    • Enabled - You need to switch the Enabled toggle to Yes. This means that origination SIP URI is enabled.
  6. If you plan to support call transfers, enable Call Transfer (SIP REFER) in your SIP trunk. If you expect to transfer calls to the public switched telephone network (PSTN), also enable PSTN Transfer on your trunk.

  7. Select Numbers from the navigation bar for your SIP trunk, and then do one of the following things:

    1. Click Add a number and then Buy a Number*.
    2. If you already have a number, you can click Add a number and then Add an Existing Number.

If you use a Lite or Trial Twilio account for testing purposes, then be sure to verify the transfer target. For more information, see the Twilio documentation.

You cannot enable SIP authentication if you choose Twilio as your SIP trunk provider. Twilio doesn't support SIPS for originating calls.

Using other third-party providers

You can ask for help setting up an account with another SIP trunk provider by opening a support request.

IBM has established relationships with the following SIP trunk providers:

The SIP trunk provider sets up a SIP trunk for your voice traffic, and manages access from allowed IP addresses. Most of the major SIP trunk providers have existing relationships with IBM. Therefore, the network configuration that is required to support the SIP trunk connection typically can be handled for you with minimal effort.

  1. Create a support case.
  2. Provide the following details to your case, if applicable:
    • Topic: Watson Assistant
    • Subtopic: Phone & SMS Integration
    • Subject: SIP trunk provider setup for Watson Assistant
    • Description:
      • Company Name
      • Your IBM Cloud account ID
      • Your Watson Assistant service name
      • Network diagram with IP address or SIP trunk provider information

Bring your own SIP trunk

If you choose to use a SIP trunk carrier that IBM does not have an established relationship with, you can do so.

The following table lists the fully qualified domain names and IP addresses that are used for SIP connections.

SIP network information
Location Domain names IP addresses
US East (N. Virginia) public.01.voip.us-east-1.aws.watsonassistant.ibm.com
public.02.voip.us-east-1.aws.watsonassistant.ibm.com
35.172.81.217
52.206.161.38

Migrating from Voice Agent with Watson

If you created an IBM® Voice Agent with Watson™ service instance in IBM Cloud to enable customers to connect to an assistant over the phone, consider using the phone integration instead. You can use the same SIP account and phone number that you configured for use with Voice Agent with Watson in the phone integration.

The phone integration provides a more seamless integration with your assistant. However, the integration currently does not support the following functions:

  • Outbound calling
  • Configuring backup locations
  • Event forwarding to save call detail reports in the IBM Cloudant for IBM Cloud database service
  • Reviewing the usage summary page. Use IBM Log Analysis instead. For more information, see Viewing logs.

To migrate from Voice Agent with Watson to the Watson Assistant phone integration, complete the following steps:

  1. From the Voice Agent with Watson page, copy the phone number or numbers that you used for your SIP account.

  2. When you set up the Watson Assistant phone integration, add the phone number or set of numbers that you copied in the previous step.

  3. From the phone integration setup page, copy the SIP uniform resource identifier (URI).

  4. In your SIP trunk account, replace the Voice Agent with Watson URI that you specified previously with the URI that you copied from the phone integration setup page in the previous step.

    For example, if you use a Twilio SIP trunk, you would add the assistant's SIP uniform resource identifier (URI) to the Twilio Origination SIP URI field.

  5. If your SIP trunk provider is not already allowlisted with the Watson Assistant region you are migrating to, follow these instructions to get access to your SIP trunk.

Call routing details

Incoming calls to your assistant follow this path:

  1. A customer calls the customer support phone number that is managed by your Session Initiation Protocol (SIP) trunk provider.

  2. The SIP trunk service sends a SIP INVITE request to your assistant's phone integration to establish a connection.

  3. The phone integration connects to the speech services that are required to support the interaction.

  4. After the services are ready, the connection is established, and audio is sent over the Real-time Transport Protocol (RTP).

    RTP is a network protocol for delivering audio and video over IP networks.

  5. The greeting action of the assistant is processed. The response text is sent to the Text to Speech service to be converted to audio and the audio is sent to the caller.

  6. When the customer says something, the audio is converted to text by the Speech to Text service and is sent to your assistant for evaluation.

  7. The assistant processes the input and calculates the best response. The response text from the assistant is sent to the Text to Speech service to be converted to audio and the audio is sent back to the caller over the existing connection.

  8. If the caller asks to speak to a person, the assistant can transfer the person to a call center. A SIP REFER request is sent to the SIP trunk provider so it can transfer the call to the call center SIP URI that is specified in the dialog node where the transfer action is configured.

  9. When one of the participants of the call hangs up, a SIP BYE request is sent to the other participant.