Integrating with phone

Handle call and transfer failures

You can configure the phone integration to transfer the caller to a human agent if the phone connection fails for any reason. To transfer the caller to a human agent automatically, 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 backup support.
• Call failure message: Add the message to say to a caller before you transfer them to a human agent.

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

• Transfer failure message: Add the message to stream to callers if the transfer to a human agent fails. The message can be up to 1,024 characters in length.
• Disconnect call on transfer failure: Choose whether to disconnect the call after sharing the failure message. This option is enabled by default. If disabled, when a call transfer fails, your assistant can disconnect or process a different dialog node.

Secure the phone connection

You can add security to the phone connection by selecting one or both of the following configuration 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.

Apply advanced SIP trunk configuration settings

• SIP INVITE headers to extract: List headers that you want to use in your dialog.

  The SIP request often sends INVITE headers with information about the request that is used by the SIP network. For example, many companies use Interactive Voice Response (IVR) systems that pass information about an incoming call by using 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. This variable is an array in which each key/value pair represents a header from the request, as in this example:

  "sip_custom_invite_headers": {
    "X-customer-name": "my_name",
    "X-account-number": "12345"
  }
  

  You can then reference these headers in your dialog. For example, you might check the header value in a dialog node condition to determine whether to process a branch. 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 will hear while the assistant is contacted: Choose whether you want the caller to hear a signal that indicates that 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.

Creating a Twilio SIP trunk

To set up a Twilio SIP trunk, complete the following steps:

1. Create a Twilio account on the Twilio website.

2. From the Twilio website, go to the Elastic SIP Trunking dashboard.

3. Select Trunks from the navigation bar and create a SIP trunk. If you already have a SIP trunk, click the plus sign (+). Enter a name for your SIP trunk and click Create.

4. From the Elastic SIP Trunks page, select your SIP trunk.

5. Select Origination from the navigation bar for your SIP trunk and configure the origination SIP URI.

   You can get the SIP URI for your phone integration from the phone integration configuration page.

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:

   • Click Buy a Number.
   • If you already have a number, you can click the plus sign (+) to provision a new phone number in your region.

8. Assign the number to the SIP trunk you created by going back to the SIP trunk and clicking the number sign (#) icon.

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

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:

• Five9
• Genesys
• Vonage
• Voximplant

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 IBM Cloud case.

2. Click Customer success as the case type.

3. For Subject, enter SIP trunk provider setup for Watson Assistant.

4. Include the following information in the 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 that are used for SIP connections.

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, use 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.

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 HTTP 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 welcome node of the dialog 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's dialog skill for evaluation.

7. The dialog processes the input and calculates the best response. The response text from the dialog node 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 HTTP request is sent to the other participant.

Viewing logs

The log events that occur in the components that are used by the phone integration are written to IBM Log Analysis. To check the logs, create an instance and configure the platform logs to observe the region where your service instance is hosted.

For more information about setting up an instance, see Provisioning an instance.

Currently, the Phone and SMS with Twilio integrations are the only components of your assistant that write logs to the IBM Log Analysis dashboard.

After you create the instance, get log information by completing the following steps:

1. Go to the IBM Cloud Logging page.

2. Click Options, then choose Edit platform.

3. Select the region and instance, and then click Select.

4. To open the IBM Log Analysis console, click Open Dashboard.

5. The source name of the log events is Watson.

   You can apply filters or search the logs by values such as a phone number or instance ID.