Phone integration configuration

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, watsonx 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 watsonx 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 watsonx 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
• Use other third-party providers
• Bring your own SIP trunk
• Migrate from Voice Agent with Watson