vania-janet/multiturn-rag-retrieval-data huggingface dataset:
They can change topics, follow a dialog flow about the unrelated topic to its end, and then return to where they were before. The result is a dialog flow that more closely simulates a human-to-human conversation.<-- <ul> --> * Before you begin]] * Customizing digressions]] * Digression usage tips]] * Disabling digressions into a root node]] * Digression tutorial]] * Design considerations]] ! ! ! !!!! ! ! ! ! ! ! !<-- </ul> --><-- <section "id="section-dialog-runtime-digression-prereqs" "> --> Before you begin As you test your overall dialog, decide when and where it makes sense to allow digressions and returns from digressions to occur. The following digression controls are applied to the nodes automatically. Only take action if you want to change this default behavior.<-- <ul> --> * Every root node in your dialog is configured to allow digressions to target them by default. Child nodes cannot be the target of a digression. * Nodes with slots are configured to prevent digressions away. All other nodes are configured to allow digressions away. However, the conversation cannot digress away from a node under the following circumstances:
<-- <ul> -->

* If any of the child nodes of the current node contain the anything_else or true condition

<-- </ul> -->

These conditions are special in that they always evaluate to true. Because of their known behavior, they are often used in dialogs to force a parent node to evaluate a specific child node in succession. To prevent breaking existing dialog flow logic, digression are not allowed in this case. Before you can enable digressions away from such a node, you must change the child node's condition to something else.

<-- <ul> -->

* If the node is configured to jump to another node or skip user input after it is processed
A 180 Ringing response is sent from the assistant back to the SIP trunk provider while your assistant processes the incoming call invitation. The ringing response is sent by default.
* Don't place callers on hold while transferring to a live agent: Choose whether the phone integration puts the caller on hold.

If your SIP trunk provider manages holds, disable this feature. For example, some SIP trunk providers prefer to have the assistant send a SIP REFER request, so they can put the call on hold themselves.



For more information about the SIP protocol, see [RFC 3261](https://tools.ietf.org/html/rfc3261) and about the RTP protocol, see [RFC 3550](https://tools.ietf.org/html/rfc3550).







 Configuring backup call center support 

When you use the phone integration as the first line of assistance for customers, it's a good idea to have human backup available. You can design your assistant to be able to transfer a call to a human in case the phone connection fails, or 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. If you use the web chat integration with service desk support, there's no way to transfer the phone call to the existing service desk that is set up for the web chat, for example.

For whichever call center service you use, you will need to provide the call center SIP URI. You must specify this information in your dialog when you enable a call transfer from a dialog node. For more information, see [Transfer a call to a human agent](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-voice-actionsdialog-voice-actions-transfer).





 Optimize your dialog for voice 

For the best customer experience, design your dialog with the capabilities of the phone integration in mind:



* Do not include HTML elements in your dialog text responses. To add formatting, use Markdown.
[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.



1. Add an [Onanswer](https://help.nice-incontact.com/content/studio/actions/onanswer/onanswer.htm) event to your script. The Onanswer event is triggered when an agent answers the call.
2. Use [Assign](https://help.nice-incontact.com/content/studio/actions/assign/assign.htm) to store the link to the conversation history into a variable. Variable watson_url Value[https://web-chat.global.assistant.watson.appdomain.cloud/loadAgentAppFrame.html?session_history_key={sessionKey}](https://web-chat.global.assistant.watson.appdomain.cloud/loadAgentAppFrame.html?session_history_key=%7BsessionKey%7D)
3. Use the [PopURL](https://help.nice-incontact.com/content/studio/actions/popurl/popurl.htm) action to display the conversation transcript to a live agent. URL {watson_url}



![Image of the conversation history window](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/cxone-pop-url.png)





 Disconnecting a call
The dialog gathers any information it needs to respond or perform a transaction on the user's behalf.

The dialog can interact with the following resources:



* Other IBM services: Connect with additional Watson services to analyze user input, such as Speech to Text.
* Back-end systems: Based on the user's intent and additional information, extract information or perform transactions by interacting with your back-end systems. For example, answer question, open tickets, update account information, or place orders.



* Any questions that cannot be answered by the dialog skill are sent to the search skill, which finds relevant answers by searching the company knowledge bases that you configure for the purpose. The search skill routes complex customer inquiries to IBM Watson® Discovery for IBM Cloud Pak® for Data. Discovery treats the user input as a search query. It finds information that is relevant to the query from the configured data sources and returns it so the assistant can share the information with the user as its response.







 Implementation 

This diagram shows the implementation in more detail:

![Flow diagram of the service](https://cloud.ibm.com/docs-content/v1/content/a2b18c153837bce00a5b4de496e4b4ca64bbf56e/assistant-data/images/cp4d-diagram.png)

Here's how you implement your assistant:



1. Create an assistant.
2. Create a dialog skill. Use the intuitive graphical tool to define the training data and dialog for the conversation between your assistant and your customers.

The training data consists of the following artifacts:



* Intents: Goals that you anticipate your users have when they interact with your assistant. Define one intent for each goal that can be identified in a user's input. For example, you might define an intent that is named store_hours that answers questions about store hours. For each intent, you add sample utterances that reflect the input customers might use to ask for the information they need, such as, What time do you open?

Or use prebuilt content catalogs that are provided by IBM to get started with data that addresses common customer goals.
let sessionId;

// Create session.
service
.createSession({
assistantId,
})
.then(res => {
sessionId = res.result.session_id;
sendMessage({
messageType: 'text',
text: '', // start conversation with empty message
});
})
.catch(err => {
console.log(err); // something went wrong
});

// Send message to assistant.
function sendMessage(messageInput) {
service
.message({
assistantId,
sessionId,
input: messageInput,
})
.then(res => {
processResponse(res.result);
})
.catch(err => {
console.log(err); // something went wrong
});
}

// Process the response.
function processResponse(response) {

let endConversation = false;

// Check for client actions requested by the assistant.
if (response.output.actions) {
if (response.output.actions[0].type === 'client'){
if (response.output.actions[0].name === 'display_time') {
// User asked what time it is, so we output the local system time.
console.log('The current time is ' + new Date().toLocaleTimeString() + '.');
} else if (response.output.actions[0].name === 'end_conversation') {
// User said goodbye, so we're done.
console.log(response.output.generic[0].text);
endConversation = true;
}
}
} else {
// Display the output from assistant, if any. Supports only a single
// response.
if (response.output.generic) {
To use the WebSocket interface, you first use the /v1/recognize method to establish a connection with the service. You specify parameters such as the language model and any custom models that are to be used for requests that are sent over the connection. You then register event listeners to handle responses from the service. To make a request, you send a JSON text message that includes the audio format and any additional parameters. You pass the audio as a binary message (blob), and then send a text message to signal the end of the audio.

The following example provides JavaScript code that establishes a connection and sends the text and binary messages for a recognition request. The basic example does not include the code to define all of the necessary event handlers for the connection.

var access_token = {access_token};
var wsURI = '{ws_url}/v1/recognize'
+ '?access_token=' + access_token;
var websocket = new WebSocket(wsURI);

websocket.onopen = function(evt) { onOpen(evt) };

function onOpen(evt) {
var message = {
action: 'start',
content-type: 'audio/flac'
};
websocket.send(JSON.stringify(message));
websocket.send(blob);
websocket.send(JSON.stringify({action: 'stop'}));
}
Show more





 Using the synchronous HTTP interface 

[The synchronous HTTP interface](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-http) provides the simplest way to make a recognition request. You use the POST /v1/recognize method to make a request to the service. You pass the audio and all parameters with the single request. The following curl example shows a basic HTTP recognition request:

IBM Cloud
The log webhook is called with each message and its corresponding response.
* Where the condition is defined

For a dialog webhook, the condition to meet before an action is taken is defined in the dialog skill. If the node condition is not met, then the dialog webhook is never called.

For the message processing webhooks, the condition to check for before taking an action must be defined in the external application code. For example, even if your webhook performs a simple language translation, you'd want to use a condition to check the language of the incoming message before sending the text to the translation service.

You don't need to define a condition for the log webhook unless you want to filter the messages somehow. In most cases, the goal is to write out every message that is submitted, so the messages can be stored for as long as you want, and analyzed by an external application or service.
* Where you configure them

You configure the dialog webhook from the the Options>Webhook page of the dialog skill. You then initialize it from one or more dialog nodes by customizing the node.

You configure the assistant-level webhooks from the Settings>Webhooks page for the assistant.
* Send to team or teammate: The assistant evaluates the user input to determine its goal, and then transfers it to the appropriate teammate.
* Suggest to team or teammate: The assistant provides the teammate with suggestions for how to respond by sharing notes with the human agent through the internal Intercom app.



* If the user input triggers a dialog branch, meaning a root dialog node with child nodes that represents a comprehensive interaction, then the assistant indicates that it is capable of addressing the request, and offers to do so.
* If the user input triggers a root node with no children, then the assistant simply shares the programmed response from the node with the human agent, but does not respond directly to the user.
* If the input triggers more than one dialog node with high confidence, the assistant shows the human teammate a list of possible responses and asks the teammate to choose the best response.



In every case, the human agent decides whether to let the assistant take over.
* Answer: The assistant responds to the user directly, without conferring with any other teammates.



Teammate involvement is required for any nodes to which you assign the Send to team or teammate or Suggest to team or teammate action types. Be sure to go back and add a rule that assigns the right person or team as the backup for this dialog node in particular.
7. To define unique interaction settings for other dialog branches, click New rule again, and repeat the previous steps.
8. After adding rules, click Return to overview to exit the page.



As your dialog changes, you will likely return to the Intercom integration page to make incremental changes to these rules.





 Testing the integration 

To effectively test your Intercom integration from end-to-end, you must have access to an Intercom end-user application. You already created or edited an Intercom workspace. The workspace must have an associated user interface client. If it does not, see [How do I create an app?](https://www.intercom.com/help/en/articles/1827298-how-do-i-create-an-app) for help with setting one up.

Submit test user queries through a client application that is associated with your Intercom workspace to see how the messages are handled by Intercom.
Webhook overview 

Make a call to an external service or application during a conversation.

Watson Assistant supports the following types of webhooks:



* Skill-level webhooks

The following type of webhook can be set up for use from a dialog skill:



* [Dialog](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-dialog-webhooks)



* Assistant-level webhooks

The following types of webhooks can be set up for an assistant:



* [Logs](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-webhook-log)
* [Premessage](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-webhook-pre)
* [Postmessage](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-webhook-post)







 Which type of webhook should I use? 

The skill-level webhook is different from the assistant-level webhooks in the following ways:



* Frequency with which the webhooks is called

The dialog webhook is called on the rare occasion that the dialog node from which it is triggered is processed.

The message processing webhooks are called with every single exchange in a conversation between the customer and the assistant.

The log webhook is called with each message and its corresponding response.
* Where the condition is defined

For a dialog webhook, the condition to meet before an action is taken is defined in the dialog skill. If the node condition is not met, then the dialog webhook is never called.

For the message processing webhooks, the condition to check for before taking an action must be defined in the external application code. For example, even if your webhook performs a simple language translation, you'd want to use a condition to check the language of the incoming message before sending the text to the translation service.
* A conversational skill interprets the customer's message further, then directs the flow of the conversation. The skill gathers any information it needs to respond or perform a transaction on the customer's behalf.
* A search skill leverages existing FAQ or other curated content that you own to find relevant answers to customer questions.
* If a customer wants more personalized help or wants to discuss a sensitive subject, the assistant can connect the customer with someone from your support team through the web chat integration.





For more information about the architecture, read the [How to Make Chatbot Orchestration Easier](https://medium.com/ibm-watson/how-to-make-chatbot-orchestration-easier-c8ed61620b8d) blog on Medium.com.

To see how Watson Assistant is helping enterprises cut costs and improve customer satisfaction today, read the [Independent study finds IBM Watson Assistant customers can accrue $23.9 million in benefits](https://www.ibm.com/blogs/watson/2020/03/independent-study-finds-ibm-watson-assistant-customers-accrued-23-9-million-in-benefits/) blog on ibm.com.

This documentation describes managed instances of Watson Assistant that are offered in IBM Cloud or in Cloud Pak for Data as a Service. If you are interested in on-premises or installed deployments, see [this documentation](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-index).

Read more about these implementation steps by following these links:



* [Creating an assistant](https://cloud.ibm.com/docs/assistant?topic=assistant-assistant-add)
* [Adding skills to your assistant](https://cloud.ibm.com/docs/assistant?topic=assistant-skill-add)
* [Deploying your assistant](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-integration-add)







 Browser support 

The Watson Assistant application (where you create assistants and skills) requires the same level of browser software as is required by IBM Cloud.
Create a handler for the [history:begin](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-eventshistorybegin) event, which is fired when the web chat is reloaded from the session history. In this handler, save any reloaded session history to the list.

function saveHistory(event) {
messages.push(...event.messages);
}
3. In your onLoad event handler, use the [on()](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-instance-methodson) instance method to subscribe to the send, receive, and history:begin events, registering the appropriate handlers as callbacks.

instance.on({ type: 'send', handler: saveMessage });
instance.on({ type: 'receive', handler: saveMessage });
instance.on({ type: 'history:begin', handler: saveHistory });
4. Create a function that converts the messages saved in the messages list to the format you want to provide in the downloaded file. Note that this conversion needs to accommodate any response types that the conversation might include (such as text, images, options, or transfers to a human agent).

In this example, we convert the messages into a CSV file format that can be opened with an application such as Microsoft Excel. The first column in each line is a label that indicates whether the message originated from the customer (You) or from the assistant (Lendyr).

This function relies on a helper function (createDownloadText) that formats the text for each line. You can see the implementation of this helper function in the [full example](https://github.com/watson-developer-cloud/assistant-toolkit/tree/master/integrations/webchat/examples/download-history).

function createDownload() {
const downloadLines = [createDownloadText('From', 'Message')];

messages.forEach(message => {
"value": "XXXXXX"
}
]
}
}
}
}
]
}
}
Show more





 Sending a text message during a phone conversation 

There are some situations when it is useful to be able to send a text message during an ongoing voice. For example, you might want the customer to specify a street address, which is easier to communicate accurately in writing than by transcribing voice input.

Before you can send SMS messages during a phone call, you must set up the SMS with Twilio integration. For more information, see [Integrating with SMS with Twilio](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-sms).

When you exchange a text with a customer during a conversation, the dialog initiates the SMS message exchange. It sends a text message to the user and asks for the user to respond to it.

To send a specific message from a dialog node or action step, use the user_defined response type with the vgwActSendSMS command:

{
"output": {
"generic": [
{
"response_type": "text",
"values":
{
"text": "I will send you a text message now."
}
],
"selection_policy": "sequential"
},
{
"response_type": "user_defined",
"user_defined": {
"vgwAction": {
"command": "vgwActSendSMS",
"parameters": {
"message": "Hey, this is Watson Assistant. To send me your street address, respond to this text message with your address."
}
}
}
}
]
}
}
Show more

You can specify any of the following parameters in the parameters object:



 Parameter Type Description 

 message string The text of the SMS message to send. Required. 
 mediaURL list A list of URLs for media files to be sent with the message as MMS attachments.
This handler modifies the payload of outgoing message events to assign a value to a context variable called User_Name.

We want to set the user name only once at the beginning of the conversation. This example assumes that the home screen is not enabled, which means that the web chat initiates each new conversation with an empty message to trigger a greeting from the assistant.

For this example, we are using the hardcoded user name Cade. In a production assistant, you might retrieve the customer's name from a user profile on your website.

function preSendHandler(event) {
// Only do this on messages that request the welcome message.
if (event.data.input && event.data.input.text === '') {
event.data.context.skills['actions skill'] = event.data.context.skills['actions skill'] || {};
event.data.context.skills['actions skill'].skill_variables = event.data.context.skills['actions skill'].skill_variables || {};
event.data.context.skills['actions skill'].skill_variables.User_Name = 'Cade';
}
}
2. In your onLoad event handler, use the [on()](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-instance-methodson) instance method to subscribe to the pre:send event, registering the preSendHandler() function as the callback.

instance.on({ type: 'pre:send', handler: preSendHandler });



The assistant actions can now access the User_Name variable throughout the conversation.

For complete working code, see the [Setting context variables for Watson Assistant web chat](https://github.com/watson-developer-cloud/assistant-toolkit/tree/master/integrations/webchat/examples/set-context) example.