vania-janet/multiturn-rag-retrieval-data huggingface dataset:
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 ![Plus or higher plans only](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/plus.png) 

By adding the phone integration to your assistant, you can make your assistant available to customers over the phone.

When you add the phone integration to your assistant, you can automatically generate a working phone number that is automatically connected to your assistant. Or, if you prefer, you can connect the assistant to your existing infrastructure by configuring an existing Session Initiation Protocol (SIP) trunk.

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). If you choose to generate a free phone number for your assistant, a SIP trunk is automatically provisioned from IntelePeer. You can also choose to use an existing SIP trunk from a provider such as IntelePeer, Genesys, or Twilio.

Generating a free phone number is available only with new phone integrations. If you have an existing phone integration and you want to switch to a free phone number, you must delete the existing integration and create a new one.

When your customer makes a phone call using the telephone number connected to your assistant, the phone integration answers. The integration converts output from your assistant into voice audio by using the IBM Watson® Text to Speech service. 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.

This feature is available only to Plus or Enterprise plan users.
For more information about saved responses, see [Saving and reusing customer responses](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-collect-infosaved-customer-responses).

In addition to the listed types, a variable can also be created as an array. To create an array variable, select Any as the type, and in the next step, define an initial value that uses the expression [] to represent an empty array.
5. Optional: Add an initial value to set the starting value for the variable at the beginning of each user session. For example, your customers can use an assistant to make purchases. You might initialize a Payment due variable with a starting value of 0, and then add to that value as the customer orders items.

To specify a complex object or an array as the initial value, or to calculate the initial value based on other variables, you can write an expression. For more information about writing expressions, see [Writing expressions](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-expressions).
6. Optional: Add a description.
7. Click Apply.







 Built-in variables 

In addition to the variables you create, Watson Assistant provides a set of built-in variables you can access from any action. At run time, these variables are automatically set with the appropriate values. For example, the Current time session variable always provides the current time in the user's time zone, at the time of the interaction with the customer.

To see these variables, click Variables on the Actions page.



* The Set by assistant page shows built-in session variables that are automatically provided for each assistant.
* The Set by integration page shows variables that are automatically provided by the integration your customer is using to connect to the assistant. (These variables are not set if no integration is connected.)



Set by assistant:



Variables set by assistant

 Variable name Variable ID Description Examples 

 Digressed from digressed_from Last action before the customer digressed (or null if not digressed) Pay bill 
 Now now The current date and time in the user's time zone. 2021-08-11T11:28:02
Deploy your assistant on the phone in minutes
: We have partnered with [IntelePeer](https://intelepeer.com/) to enable you to generate a phone number for free within the phone integration. Simply choose to generate a free number when following the prompts to create a phone integration, finish the setup, and a number is assigned to your assistant. These numbers are robust and ready for production.

Connect to your existing service desks
: We have added step-by-step documentation for connecting to [Genesys](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-phone-genesys) and [Twilio Flex](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-phone-flex) over the phone. Easily hand off to your live agents when your customers require telephony support from your service team. Watson Assistant deploys on the phone via SIP, so most phone based service desks can easily be integrated via SIP trunking standards.





 23 August 2021 

Intent detection updates
: Intent detection for the English language has been updated with the addition of new word-piece algorithms. These algorithms improve tolerance for out-of-vocabulary words and misspelling. This change affects only English-language assistants, and only if the enhanced intent recognition model is enabled.

Automatic retraining of old skills and workspaces
: As of August 23, 2021, Watson Assistant enabled automatic retraining of existing skills in order to take advantage of updated algorithms. The Watson Assistant service will continually monitor all ML models, and will automatically retrain those models that have not been retrained within the previous 6 months. For more information, see [Automatic retraining of old skills and workspaces](https://cloud.ibm.com/docs/assistant?topic=assistant-skill-auto-retrain).





 19 August 2021 

Actions preview now includes debug mode and variable values
: When previewing your actions, you can use debug mode and variable values to ensure your assistant is working the way you expect.

Debug mode allows you to go to the corresponding step by clicking on a step locator next to each message.
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) that can queue callers until an appropriate agent is available. If not, choose a call center service 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 call center SIP URI for the call center service 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](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-phone-actionsphone-actions-transfer).





 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](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-respondrespond-formatting).
* 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.
* logs



For more information, see the [API Reference](https://cloud.ibm.com/apidocs/assistant/assistant-v1).
* The behavior of the /messages POST method has changed the handling of entities and intents specified as part of the message input:



* If you specify intents on input, your assistant uses the intents you specify, but uses natural language processing to detect entities in the user input.
* If you specify entities on input, your assistant uses the entities you specify, but uses natural language processing to detect intents in the user input.



The behavior has not changed for messages that specify both intents and entities, or for messages that specify neither.
* The option to mark user input as irrelevant is now available for all supported languages. This is a beta feature.
* A new Credentials tab provides a single place where you can find all of the information you need for connecting your application to a workspace (such as the Watson Assistant credentials and workspace ID), as well as other deployment options. To access the Credentials tab for your workspace, click the icon and select Credentials.







 9 March 2017 

REST API updates
: The Watson Assistant REST API now supports access to the following resources:



* workspaces
* intents
* examples
* counterexamples



For more information, see the [API Reference](https://cloud.ibm.com/apidocs/assistant/assistant-v1).





 7 March 2017 

Intent name restrictions
: The use of . or .. as an intent name causes problems and is no longer supported. You cannot rename or delete an intent with this name; to change the name, export your intents to a file, rename the intent in the file, and import the updated file into your workspace. Paying customers can contact support for a database change.





 1 March 2017 

System entities are now enabled in German
: System entities are now enabled in German.





 22 February 2017 

Messages are now limited to 2,048 characters
: Messages are now limited to 2,048 characters.





 3 February 2017 

Updates
: This release includes the following updates:
Understanding your users' questions or requests 

Actions represent the tasks or questions that your assistant can help customers with. Each action has a beginning and an end, making up a conversation between the assistant and a customer. Learn how to begin an action, where it understands and recognizes a goal based on the words a customer uses to ask a question or make a request.



 Beginning an action 

Each assistant can include as many actions as you need to have conversations with your users. You design each individual action to recognize a specific question or request, and when it does, the action starts.

When you create a new action, your first task is to enter one phrase that a customer types or says to start the conversation about a specific topic. This phrase determines the problem that your customer has or the question your user asks.

To get going, you need to enter only one phrase, for example: What are your store hours?.

After you enter the phrase, it is stored in Customer starts with, at the start of the action.

Zoom

![Customer starts with](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/customer-starts-with.png)

Customer starts with





 Testing your phrase 

Before even doing anything else with your action, you can already start checking that your assistant recognizes the starting phrase.



1. Click the Preview button.
2. Enter your first phrase, for example: What are your store hours?.
3. If you see There are no additional steps for this action that means the action recognizes the phrase. (And it's because you didn't add anything else to your action.)

Zoom

![Preview](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/new-action-preview.png)

Preview
4.
Calling actions from a dialog 

In the new Watson Assistant, you can use actions with your primary dialog conversation. A dialog feature takes precedence over actions. You can use actions to supplement a dialog-based conversation, but the dialog drives the conversation with users to match their requests.

A dialog node calls an action to perform a task and then return to the dialog. From a single dialog node, you can make a call to either a webhook or an action, not both. Choose the approach that best suits your needs:



* Call an action if you want to perform a discrete and self-contained task, and then return to the dialog to be ready to address any new user requests. Data collected from the user during action processing must be stored as a session variable for it to be passed to the dialog.
* Call a webhook if you want to send a request to a web service to complete a task and return a response that can be used later by this dialog. For more information, see [Extending your assistant with webhooks](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-webhook-overview).





 When to call an action from a dialog 

You might want to call an action from a dialog in the following scenarios:



* You want to perform an action from multiple dialog threads.

For example, you want to ask customers how satisfied they are with your service. You can define a single action to check customer satisfaction and call it from multiple branch-ending dialog nodes.

In this scenario, you don't need to define an intent, such as check_satisfaction. The action is called automatically, replacing a jump to another dialog node's response.
* You want to see how actions works.

In this scenario, you can pick an intent for the action to handle. If you plan for the action to be called from the dialog only, you can spend your time defining the user examples for the intent that triggers the dialog node. When you define the action, you can add one customer example only, reducing the time you need to spend building the action.







 Adding a call to an action
If you are looking for other ways to analyze your user conversation logs in more detail, consider using Jupyter notebooks. See [Advanced tasks](https://cloud.ibm.com/docs/assistant?topic=assistant-logs-resources) for more details.





 9 November 2018 

Major user interface revision
: The Watson Assistant service has a new look and added features.

This version of the tool was evaluated by beta program participants over the past several months.



* Skills: What you think of as a workspace is now called a skill. A dialog skill is a container for the natural language processing training data and artifacts that enable your assistant to understand user questions, and respond to them.



Where are my workspaces? Any workspaces that you created previously are now listed in your service instance as skills. Click the Skills tab to see them. For more information, see [Adding skills to your assistant](https://cloud.ibm.com/docs/assistant?topic=assistant-skill-add).



* Assistants: You can now publish your skill in just two steps. Add your skill to an assistant, and then set up one or more integrations with which to deploy your skill. The assistant adds a layer of function to your skill that enables Watson Assistant to orchestrate and manage the flow of information for you. See [Assistants](https://cloud.ibm.com/docs/assistant?topic=assistant-assistants).
* Built-in integrations: Instead of going to the Deploy tab to deploy your workspace, you add your dialog skill to an assistant, and add integrations to the assistant through which the skill is made available to your users. You do not need to build a custom front-end application and manage the conversation state from one call to the next. However, you can still do so if you want to. See [Adding integrations](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-integration-add) for more information.
* New major API version: A V2 version of the API is available. This version provides access to methods you can use to interact with an assistant at run time.
: We have added step-by-step documentation for connecting to [Genesys](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-phone-genesys) and [Twilio Flex](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-phone-flex) over the phone. Easily hand off to your live agents when your customers require telephony support from your service team. Watson Assistant deploys on the phone via SIP, so most phone based service desks can easily be integrated via SIP trunking standards.





 23 August 2021 

Intent detection updates
: Intent detection for the English language has been updated with the addition of new word-piece algorithms. These algorithms improve tolerance for out-of-vocabulary words and misspelling. This change affects only English-language assistants, and only if the enhanced intent recognition model is enabled. (For more information about the enhanced intent recognition model, and how to determine whether it is enabled, see [Improved intent recognition](https://cloud.ibm.com/docs/assistant?topic=assistant-intent-detection).)

Automatic retraining of old skills and workspaces
: As of August 23, 2021, Watson Assistant enabled automatic retraining of existing skills in order to take advantage of updated algorithms. The Watson Assistant service will continually monitor all ML models, and will automatically retrain those models that have not been retrained within the previous 6 months. For more information, see [Automatic retraining of old skills and workspaces](https://cloud.ibm.com/docs/assistant?topic=assistant-skill-auto-retrain).





 19 August 2021 

Actions preview now includes debug mode and variable values
: When previewing your actions, you can use debug mode and variable values to ensure your assistant is working the way you expect.

Debug mode allows you to go to the corresponding step by clicking on a step locator next to each message. It shows you the confidence score of top three possible action when the input triggers an action. You can also follow the step in the action editor along with the conversation flow.
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 Intercom 

Intercom is a customer messaging platform that helps drive business growth through better relationships throughout the customer lifecycle.

Intercom has partnered with IBM to add a new agent to the customer support 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 agents. Read the [Watson blog post](https://medium.com/ibm-watson/contact-center-post-394dff427c8) to learn more about the integration.

If you integrate the assistant with Intercom, the Intercom application becomes the client-facing application for your skill. All interactions with users are initiated through and managed by Intercom.



 One-time agent creation 

You or someone in your organziation must complete these one-time prerequisite steps before you add the Intercom integration to your assistant.



1. Create a functional email account for your assistant.

Each assistant must have a valid, unique email address before it can be added to a team in Intercom.
2. From your Intercom workspace, add the assistant to your team as a new agent.

Go to the teammate settings page in your Intercom workspace, invite the assistant as a new agent by adding the email you created in the previous step to the invite field.

If you don't have an Intercom workspace set up yet, create one at [www.intercom.com](https://www.intercom.com). At a minimum, you need a subscription to the Inbox product from Intercom to be able to create a workspace.
3. From the assistant email account you created earlier, find the invitation from Intercom. Click the link in the email to join the team. Sign up using the assistant's functional email address, and then join the team.
4. Optional: Update the profile for your assistant.

You can edit the name and profile picture for your assistant.
Provide live support to your customers with the pre-built integration of Watson Assistant, Speech to Text, and IBM Watson® Text to Speech.
* Analyze customer calls - Uncover patterns and conduct root-cause analysis on transcriptions of phone calls between your customers and call center agents. Transcribe audio by using Speech to Text, and then analyze the transcription with IBM Watson® Natural Language Understanding.
* Support agents - Provide real-time information to improve agent efficiency and focus. Use Speech to Text to transcribe calls live, and then use IBM Watson® Discovery to automatically surface relevant information so that your agent can focus on the customer rather than on the search.







 Beta features 

IBM occasionally releases features and language support that are classified as beta. Such features are provided so that you can evaluate their functionality. They might be unstable and are subject to change or removal with short notice. They are not intended for use in a production environment.

Beta features might not provide the same level of performance or compatibility as generally available features. Generally available features are ready for use in a production environment.





 Pricing 

IBM Cloud

The service offers multiple pricing plans to suit your usage and application needs:



* For general information about the pricing plans and answers to common questions, see the [Pricing FAQs](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-faq-pricing).
* For more information about the pricing plans or to purchase a plan, see the Speech to Text service in the [IBM Cloud® Catalog](https://cloud.ibm.com/catalog/speech-to-text).
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.

This feature is available only to Plus or Enterprise plan users.

Depending on the architecture of your existing telephony infrastructure, there are multiple ways you might integrate it with Watson Assistant. For more information about common integration patterns, read the blog post [Hey Watson, can I have your number?](https://medium.com/ibm-watson/hey-watson-can-i-have-your-number-7de8fc7621ed) on Medium.



 Set up the integration 

You must have Manager role access to the instance and Viewer role access to the resource group to complete setup. For more information about access levels, see [Managing access](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-access-control).

To set up the integration:



1. In the Integrations section on the main page for your assistant under Essential Channels, you will see a tile for Phone.
2. On the Phone tile, click Add.
3. On the pop-up window, click Add again.
4. Choose whether to generate a free phone number for your assistant, integrate with your contact center, or connect to an existing SIP trunk:



* To generate a free phone number for your assistant, click Generate a free phone number.

Generating a free phone number is supported only for Watson Assistant instances in the Dallas and Washington DC data centers.
* To integrate with a [contact center](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-deploy-phone-nicecxone), click Integrate with your contact center.