vania-janet/multiturn-rag-retrieval-data huggingface dataset:
The dialog keys off the common customer goals that you teach it to recognize, and provides useful responses. [Learn more](https://cloud.ibm.com/docs/assistant?topic=assistant-skill-addskill-add-dialog-skill)



If you can't decide which type of conversational skill to create, see [Choosing a conversational skill](https://cloud.ibm.com/docs/assistant?topic=assistant-skills-choose).
* Search skill![Plus or higher plans only](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/plus.png): Leverages information from existing corporate knowledge bases or other collections of content authored by subject matter experts to address unanticipated or more nuanced customer inquiries. For a given user query, uses the IBM Watson® Discovery service to search a data source of your self-service content and return an answer. [Learn more](https://cloud.ibm.com/docs/assistant?topic=assistant-skill-addskill-add-search-skill)

Only users paid plans can create this type of skill.





 Actions skill 

An actions skill contains actions that represent the tasks you want your assistant to help your customers with.

Each action contains a series of steps that represent individual exchanges with a customer. Building the conversation that your assistant has with your customers is fundamentally about deciding which steps, or which user interactions, are required to complete an action. After you identify the list of steps, you can then focus on writing engaging content to turn each interaction into a positive experience for your customer.

![Diagram of a simple exchange between a customer and an actions skill step.](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/action-skill-explained.png)





 Dialog skill
* conversation_id (v1 API only): A property defined in the v1 API that is stored in the context object of a /message API call. This property can be used to identify multiple /message API calls that are associated with a single conversational exchange with one user. However, the same ID is only used if you explicitly retain the ID and pass it back with each request that is made as part of the same conversation. Otherwise, a new ID is generated for each new /message API call.



For example, if the same person chats with your assistant on three separate occasions over the same billing period, how you represent that user in the API call impacts how the interactions are billed. If you identify the user interaction with a user_id, it counts as one use. If you identify the user interaction with a session_id, then it counts as three uses (because there is a separate session that is created for each interaction).

Design any custom applications to capture a unique user_id or session_id and pass the information to Watson Assistant. Choose a non-human-identifiable ID that doesn't change throughout the customer lifecycle. For example, don't use a person's email address as the user ID. In fact, the user_id syntax must meet the requirements for header fields as defined in [RFC 7230](https://tools.ietf.org/html/rfc7230section-3.2).

The built-in integrations derive the user ID in the following ways:



* For Facebook integrations, the user_id property is set to the sender ID that Facebook provides in its payload.
* For Slack integrations, the user_id property is a concatenation of the team ID, such as T09LVDR7Y, and the member ID of the user, such has W4F8K9JNF. For example: T09LVDR7YW4F8K9JNF.
* For web chat, you can set the value of the user_id property.



Billing is managed per monthly active user per service instance. If a single user interacts with assistants that are hosted by different service instances that belong to the same plan, each interaction is treated as a separate use.
For more information about the user_id property, see the API reference documentation:



* [v2 stateless /message](https://cloud.ibm.com/apidocs/assistant-v2/assistant-v2messagestateless)
* [v2 stateful /message](https://cloud.ibm.com/apidocs/assistant-v2/assistant-v2message)







 If the user ID is not specified 

If you are using a custom client application and do not set a user_id value, the service automatically sets it to one of the following values:



* session_id (v2 API only): A property defined in the v2 API that identifies a single conversation between a user and the assistant. A session ID is provided in /message API calls that are generated by the built-in integrations. The session ends when a user closes the chat window or after the inactivity time limit is reached.

If you use the stateless v2 message API, you must specify the session_id with each message in an ongoing conversation (in context.global.session_id).
* conversation_id (v1 API only): A property defined in the v1 API that is stored in the context object of a /message API call. This property can be used to identify multiple /message API calls that are associated with a single conversational exchange with one user. However, the same ID is only used if you explicitly retain the ID and pass it back with each request that is made as part of the same conversation. Otherwise, a new ID is generated for each new /message API call.



For example, if the same person chats with your assistant on three separate occasions over the same billing period, how you represent that user in the API call impacts how the interactions are billed. If you identify the user interaction with a user_id, it counts as one use. If you identify the user interaction with a session_id, then it counts as three uses (because there is a separate session that is created for each interaction).

Design any custom applications to capture a unique user_id or session_id and pass the information to Watson Assistant. Choose a non-human-identifiable ID that doesn't change throughout the customer lifecycle.
The Intercom user_id property is the id of the author message object in the Conversation Model that is defined by Intercom.



* To get the ID, open the channel from a web browser. Open the web developer tools to view the console. Look for author.



The full customer ID looks like this: customer_id=intercom_5c499e5535ddf5c7fa2d72b3.
* For Slack, the customer_id is the user_id prepended with slack_. The Slack user_id property is a concatenation of the team ID, such as T09LVDR7Y, and the member ID of the user, such has W4F8K9JNF. For example: T09LVDR7YW4F8K9JNF.



* To get the team ID, open the channel from a web browser. Open the web developer tools to view the console. Look for [BOOT] Initial team ID.
* You can copy the member ID from the user's Slack profile.
* To get the IDs programmatically, use the Slack API. For more information, see [Overview](https://api.slack.com/apis). The full customer ID looks like this: customer_id=slack_T09LVDR7YW4F8K9JNF.



* For the web chat integration, the service takes the user_id that is passed in and adds it as the customer_id parameter value to the X-Watson-Metadata header with each request.





 Before you begin 

To be able to delete message data associated with a specific user, you must first associate all messages with a unique customer ID for each user. To specify the customer ID for any messages sent using the /message API, include the X-Watson-Metadata: customer_id property in your header. For example:

curl -X POST -u "apikey:3Df... ...Y7Pc9"
--header
'Content-Type: application/json'
'X-Watson-Metadata: customer_id=abc'
--data
The built-in integrations typically set this property for you. If you're using a custom application and don't specify a user_id, the user_id is set to the session_id (v2) or conversation_id(v1) value.

Digression bug fix
: Fixed a bug where digression setting changes that were made to a node with slots were not being saved.





 5 February 2021 

Documentation update
: The phone and SMS with Twilio deployment documentation was updated to include instructions for migrating from Voice Agent with Watson. For more information, see [Integrating with phone](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-phonedeploy-phone-migrate-from-va) and [Integrating with SMS with Twilio](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-smsdeploy-sms-migrate-from-va).





 27 January 2021 

German language improvements
: A word decomposition function was added to the intent and entity recognition models for German-language dialog skills.

A characteristic of the German language is that some words are formed by concatenating separate words to form a single compound word. For example, "festnetznummer" (landline number) concatenates the words "festnetz" (landline) and "nummer" (number). When your customers chat with your assistant, they might write a compound word as a single word, as hyphenated words, or as separate words. Previously, the variants resulted in different intent confidence scores and different entity mention counts based on your training data. With the addition of the word decomposition function, the models now treat all compound word variants as equivalent. This update means you no longer need to add examples of every variant of the compound words to your training data.





 19 January 2021 

The Phone and SMS with Twilio integrations are now generally available!
: For more information, see:



* [Integrating with phone](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-phone)
Important: The User ID property is not equivalent to the Customer ID property, though both can be passed with the message. The User ID field is used to track levels of usage for billing purposes, whereas the Customer ID field is used to support the labeling and subsequent deletion of messages that are associated with end users. Customer ID is used consistently across all Watson services and is specified in the X-Watson-Metadata header. User ID is used exclusively by the Watson Assistant service and is passed in the context object of each /message API call.





 Enabling user metrics 

User metrics allow you to see, for example, the number of unique users who have engaged with your assistant, or the average number of conversations per user over a given time interval on the [Overview page](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-logs-overview). User metrics are enabled by using a unique User ID parameter.

To specify the User ID for a message sent using the /message API, include the user_id property in your global [context](https://cloud.ibm.com/apidocs/assistant-data-v2message), as in this example:

"context": {
"global": {
"system": {
"user_id": "{UserID}"
}
}
}

If your application is still using the older [v1 runtime API](https://cloud.ibm.com/apidocs/assistant-data-v1?curl=message), the context format is different:

"context" : {
"metadata" : {
"user_id": "{UserID}"
}
}





 Associating message data with a user for deletion 

There might come a time when you want to completely remove a set of your user's data from a Watson Assistant instance. When the delete feature is used, then the Overview metrics will no longer reflect those deleted messages; for example, they will have fewer Total Conversations.



 Before you begin 

To delete messages for one or more individuals, you first need to associate a message with a unique Customer ID for each individual.
One of the following values:<br><br><br><br> * Web chat<br> * Phone<br> * SMS<br> * Whatsapp<br> * Slack<br> * Facebook Messenger<br><br><br> 
 channel.private.user.id String The ID of the user who is interacting with the assistant through the channel. This ID is specific to the channel and might be different from the user ID Watson Assistant uses for billing purposes. For more information, see [Channel user IDs](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-expression-integration-variablesexpression-integration-variables-channel-userid). 
 channel.private.user.phone_number String The phone number associated with the user. Set by the phone, SMS, and WhatsApp integrations. 
 channel.private.user.name String The name of the user who is interacting with the assistant through the channel. Set by the Microsoft Teams integration. 







 Example JSON 

"channel": {
{
"name": "Web chat",
"private": {
"user": {
"id": "anonymous_IBMuid-727c0302-6fd7-4abb-b7ee-f06b4bf30e99"
}
}
}
}





 Channel user ID 

The channel.private.user.id property, which is set by the channel integration, specifies a user ID for the customer that is specific to the channel. The source of this user ID depends on the channel:



Sources of the channel user ID

 Channel Channel user ID 

 Web chat The user ID set by the web chat instance. For more information, see [Managing user identity information](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-web-chat-develop-userid). 
 Slack The Slack member ID (for example, U2147483697). 
 Facebook The Facebook sender ID (for example, 4310101122439797). 
 Whatsapp The customer's phone number.
The prompt ID is used to identify the prompt in requests to the service, including in the SSML of speech synthesis requests.
* status is the current status of the prompt:



* processing indicates that the service received the request to add the prompt and is processing the prompt. This is the initial status of all prompts.
* available indicates that the service successfully validated the prompt. The prompt is now ready for use in a speech synthesis request.
* failed indicates that the service's validation of the prompt failed. The status of the prompt includes an error field that describes the reason for the failure.



* speaker_id is the GUID of the speaker model that is associated with the prompt. The service omits the field if no speaker ID is associated with the prompt.



When listing all prompts for a custom model, the prompts array is empty if the model contains no prompts.



 List all custom prompts example 

The following example lists all custom prompts that are included in the custom model that has the specified customization ID:

IBM Cloud

curl -X GET -u "apikey:{apikey}" "{url}/v1/customizations/{customization_id}/prompts"

IBM Cloud Pak for Data

curl -X GET --header "Authorization: Bearer {token}" "{url}/v1/customizations/{customization_id}/prompts"

The model contains three custom prompts. The first two prompts are associated with the same speaker; the first is available and ready to use, and the service is still processing the second. The third prompt, which is available, is associated with a different speaker.

{
"prompts": [!
{
"prompt": "Hello and welcome",
"prompt_id": "greeting",
"status": "available",
"speaker_id": "56367f89-546d-4b37-891e-4eb0c13cc833"
},
{
"prompt": "How can I help you today?",
"prompt_id": "help",
Prompt IDs must be unique within a given custom model, so you cannot define two prompts with the same ID for the same model. If you provide the ID of an existing prompt, the previously uploaded prompt is replaced by the new information. The service reprocesses the existing prompt by using the new text and audio, and it updates the prosodic data that is associated with the prompt.

When it processes a request to add a prompt, the service attempts to align the text and the audio that are provided for the prompt. The text that is passed with a prompt must match the spoken audio as closely as possible. Optimally, the text and audio match exactly. The service does its best to align the specified text with the audio, and it can often compensate for mismatches between the two. But if the service cannot effectively align the text and the audio because the magnitude of differences between the two is too great, processing of the prompt fails.

Prompts are supported for use only with US English custom models and voices. The quality of a prompt is undefined if the language of a prompt does not match the language of its custom model. This is consistent with any text that is specified for a speech synthesis request. The service makes a best-effort attempt to render the specified text for the prompt. It does not validate that the language of the text matches the language of the model.





 Speaker models 

A speaker model is defined by an audio sample of a user's voice from which the service extracts information to train itself on that voice's characteristics. When the speaker model is associated with a custom prompt that is spoken by the same user, the service leverages its understanding of the speaker's voice to identify how the prosody of the prompt compares to the speaker's normal speech patterns. The speaker model serves as a baseline to distinguish prosodic features in the audio of the prompt.

When you create a speaker model, you provide enrollment audio and a name for the model that is unique within the context of the owning service instance:



* The enrollment audio must include speech that is spoken by the user who is associated with the model. The service extracts information about the speaker's voice from the audio sample that you provide.
* The name provides a human-readable handle for the model.
With the stateless message API, the context is always included with each message response. For more information, see the [v2 API Reference](https://cloud.ibm.com/apidocs/assistant/assistant-v2messagestateless).



Important: One use of the context is to specify a unique user ID for each end user who interacts with the assistant. For user-based plans, this ID is used for billing purposes. (For more information, see [User-based plans](https://cloud.ibm.com/docs/assistant?topic=assistant-admin-managing-planadmin-managing-plan-user-based).)

There are two types of context:



* Global context: context variables that are shared by all skills used by an assistant, including internal system variables used to manage conversation flow. The global context includes the user ID, as well as other global values such as the time zone and language of the assistant.
* Skill-specific context: context variables specific to a particular skill, including any user-defined variables needed by your application. Currently, only one skill (named main skill) is supported.



User-defined context variables that you specify in a dialog node are part of the user_defined object within the skill context when accessed using the API. Note that this structure differs from the context structure that appears in the JSON editor in the Watson Assistant user interface. For example, you might specify the following in the JSON editor:

"context": {
"my_context_var": "this is the value"
}

In the v2 API, you would access this user-defined variable as follows:

"context": {
"skills": {
"main skill": {
"user_defined": {
"my_context_var": "this is the value"
}
}
}
}

For detailed information about how to access context variables using the API, see the [v2 API Reference](https://cloud.ibm.com/apidocs/assistant/assistant-v2).



 Example
For user-based plans, this ID is used for billing purposes. For more information, see [User-based plans explained](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-admin-managing-planadmin-managing-plan-user-based).

There are two types of context:



* Global context: context variables that are shared by all skills that are used by an assistant, including internal system variables that are used to manage conversation flow. The global context includes the user ID and other global values such as the time zone and language of the assistant.
* Skill-specific context: context variables specific to a particular skill, including any user-defined variables needed by your application. Currently, only one skill (named main skill) is supported.



User-defined context variables that you specify in a dialog node are part of the user_defined object within the skill context when accessed by using the API. This structure differs from the context structure that appears in the JSON editor in the Watson Assistant user interface. For example, you might specify the following code in the JSON editor:

"context": {
"my_context_var": "this is the value"
}

In the v2 API, you would access this user-defined variable as follows:

"context": {
"skills": {
"main skill": {
"user_defined": {
"my_context_var": "this is the value"
}
}
}
}

For more information about how to access context variables by using the API, see the [v2 API Reference](https://cloud.ibm.com/apidocs/assistant/assistant-v2).



 Example 

The following example shows a stateful /message request that includes both global and skill-specific context variables; it also uses the options.return_context property to request that the context is returned with the response. This option is applicable only if you are using the stateful message method because the stateless message method always returns the context.



* Java
* Python
* Node



MessageInputOptions inputOptions = new MessageInputOptions.Builder()
* 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. A skill is effectively a wrapper for a V1 workspace.



Important: The User ID property is not equivalent to the Customer ID property, though both can be passed with the message. The User ID field is used to track levels of usage for billing purposes, whereas the Customer ID field is used to support the labeling and subsequent deletion of messages that are associated with end users. Customer ID is used consistently across all Watson services and is specified in the X-Watson-Metadata header. User ID is used exclusively by the Watson Assistant service and is passed in the context object of each /message API call.





 Associating message data with a user for deletion 

There might come a time when you want to completely remove a set of your user's data from a Watson Assistant instance. When the delete feature is used, then the Overview metrics will no longer reflect those deleted messages; for example, they will have fewer Total Conversations.



 Before you begin 

To delete messages for one or more individuals, you first need to associate a message with a unique Customer ID for each individual. To specify the Customer ID for any message sent using the /message API, include the X-Watson-Metadata: customer_id property in your header. You can pass multiple Customer ID entries with semicolon separated field=value pairs, using customer_id, as in the following example:

curl -X POST -u "apikey:3Df...