vania-janet/multiturn-rag-retrieval-data huggingface dataset:
Use the instance.updateLocale() method.

For example, if you apply the Spanish locale (es), the web chat uses Spanish-language phrases that are listed in the es.json file, and uses the DD-MM-YYYY format for dates instead of MM-DD-YYYY.

The locale you specify for the web chat does not impact the syntax of dates and times that are returned by the underlying skill.
2. To change only the language of the hardcoded English phrases, use the instance.updateLanguagePack() method.

For more information, see [Instance methods](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-instance-methodslanguages).
3. To change the text direction of the page from right to left, use the direction method. For more information, see [Configuration](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-configurationconfigurationobject).





 Customizing phrases 

You can edit the hardcoded phrases that are displayed in the web chat to customize them for branding or style. Whether your web chat responds in English or another language, you can customize the wording that is used. For example, you might want to replace the phrase that says, The live agent is typing with the phrase, A customer support agent is typing.

The language files contain [ICU Message Format](http://userguide.icu-project.org/formatparse/messages) JSON representations of all of the languages that are supported by the web chat. You can edit all or a subset of the phrases in a JSON file, and then configure the web chat to use your version by specifying the instance.updateLanguagePack() method.

For more information, see [Languages](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-instance-methodslanguages).







 Versioning 

Web chat follows semantic versioning practices.
: From the Pre-message webhook and Post-message webhook configuration pages, you can configure the webhook timeout length from a minimum of 1 second to a maximum of 30 seconds. For more information, see [Webhook overview](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-webhook-overview).

Rich response types
: Your assistant can now send responses that include elements such as audio, video, or embedded iframe content. For more information, see [Rich responses](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-dialog-overviewdialog-overview-multimedia).

Analytics overview change
: To improve reliability, the Values column has been removed from Top entities on the Analytics Overview page. Top Entities continues to provide counts of entity types. For more information, see [Top intents and top entities](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-logs-overviewlogs-overview-tops).

Dialog skill Try it out improvements
: For dialog skills, the Try it out pane now uses the [React](https://reactjs.org/) UI framework similar to the rest of the Watson Assistant user interface. You shouldn't see any change in behavior or functionality. As a part of the update, dialog skill error handling has been improved within the Try it out pane.

Disambiguation feature updates
: The dialog skill disambiguation feature now includes improved features:



* Increased control: The frequency and depth of disambiguation can now be controlled by using the sensitivity parameter in the [workspace API](https://cloud.ibm.com/apidocs/assistant-data/assistant-data-v1updateworkspace). There are 5 levels of sensitivity:



* high
* medium_high
* medium
* medium_low
* low



The default (auto) is medium_high if this option is not set.
* More predictable: The new disambiguation feature is more stable and predictable.
For example, if the URL has the syntax: https://assistant-facebook-{location}.watsonplatform.net/public/message/, change it to have this syntax:

https://integrations.{location}.assistant.watson.appdomain.cloud/public/facebook/{integration-id}/message?version=2020-09-24

Check the Generated callback URL field in the Facebook Messenger integration setup page for the full URL to use, which includes the appropriate {location} and {integration-id} values for your instance.



* For a Phone integration, if you connect to existing speech service instances, make sure those speech services use credentials that were generated with the latest endpoint syntax (a URL that starts with https://api.{location}.speech-to-text.watson.cloud.ibm.com/).
* For a search skill, if you connect to an existing Discovery service instance, make sure the Discovery service uses credentials that were generated with the supported syntax (a URL that starts with https://api.{location}.discovery.watson.cloud.ibm.com/).
* If you are using [Jupyter notebooks](https://cloud.ibm.com/docs/assistant?topic=assistant-logs-resourceslogs-resources-jupyter-logs) to do advanced analytics, check your Jupyter notebook files to make sure they don't specify URLs with the old watsonplatform.net syntax. If so, update your files.
* No action is required for the following integration types:



* Intercom
* SMS with Twilio
* WhatsApp with Twilio
* Zendesk service desk connection from web chat









 23 March 2021 

Actions skill improvement
: Actions have a new toolbar making it easier to send feedback, access settings, save, and close.





 17 March 2021 

Channel transfer response type
: Dialog skills now include a channel transfer response type. If your assistant uses multiple integrations to support different channels for interaction with users, there might be some situations when a customer begins a conversation in one channel but then needs to transfer to a different channel.
Making a call after processing a message 

Make a call to an external service or application every time a response is rendered by the assistant.

A webhook is a mechanism that allows you to call out to an external program based on events in your program. You can add a postmessage webhook to your assistant if you want the webhook to be triggered before each message response is returned to the customer.

The postmessage webhook works with the v2 /message API only (stateless and stateful). For more information, see the [API reference](https://cloud.ibm.com/apidocs/assistant/assistant-v2message).

You can use a postmessage webhook to do things like extract custom responses from an external content repository. For example, you can define a conversational skill with custom IDs in the response instead of text. The postmessage webhook can pass the ID to an external database to retrieve a stored text response.

You can use this webhook in coordination with the premessage webhook. For example, if you used the premessage webhook to strip personally identifiable information from the customer's input, you can use the postmessage webhook to add it back. Or if you use the premessage webhook to translate the customer's input to the language of the skill, you can use the postmessage webhook to translate the response back into the customer's native language before it is returned. For more information, see [Making a call before processing a message](https://cloud.ibm.com/docs/assistant?topic=assistant-webhook-pre).

If you want to perform a one-time action when certain conditions are met during a conversation, use a dialog webhook instead. For more information about the dialog webhook, see [Making a programmatic call from dialog](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-webhooks).

For environments where private endpoints are in use, keep in mind that a webhook sends traffic over the internet.



 Defining the webhook
For more information, see [End the call](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-voice-actionsdialog-voice-actions-hangup).





 Example 

This example uses the end_session response type to end a conversation.

{
"output": {
"generic": [
{
"response_type": "end_session"
}
]
}
}







 user_defined 

A custom response type containing any JSON data the client or integration knows how to handle. For example, you might customize the web chat to display a special kind of card, or build a custom application to format responses using a table or chart.

The user-defined response type is not displayed unless you have implemented code specifically to handle it. For more information about customizing the web chat, see [Applying advanced customizations](https://cloud.ibm.com/docs/assistant?topic=assistant-web-chat-config). For more information about handling responses in a custom client app, see [Implementing responses](https://cloud.ibm.com/docs/assistant?topic=assistant-api-dialog-responses).



 Fields 



 Name Type Description Required? 

 response_type string user_defined Y 
 user_defined object An object containing any data the client or integration knows how to handle. This object can contain any valid JSON data, but it cannot exceed a total size of 5000 bytes. Y 







 Example 

This examples shows a generic example of a user-defined response. The user_defined object can contain any valid JSON data.

{
"output": {
"generic":[
{
"response_type": "user_defined",
"user_defined": {
"field_1": "String value",
"array_1":
1,
2
],
"object_1": {
"property_1": "Another string value"
}
}
}
]
}
}
Show more









 Native JSON format
}
}
}
}
}
Show more





 Restoring conversation state 

In some situations, you might want the ability to restore a conversation to a previous state.

You can use the export option on stateful message requests to specify that you want the context object in the response to include complete session state data. If you specify true for this option, the returned skill context includes an encoded state property that represents the current conversation state.

If you are using the stateful message API, the service stores conversation state data only for the life of the session. However, if you save this context data (including state) and send it back to the service with a subsequent message request, you can restore the conversation to the same state, even if the original session has expired or has been deleted.

If you are using the stateless message API, the state property is always included in responses (along with the rest of context). Although stateless sessions do not expire, you can still use this state data to reset a conversation to a previous state.
For more information about voice model options, see [Supported languages and voices](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-voiceslanguageVoices).

The model you specify must be one that is supported by the Text to Speech service instance that is configured for use with the integration.







 Transferring a call to a live agent 

When you configure the phone integration, you can optionally set up backup call center support, which makes it possible for the assistant to transfer a call to a human. You can use the Connect to agent response type in an action step to initiate a transfer to a live agent at a specific point in the conversation. When a Connect to agent response is sent to the phone integration, a SIP transfer is initiated using the SIP REFER message, as defined by [RFC 5589](https://datatracker.ietf.org/doc/html/rfc5589section-6.1).

For more information about initiating a transfer to a live agent during the conversation, see the following documentation:



* [Setting up live agent escalation](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-deploy-phone)
* [Defining responses using the JSON editor](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-assistant-responses-json)



The phone integration supports additional parameters for the Connect to agent response type. You can add these phone-specific parameters to the connect_to_agent response type using the JSON editor.

The connect_to_agent response type supports the ability to specify the target transfer information under the transfer_info parameter.

The following example shows a transfer that uses all of the configurable parameters:

{
"generic": [
{
"response_type": "connect_to_agent",
"transfer_info": {
"target": {
"service_desk": {
"sip": {
"uri": "sip:user\@domain.com",
"transfer_headers":
{
response.redirect(
{ method: 'POST' },
studioWebhookReturnUrl
);

// This callback is what is returned in response to this function being invoked.
// It's really important! E.g. you might respond with TWiML here for a voice or SMS response.
// Or you might return JSON data to a studio flow. Don't forget it!
return callback(null, response);
}
Show more

Replace {webhook_url} with the WEBHOOK URL value you copied from the Trigger widget in your Studio Flow.
7. Click Save.
8. Click Deploy All.
9. After you create this refer-handler, copy the function URL back into the /receive-call handler's referUrl field.







 Configuring the assistant to transfer calls to Twilio Flex 

Now we need to configure the assistant to transfer calls to Twilio Flex when a customer asks to speak to an agent. Follow these steps:



1. In the Watson Assistant user interface, open the dialog skill of your assistant.
2. Add a node with the condition you want to trigger your assistant to transfer customers to an agent.
3. Add a text response to the node, and specify the text you want your assistant to say to your customers before it transfers them to an agent.
4. Open the JSON editor for the response.
5. In the JSON editor, add a [connect_to_agent response](https://cloud.ibm.com/docs/assistant?topic=assistant-phone-context), specifying your phone number as the sip.uri (replace {phone_number} with the phone number of your SIP trunk):



{
"output": {
"generic": [
{
"response_type": "connect_to_agent",
"transfer_info": {
"target": {
"service_desk": {
"sip": {
Once the phone number has been enabled for SMS, you will see a webhook icon beside the number.

Paste the value that you copied from the Webhook URI field into it.
15. Click Save.
16. If you want to support multiple phone numbers, repeat the previous step for each phone number that you want to use.









 SMS Advanced configuration options 

The Advanced options tab is available after you set up the SMS integration. Click the Advanced options tab to make any of the following customizations to the messaging behavior:



* Initiate conversation from inbound messages: Disable this option if you want to limit messaging support to allow messages that are sent in the context of an ongoing phone integration conversation only, and not allow customers to start a message exchange with the assistant outside of a phone call.
* Default failure message: Add a message to send to the customer if the SMS connection fails.
* Base URL: This URL is the REST API endpoint for the SMS service you are using.







 Optimize your actions for messaging 

For the best customer experience, design your actions with the capabilities of the SMS integration in mind:



* Do not include HTML elements in your text responses.
* The SMS integration does not support chat transfers that are initiated with the connect_to_agent response type.
* Image, Audio, Video response types allow sending a message containing media. A title and description are sent along with the attachment. Note that depending on the carrier and device of the end user these messages may not be successfully received. For a list of the supported content types for Twilio, see [Twilio: Accepted Content Types for Media](https://www.twilio.com/docs/sms/accepted-mime-types).

For more information on these response types, see [Response types reference](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-response-types-reference).



If you want to use the same action for an assistant that you deploy to many different platforms, add custom responses per integration type. You can add a conditioned response that tells the assistant to show the response only when the SMS integration is being used.
[https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-configuration#onerror-detail](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-configurationonerror-detail)





 Failover 

Handling a failover for web chat is simple assuming you have set up an additional web chat integration in another region. When the failover needs to be manually triggered, make the following changes:



* The embed script that contains your integration ID, region, service instance ID, and subscription ID (if applicable) needs be changed or updated to use the IDs for the new integration and region.
* If you are using Salesforce or ZenDesk integrations for connecting to human agents, update the configuration within those systems to make sure they can communicate with the correct integration. Follow the instructions on the Live agent tab in the web chat configuration for setting up those systems. This is only needed for obtaining the conversation history for the agent.
* If you have web chat security enabled and you are using encrypted payloads, the IBM-provided public key used for the encryption may be different depending on region. If so, you need to update the system that generates the JSON Web Token (JWT) to use the correct key.



You can set up an active/active configuration of web chat by using different integration IDs in your embed scripts, and by ensuring the web chat integration is "sticky" by user. Otherwise, if the user fails over to a different integration, the conversation history might be lost.







 API 



 Monitoring 

Capture and monitor response codes of /message calls. Response codes of live /message traffic should be captured and aggregated.

Ideally, save the response code statistics in an external persistence store. This shared store can aggregate response code results from all deployed instances of a your application and provide the greatest fidelity in determining if a failover should be triggered.

Alternatively, response codes can be aggregated and evaluated in memory for a given instance of your application. As only a fraction of traffic is contributing to the failover decision, this could lead to different behavior with respect to how often the failover decision is acted upon.
Making a call after processing a message 

A postmessage webhook makes a call to an external service or application every time a response is rendered by the assistant. The external service can process the assistant output before it is sent to the channel.

You can add a postmessage webhook to your assistant if you want the webhook to be triggered before each message response is shown to the customer.

If you are using a custom channel, note that the postmessage webhook works with the v2 /message API only (stateless and stateful). For more information, see the [API reference](https://cloud.ibm.com/apidocs/assistant/assistant-v2message). All built-in channel integrations use this API.

You can use a postmessage webhook to do things like extract custom responses from an external content repository. For example, you can define actions with custom IDs in the responses instead of text. The postmessage webhook can pass these IDs to an external database to retrieve stored text responses.

You can use this webhook in coordination with the premessage webhook. For example, if you use the premessage webhook to strip personally identifiable information from the customer's input, you can use the postmessage webhook to add it back. Or if you use the premessage webhook to translate the customer's input to the language of the assistant, you can use the postmessage webhook to translate the response back into the customer's native language before it is returned. For more information, see [Making a call before processing a message](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-webhook-pre).

For environments where private endpoints are in use, keep in mind that a webhook sends traffic over the internet.



 Defining the webhook 

You can define one webhook URL to use for processing every message response before it is sent to the channel and shown to the customer.

The programmatic call to the external service must meet these requirements:



* The call must be a POST HTTP request.
For detailed information about how to this command, see [Applying advanced settings to the Speech to Text service](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-voice-actionsdialog-voice-actions-speech-advanced).





 Example 

This example uses the speech_to_text response type with the configure command to change the language model used by the Text to Speech service to Spanish, and to enable smart formatting.

{
"output": {
"generic": [
{
"response_type": "speech_to_text",
"command_info": {
"type": "configure",
"parameters": {
"narrowband_recognize": {
"model": "es-ES_NarrowbandModel",
"smart_formatting": true
}
}
},
"channels":
{
"channel": "voice_telephony"
}
]
}
]
}
}
Show more







 end_session 

Sends a command to the channel ending the session. This response type instructs the phone integration to hang up the call.



 Fields 



 Name Type Description Required? 

 response_type string end_session Y 



For the phone integration, you can use the channel_options object to include custom headers with the SIP BYE request that is generated. For more information, see [End the call](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-voice-actionsdialog-voice-actions-hangup).





 Example 

This example uses the end_session response type to end a conversation.

{
"output": {
"generic": [
{
"response_type": "end_session"
}
]
}
}







 user_defined 

A custom response type containing any JSON data the client or integration knows how to handle.
{
"output": {
"generic": [
{
"response_type": "connect_to_agent",
"message_to_human_agent": "User asked to speak to an agent.",
"agent_available": {
"message": "Please wait while I connect you to an agent."
},
"agent_unavailable": {
"message": "I'm sorry, but no agents are online at the moment. Please try again later."
}
}
]
}
}
Show more







 channel_transfer 

Requests that the conversation be transferred to a different integration.



 Fields 



 Name Type Description Required? 

 response_type string channel_transfer Y 
 message_to_user string A message to display to the user before the link for initiating the transfer. Y 
 transfer_info object Information used by an integration to transfer the conversation to a different channel. Y 
 transfer_info.target.chat string The URL for the website hosting the web chat to which the conversation is to be transferred. Y 







 Example 

This example requests a transfer from Slack to web chat. In addition to the channel_transfer response, the output also includes a text response to be displayed by the web chat integration after the transfer. The use of the channels array ensures that the channel_transfer response is handled only by the Slack integration (before the transfer), and the connect_to_agent response only by the web chat integration (after the transfer). For more information about using channels to target specific integrations, see [Targeting specific integrations](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-responses-jsondialog-responses-json-target-integrations).

{
"output": {
"generic": [
{
"response_type": "channel_transfer",
"channels":
{
"channel": "whatsapp"
}
],
"message_to_user": "Click the link to connect with an agent using our website.",