vania-janet/multiturn-rag-retrieval-data huggingface dataset:
Integrating with phone ![Plus or higher plans only](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/plus.png) 

IBM Cloud

Adding the phone integration to your assistant makes your assistant available to customers over the phone.

If an end user asks to speak to a person, the phone integration can transfer the call to an agent. Supported live agent and contact center integrations:



* Genesys
* Twilio Flex
* NICE CXone
* Bring your own



There are several ways to add the phone integration to your assistant:



* You can generate a free phone number that is automatically provisioned from IntelePeer. This is available only with new phone integrations. If you have an existing phone integration, you must delete it and create a new one to switch to a free phone number.
* You can connect to a contact center with live agents. For more information about setting up the integration, see [Integrating with phone and NICE CXone contact center](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-deploy-phone-nicecxone).
* You can use and connect an existing number by configuring a Session Initiation Protocol (SIP) trunk from a provider such as Genesys, IntelePeer, or Twilio.



A SIP trunk is equivalent to an analog telephone line, except it uses Voice over Internet Protocol (VoIP) to transmit voice data and can support multiple concurrent calls. The trunk can connect to the public switched telephone network (PSTN) or your company's on-premises private branch exchange (PBX).

When a customer makes a phone call using the telephone number connected to your assistant, the phone integration makes it possible for your assistant to answer. The integration converts output from your assistant into voice audio by using the IBM Watson® Text to Speech service, and the audio is sent to the telephone network through the SIP trunk. When the customer replies, the voice input is converted into text by using the IBM Watson® Speech to Text service.
See [Log limits](https://cloud.ibm.com/docs/assistant?topic=assistant-logslogs-limits) for details.

For a Python script you can run to export logs and convert them to CSV format, download the export_logs_py.py file from the [Watson Assistant GitHub)](https://github.com/watson-developer-cloud/community/blob/master/watson-assistant/export_logs_py.py) repository.





 Understanding logs-related terminology 

First, review the definitions of terms that are associated with Watson Assistant logs:



* Assistant: An application - sometimes referred to as a 'chat bot' - that implements your Watson Assistant content.
* Assistant ID: The unique identifier of an assistant.
* Conversation: A set of messages consisting of the messages that an individual user sends to your assistant, and the messages your assistant sends back.
* Conversation ID: Unique identifier that is added to individual message calls to link related message exchanges together. App developers using the V1 version of the Watson Assistant API add this value to the message calls in a conversation by including the ID in the metadata of the context object.
* Customer ID: A unique ID that can be used to label customer data such that it can be subsequently deleted if the customer requests the removal of their data.
* Deployment ID: A unique label that app developers using the V1 version of the Watson Assistant API pass with each user message to help identify the deployment environment that produced the message.
* Instance: Your deployment of Watson Assistant, accessible with unique credentials. A Watson Assistant instance might contain multiple assistants.
* Message: A message is a single utterance a user sends to the assistant.
* Skill ID: The unique identifier of a skill.
* User: A user is anyone who interacts with your assistant; often these are your customers.
* User ID: A unique label that is used to track the level of service usage of a specific user.
* Workspace ID: The unique identifier of a workspace. Although any workspaces that you created before November 9 are shown as skills in the product user interface, a skill and a workspace are not the same thing.
[Image of the outbound call flow](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/cxone-placecall.png)





 Transferring a caller to a live agent 

You can configure your assistant to transfer a customer to a NICE CXone live agent.

The phone integration uses the [signal](https://developer.niceincontact.com/API/AdminAPI/Contacts/Signal%20a%20Contact) REST API. The p1 attribute is preserved for the session history key. The key can be used to fetch the conversation history and present it to a live agent.



1. Use [Onsignal](https://help.nice-incontact.com/content/studio/actions/onsignal/onsignal.htm) to process the signal event.
2. Save the value of the p1 attribute:



sessionKey = "{p1}"

For example, you can use the [Snippet](https://help.nice-incontact.com/content/studio/actions/snippet/snippet.htm) action:

ASSIGN sessionKey = "{p1}"

Use [Reqagent](https://help.nice-incontact.com/content/studio/actions/reqagent/reqagent.htm) to transfer a call to a live agent.

![Image of call transfer to a live agent](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/cxone-live-agent.png)





 Displaying conversation history to a live agent 

Configure your script to provide a transcript of the assistant conversation to a live agent in a pop-out window. This helps the agent better understand and address a customer's needs.
Note that initial context must be set using a conversation_start node. For more information, see [Starting the conversation](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-startdialog-start-welcome).

Connect to human agent response type allows more text
: In a dialog skill, the response type Connect to human agent now allows 320 characters in the Response when agents are online and Response when no agents are online fields. The previous limit was 100 characters.

Legacy system entities deprecated
: In January 2020, a new version of the system entities was introduced. As of April 2021, only the new version of the system entities is supported for all languages. The option to switch to using the legacy version is no longer available.





 6 April 2021 

Service API endpoint change
: As explained in [December 2019](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-watson-assistant-release-noteswatson-assistant-dec122019), as part of work done to fully support IAM authentication, the endpoint you use to access your Watson Assistant service programmatically is changing. The old endpoint URLs are deprecated and will be retired on 26 May 2021. Update your API calls to use the new URLs.

The pattern for the endpoint URL changes from gateway-{location}.watsonplatform.net/assistant/api/ to api.{location}.assistant.watson.cloud.ibm.com/. The domain, location, and offering identifier are different in the new endpoint. For more information, see [Updating endpoint URLs from watsonplatform.net](https://cloud.ibm.com/docs/watson?topic=watson-endpoint-change).



* If your service instance API credentials show the old endpoint, create a new credential and start using it today. After you update your custom applications to use the new credential, you can delete the old one.
* For a web chat integration, you might need to take action depending on when and how you created your integration.
Use analytics to review your entire assistant at a glance 

The Analyze page provides a summary of the interactions between users and your assistant.

Analytics help you to understand the following things:



* What do customers want help with today?
* Is your assistant understanding and addressing customer needs?
* How can you make your assistant better?



To see analytics information, select Analyze in the navigation bar.



 Choosing the environment and date range 

To get started, choose the [environment](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-publish-overviewenvironments) and date range you want to analyze. All charts and cards reflect data based on the environment and the date range you select. When you change the environment or the date range, the charts and cards on the page update to reflect the new date range. You can also use Refresh to ensure the latest data is shown.

![Time period](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/analytics-time-period.png)





 Unique users, conversations, and user requests 

These three traffic metrics -- unique users, conversations, and user requests -- provide you with data about the volume of user engagements with your assistant.

![Unique users, conversations, and user requests](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/analytics-traffic.png)

Unique user is anyone who interacts with your assistant. User ID identifies each user, using a unique label to track the level of service usage. A unique user can have multiple conversations, but a conversation never has more than one unique user.

Conversation is a set of messages consisting of the messages that an individual user sends to your assistant, and the messages your assistant sends back. Conversations can have multiple requests within a single conversation, but a single request doesn't span more than 1 conversation.
Watson Assistant analytics provide overview statistics on the number of interactions with users and containment rates. Analytics doesn't cumulate statistics across regions. With an active/passive topology, this approach to analytics should be sufficient. However, using an active/active topology likely requires using [webhooks](https://cloud.ibm.com/docs/assistant?topic=assistant-webhook-log) to gather interaction data, and build custom data warehouses and reports to understand total usage.





 Recommendations 

The intent and user example recommendation features use production data to make the recommendations. The available recommendations may vary by instance due to differences in the data across regions.





 Autolearning 

The autolearning feature uses production data to train an improved intent recognizer. The autolearning results may vary by instance due to differences in the data across regions.





 Session history for web chat and the v2 api 

Session history allows your web chats to maintain conversation history and context when users refresh a page or change to a different page on the same website. This feature doesn't work across instances, so in-progress conversations need to be restarted.





 Billing 

IBM calculates your bill based on the IBM Cloud Account. Watson Assistant calculates monthly average user (MAU) metrics by aggregating within a given service instance as follows:



* The same MAU used in 2 different assistant resources in the same service instance counts as 1 MAU
* The same MAU used in 2 different assistant resources in different service instances counts as 2 MAUs



Note that for an active/active topology, under the worst case scenario, the MAU count could end up being doubled for a given billing period.







 Phone integration 

A Watson Assistant phone integration in one region is unaware of a phone integration in a different region. You need to ensure that your assistants are identically configured in both regions. You also need to rely on the upstream SIP trunking provider to detect and manage failing over between regions.



 Monitoring 

SIP trunking providers can be configured to actively health-check the Watson Assistant session border controllers (SBCs) by sending periodic SIP OPTIONS messages to each zone within a region.
The Test feature in the step editor uses a browser-based regex engine to find matches in your test input. At run time, the assistant uses a different regex engine that might have different results, especially with complex patterns. Before deploying your assistant in production, always use the assistant preview to test any step that uses a regex response.
6. Click Apply when you're finished editing.
7. By default, customers can't change topics when an utterance matches the pattern in a regex response. If you want a customer to be able to digress and change topics while entering a regex answer, click the Settings icon, then enable the toggle Allow customer to change topics during a regex response. For more information, see [Allowing your customers to change the topic of the conversation](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-change-topic).



You can save your configured regex response for reuse in other steps. For more information, see [Saving and reusing customer responses](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-collect-infosaved-customer-responses).



 Example regex patterns 

You can use the following regex patterns to recognize some common types of user input.



Example regex patterns

 Description Patterns 

 US passport number /^[A-PR-WY]ds?d{4}[1-9]$/ 
 US bank routing number b((0[0-9]) (1[0-2])(2[1-9])(3[0-2])(6[1-9])(7[0-2])80) ([0-9]{7})b 
 UPS tracking number /b(1Z ?[0-9A-Z]{3} ?[0-9A-Z]{3} ?[0-9A-Z]{2} ?[0-9A-Z]{4} ? [0-9A-Z]{3} ?
Previously, when you integrated your assistant with Slack, the assistant interacted with users through a direct message channel. Now, you can configure the assistant to listen for mentions, and respond when it is mentioned in other channels. You can choose to use one or both event types as the mechanism through which your assistant interacts with users.





 11 February 2019 

Integrate with Intercom
: Intercom, a leading customer service messaging platform, has partnered with IBM to add a new agent to the team, a virtual Watson Assistant. You can integrate your assistant with an Intercom application to enable the app to seamlessly pass user conversations between your assistant and human support agents. This integration is available to Plus and Premium plan users only. See [Integrating with Intercom](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-intercom) for more details.





 8 February 2019 

Version your skills
: You can now capture a snapshot of the the intents, entities, dialog, and configuration settings for a skill at key points during the development process. With versions, it's safe to get creative. You can deploy new design approaches in a test environment to validate them before you apply any updates to a production deployment of your assistant. See [Creating skill versions](https://cloud.ibm.com/docs/assistant?topic=assistant-versions) for more details.

Arabic content catalog
: Users of Arabic-language skills can now add prebuilt intents to their dialogs. See [Using content catalogs](https://cloud.ibm.com/docs/assistant?topic=assistant-catalog) for more information.





 17 January 2019 

Czech language support is generally available
: Support for the Czech language is no longer classified as beta; it is now generally available. See [Supported languages](https://cloud.ibm.com/docs/assistant?topic=assistant-language-support) for more information.

Language support improvements
: The language understanding components were updated to improve the following features:



* German and Korean system entities
* Intent classification tokenization for Arabic, Dutch, French, Italian, Japanese, Portuguese, and Spanish







 4 January 2019
For more information about creating assistants, see [Creating an assistant](https://cloud.ibm.com/docs/assistant?topic=assistant-assistant-add).
3. After your new assistant is created, click the ![Menu](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/kebab.png) menu and then select Settings.
4. On the Assistant Settings page, find the assistant ID. Your application will use this ID (instead of a workspace ID) to communicate with the assistant. The service credentials are the same for both the v1 and v2 APIs.

Currently, there is no API support for retrieving an assistant ID. To find the assistant ID, you must use the Watson Assistant user interface.







 Call the v2 runtime API 

After you have created an assistant, you can update your client application to use the v2 runtime API instead of the v1 runtime API.



1. Before sending the first message in a conversation, use the v2 [Create a session](https://cloud.ibm.com/apidocs/assistant/assistant-v2createsession) method to create a session. Save the returned session ID:



service .createSession({ assistant_id: assistantId, }) .then(res => { sessionId = res.session_id; })

 {: codeblock python }
session_id = service.create_session(
assistant_id = assistant_id
).get_result()['session_id']

 {: codeblock java}

CreateSessionOptions createSessionOptions = new CreateSessionOptions.Builder(assistantId).build(); SessionResponse session = service.createSession(createSessionOptions).execute().getResult(); String sessionId = session.getSessionId();

1.
[Learn more](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-preview-share). 
 Recognition Measurement of how many requests are being recognized by the assistant and routed into starting an action. [Learn more](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-analytics-overviewrecognition). 
 Response To create your assistant's response in an action step, you use the Assistant says section. This represents the text or speech the assistant delivers to a user at a particular step. Depending on the step, you can add a complete answer to a user's question or ask a follow-up question. [Learn more](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-respond). 
 Step A step that you add to an action represents a single interaction or exchange of information with a customer, a turn in the conversation. [Learn more](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-build-actions-overviewsteps). 
 Subaction An action that is called from another action is referred to as a subaction. [Learn more](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-step-what-nextgo-to-another-action). 
 Training To set up a Watson instance with components that enable the system to function in a particular domain (for example: corpus content, training data that generates machine learning models, programmatic algorithms, annotators, or other ground truth components) and then making improvements and updates to these components based on accuracy analysis. 
 Variable A variable is data that a customer shares with the assistant, which is collected and saved so it can be referenced later. In actions, you can collect action and session variables. [Learn more](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-manage-infoaction-variables-and-session-variables). 
 Web chat A channel that you can use to embed your assistant in your company website.
This documentation is for the classic Watson Assistant experience. To see the documentation for the new Watson Assistant, please go [here](https://cloud.ibm.com/docs/watson-assistant).



 Integrating with phone and Genesys Cloud 

You can use the phone integration to help your customers over the phone and transfer them to live agents inside of Genesys Cloud. If, in the course of a conversation with your assistant, a customer asks to speak to a person, you can transfer the conversation directly to a Genesys Cloud agent.



 Before you begin 

To use this integration pattern, make sure you have the following:



* Watson Assistant Plus or Enterprise Plan (required for phone integration)
* A working assistant you are ready to deploy
* A Genesys Cloud account







 Integrating with Genesys Cloud 

To integrate your assistant with Genesys Cloud, follow these steps:



1. Log into the [Genesys Cloud console](https://apps.mypurecloud.com).
2. Click Admin.
3. On the Telephony tab, click Trunks.
4. In the External Trunks section, click Create new. Specify the following information:



* In the External Trunk Name field, type a descriptive name (for example, Watson).
* In the Type field, select BYOC Carrier and then Generic BYOC Carrier.
* In the Inbound SIP Termination Identifier field, specify any name you want to use (for example, Watson). This value will not be used for now, but it is required by Genesys Cloud.
* In the Protocol field, select TLS.



![Genesys create trunk](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/phone-genesys-create-trunk.png)
5. Under Outbound, scroll to the SIP Servers or Proxies section. Specify the following information:
: The Confirmation and Free text response types are now set to Always ask for this information by default. For more information, see [Skipping steps, always asking steps, or never asking steps](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-collect-infocollect-info-skip-step).





 13 February 2023 

Response variations
: In actions, you can add response variations so that your assistant can respond to the same request in different ways. You can choose to rotate through the response variations sequentially or in random order. For more information, see [Adding variations](https://cloud.ibm.com/docs/watson-assistant/watson-assistant?topic=watson-assistant-respondrespond-variations).

Microsoft Teams integration
: A [Microsoft Teams integration](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-deploy-microsoft-teams) is now available to connect your assistant with the people, content, and tools that your business or community needs to chat, call, and collaborate.





 3 February 2023 

Action conditions (beta)
: An action condition is a boolean test, based on some runtime value; the action executes only if the test evaluates as true. This test can be applied to any variable. By defining action conditions, you can do things such as control user access to actions or create date-specific actions. This is a beta feature that is available for evaluation and testing purposes. For more information, see [Adding conditions to an action](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-action-conditions).





 2 February 2023 

Detect trigger words (beta)
: Use the Trigger word detected action to add words or phrases to two separate groups. The first group connects customers with an agent, when it’s important for a customer to speak with a live agent rather than activate any further actions. The second group shows customers a customizable warning message, used to discourage customers from interacting with your assistant in unacceptable ways, such as using profanity. This action is included with all new assistants created as of this date.