vania-janet/multiturn-rag-retrieval-data huggingface dataset:
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 

You can define one webhook URL to use for preprocessing every incoming message.

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



* The call must be a POST HTTP request.
* The request body must be a JSON object (Content-Type: application/json).
* The call must return in 30 seconds or less.



If your external service supports only GET requests, or if you need to specify URL parameters dynamically at run time, consider creating an intermediate service that accepts a POST request with a JSON payload containing any runtime values. The intermediate service can then make a request to the target service, passing these values as URL parameters, and then return the response to the dialog.

Do not set up and test your webhook in a production environment where the assistant is deployed and is interacting with customers.

To add the webhook details, complete the following steps:



1. From your assistant, click the ![Overflow menu](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/kebab.png) icon, and then choose Settings.
2. Click Webhooks > Pre-message webhook.
3. Set the Pre-message webhook switch to Enabled.
4. Decide whether to return an error if the webhook call fails.

When enabled, everything stops until the preprocessing step is completed successfully.



* If you have a critical preprocessing step that must be taken before you want to allow the message to be processed by the assistant, enable this setting.
https://us-south.functions.cloud.ibm.com/api/v1/web/my_org_dev/default/Hello%20World.json

If the external application that you call returns a response, it must be able to send back a response in JSON format.

Notice the request URL in this example ends in .json. By specifying this extension, you take advantage of a feature of web actions that lets you specify the desired content type of the response. Specifying this extension type ensures that, if the web actions can return responses in more than one format, a JSON response will be returned. See [Extra features](https://cloud.ibm.com/docs/openwhisk?topic=openwhisk-actions_webactions_web_extra) for more details.
3. If the web action is secured, specify any headers, such as X-Require-Whisk-Auth, that are required to call the web action.



Header example

 Header name Header value 

 `X-Require-Whisk-Auth` `{my-secret}` 



4. Click the Dialog tab.
5. Click to open the dialog node from which you want to call the web action, and then click Customize.
6. Scroll down to the webhook section. Set the Callout to webhooks switch to On, and then click Apply.
7. Add any data that you want to pass to the external application as key and value pairs in the Parameters section.

For example, if you call the Hello World Cloud Functions web action, you might want to add the following information to pass in the message parameter that is accepted by that application:



Parameter example

 Key Value 

 message hello 



When calling a Cloud Functions web action, you cannot pass parameters with the same key as parameters that are defined as part of the web action. See [Protected parameters](https://cloud.ibm.com/docs/openwhisk?topic=openwhisk-actions_webactions_web_protect_parameters) for more details.
8.
Dynamically reconfigures the Text to Speech service by applying a set of configuration parameters, which can be based on the conversation flow. For example, you might want to choose a particular voice at a specific point in the conversation.



 parameter description required default 

 synthesize The Text to Speech service configuration to use when synthesizing audio. The parameters defined by this object are used when connecting to the Text to Speech service for speech synthesis requests. For more information about these parameters, see the [Text to Speech API documentation](https://cloud.ibm.com/apidocs/text-to-speechsynthesize-audio-websockets-). yes Current Text to Speech configuration 
 update_strategy Specifies the update strategy to use when setting the speech configuration. Possible values include:<br><br><br><br> * replace: Replaces the configuration for the rest of the session. Any root-level fields in the new configuration completely overwrite the previous configuration.<br> * replace_once: Replaces the configuration only for the next turn of the conversation. Subsequently, the previous configuration is used.<br> * merge: Merges the new configuration with the existing configuration for the rest of the session. Only changed parameters are overwritten; any other configuration parameters are unchanged.<br> * merge_once: Merges the new configuration with the existing configuration only for the next turn of the conversation. Subsequently, the previous configuration is used.<br><br><br> no replace 



The parameters that you can set for synthesize reflect the parameters that are made available by the Text to Speech WebSocket interface. The WebSocket API sends two types of parameters: query parameters, which are sent when phone integration connects to the service, and message parameters, which are sent as part of the JSON data in the request body. For a full list of parameters, see the [Text to Speech API documentation](https://cloud.ibm.com/apidocs/text-to-speech).





 command_info.type : disable_barge_in 

Disables speech barge-in so that playback isn't interrupted when the caller speaks while audio is being played back.

No parameters.
Users with Lite or Trial accounts can view the [IBM Cloud documentation](https://cloud.ibm.com/docs/get-support?topic=get-support-using-avatar), Chat with Watson, and use [Stack Overflow](https://stackoverflow.com/questions/tagged/ibm-cloud).







 How do I escalate support cases? 

As an IBM Cloud customer, you can escalate support cases to surface critical issues. After a case is escalated, the IBM Cloud Support team reviews the information and responds with updates. For information about case severity, see [Case severity and initial response times](https://cloud.ibm.com/docs/get-support?topic=get-support-support-case-severity).

To escalate a case, complete the following steps:



1. Contact IBM Cloud Support by phone or chat:



* Pay-as-you-go or subscription accounts can contact support by phone and can find the number in the [Support Center](https://cloud.ibm.com/unifiedsupport/supportcenter).
* Contact by chat from the [Support Center](https://cloud.ibm.com/unifiedsupport/supportcenter) and click Chat with IBM from the Chat with a support agent tile.



2. Provide your existing case number and a request to escalate the case.
3. Provide the justification an escalation and explain the business impact of your problem or issue.



If your support inquiry requires a more immediate response, consider upgrading to the premium or advanced support plan so that you can open severity 1-4 support cases. To upgrade your support plan, contact a [IBM Cloud Sales](https://www.ibm.com/cloud?contactmodule) representative.





 How do I change my email preferences for notifications? 

You can change which email notifications you receive for planned events, unplanned events, and announcements in your profile settings. To change your email preferences, choose one of the following options:



* Go to [Notifications](https://cloud.ibm.com/user/notifications) in your profile settings.
If you decide you do not want to make a webhook call from a dialog node, open the node's Customize page, and then switch Webhooks Off.

The Parameters section and the Return variable field are removed from the dialog node editor. However, any conditional responses that were added for you or that you added yourself remain.

The Multiple conditioned responses section is editable again. You can choose to switch the feature off. If you do so, then only the first conditional response is saved as the node's only text response.

To change the external service that you call from dialog nodes, edit the webhook details defined on the Webhooks page of the Options tab. If the new service expects different parameters to be passed to it, be sure to update any dialog nodes that call it.





 Calling an IBM Cloud Functions web action 

Typically, web actions can be run without requiring the caller to authenticate first. However, you can secure a web action that requires any callers to pass an ID with the request. For more information about how to secure a web action, see [Securing web actions](https://cloud.ibm.com/docs/openwhisk?topic=openwhisk-actions_webactions_web_secure).

The following tips will help you call a Cloud Functions web action from your dialog.



1. Open the Options page for the skill, and then click Webhooks.
2. In the URL field, add the URL for the external application to which you want to send HTTP POST request callouts.

For example, to call a Cloud Functions web action, specify the URL for the public web action. For example:

https://us-south.functions.cloud.ibm.com/api/v1/web/my_org_dev/default/Hello%20World.json

If the external application that you call returns a response, it must be able to send back a response in JSON format.

Notice the request URL in this example ends in .json. By specifying this extension, you take advantage of a feature of web actions that lets you specify the desired content type of the response.
[Overflow menu](https://cloud.ibm.com/docs-content/v1/content/a2b18c153837bce00a5b4de496e4b4ca64bbf56e/assistant-data/images/kebab.png) icon, and then choose Settings.
2. Click Webhooks > Log webhook.
3. Set the Log webhook switch to Enabled.

If you cannot enable the webhook, you might need to upgrade your service plan.
4. In the URL field, add the URL for the external application to which you want to send HTTP POST request callouts.

For example, to write the message to https://www.mycompany.com/my_log_service, you must specify a URL that uses the SSL protocol. In this case, specify a URL that begins with https.
5. In the Secret field, add a token to pass with the request that can be used to authenticate with the external service.

The secret must be specified as a text string, such as purple unicorn. Maximum length is 1,024 characters. You cannot specify a context variable.

It is the responsibility of the external service to check for and verify the secret. If the external service does not require a secret, you can leave this field empty.

It is the responsibility of the external service to check for and verify the secret. If the external service does not require a token, specify any string you want. You cannot leave this field empty.
6. Click the appropriate checkboxes to select Subscribe to conversation logs.
7. In the Headers section, add any headers that you want to pass to the service one at a time by clicking Add header.

The service automatically sends an Authorization header with a JWT; you do not need to add one. If you want to handle authorization yourself, add your own authorization header and it will be used instead.



Your webhook details are saved automatically.





 Removing the webhook 

If you decide you do not want to log messages programmatically, complete the following steps:



1.
For more information about deleting a user's data, see [Labeling and deleting data](https://cloud.ibm.com/docs/assistant?topic=assistant-information-securityinformation-security-gdpr-wa).







 Human agent service integration 

You can configure the web chat to transfer a customer to a human customer support agent if the customer asks for help from a person. The following service desk integrations are supported:

Built-in service desk integrations:



* [Intercom](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-intercom)![Plus or higher plans only](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/plus.png)
* [Web chat with Salesforce support](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-salesforce)
* [Web chat with Zendesk support](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-zendesk)



Web chat service desk reference implementations:



* [Genesys Cloud](https://github.com/watson-developer-cloud/assistant-web-chat-service-desk-starter/tree/main/src/genesys/webChat)
* [NICE inContact](https://github.com/watson-developer-cloud/assistant-web-chat-service-desk-starter/tree/main/src/incontact/webChat)
* [Twilio Flex](https://github.com/watson-developer-cloud/assistant-web-chat-service-desk-starter/tree/main/src/flex/webChat)
* [Bring your own (starter kit)](https://github.com/watson-developer-cloud/assistant-web-chat-service-desk-starter/tree/main/src/genesys/webChat)
image
: Displays an image that is specified by a URL.

option
: Presents a set of options (such as buttons or a drop-down list) that users can choose from. The selected value is then sent to the assistant as user input.

pause
: Pauses before sending the next message to the channel, and optionally sends a "user is typing" event (for channels that support it).

speech_to_text
: Sends a command to the Speech to Text service instance used by the phone integration. These commands can dynamically change the configuration or behavior of the service during a conversation.

start_activities
: Sends a command to a channel integration to start one or more activities that are specific to that channel. You can use this response type to restart any activity you previously stopped by using the stop_activities response type.

stop_activities
: Sends a command to a channel integration to stop one or more activities that are specific to that channel. The activities remain stopped until they are restarted by using the start_activities response type.

text
: Displays text (or reads it aloud, for the phone integration). To add variety, you can specify multiple alternative text responses. If you specify multiple responses, you can choose to rotate sequentially through the list, choose a response randomly, or output all specified responses.

text_to_speech
: Sends a command to the Text to Speech service instance used by the phone integration. These commands can dynamically change the configuration or behavior of the service during a conversation.

user_defined
: A custom response type with any JSON data the client or integration knows how to handle.

video
: Displays a video that is specified by a URL.





 Channel integration support for response types 

The following table indicates which channel integrations support each type. For additional information about any channel-specific limitations, see [Response types reference](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-response-types-reference).



Channel integration support

 Response type Web chat Phone SMS Slack Facebook WhatsApp 

 audio !
"uri": "sip:+18883334444\@example.com",
"transfer_headers_send_method": "refer_to_header"
}
}
}
},
"agent_available": {
"message": "Ok, I'm transferring you to an agent"
},
"agent_unavailable": {
"message": ""
}
}
]
}
Show more

Make sure you use the \ escape characters so Watson Assistant does not misinterpret the @ as part of the entity shorthand syntax.
5. Make a test call and say something that initiates a transfer to an agent. In your Genesys Cloud console, you should see the transfer take place.





 Share the conversation history with service desk agents 

To enable the service desk agent to get a quick view of the conversation history between the visitor and the assistant, set up the Watson Assistant Agent App app for your Genesys Pure Cloud Environment. For more information, see the documentation for the [Genesys starter kit](https://github.com/watson-developer-cloud/assistant-web-chat-service-desk-starter/tree/main/src/genesys/agentApp).
* How long are log files kept for a workspace?

Messages are retained for 90 days. For more information, see [Log limits](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-logslogs-limits).
* How do I create a webhook?

To define a webhook and add its details, open the skill where you want to add the webhook. Open the Options page, and then click Webhooks to add details about your webhook. To invoke the webhook, call it from one or more of your dialog nodes. For more information, see [Making a programmatic call from dialog](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-dialog-webhooks).
* Can I have more than one entry in the URL field for a webhook?

No, you can define only one webhook URL for a dialog skill. For more information, see [Defining the webhook](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-dialog-webhooksdialog-webhooks-create).
* Can I extend the webhook time limit?

No. The service that you call from the webhook must return a response in 8 seconds or less, or the call is canceled. You cannot increase this time limit. For more information about strategies for handling complex actions with a webhook, watch the video in [Making a programmatic call from dialog](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-dialog-webhooks).



Analytics Analytics Engine



* Is IBM Cloud Object Storage included in IBM Analytics Engine?

No, IBM Cloud Object Storage isn't included. It is a separate offering.
* [Search skill](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-overviewdialog-overview-add-search-skill)![Plus or higher plans only](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/plus.png)

This response type is only visible to users of paid plans.
* [Text](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-overviewdialog-overview-simple-text)



2. To add another response type to the current response, click Add response type.

You might want to add multiple response types to a single response to provide a richer answer to a user query. For example, if a user asks for store locations, you could show a map and display a button for each store location that the user can click to get address details. To build that type of response, you can use a combination of image, options, and text response types. Another example is using a text response type before a pause response type so you can warn users before pausing the dialog.

You cannot add more than 5 response types to a single response. This means that if you define three conditioned responses for a dialog node, each conditioned response can have no more than 5 response types added to it.

You cannot add more than one Connect to human agent or more than one Search skill response type to a single dialog node.

Do not add more than one option response type to a single dialog node because both lists are displayed at once, but the customer can choose an option from only one of them.
3. If you added more than one response type, you can click the Move up or down arrows to arrange the response types in the order you want your assistant to process them.







 Adding a Connect to human agent response type 

If your client application is able to transfer a conversation to a person, such as a customer support agent, then you can add a Connect to human agent response type to initiate the transfer.
Plan whether you want to connect the assistant to existing content sources by taking an inventory of relevant help content (for example, product information, knowledge articles, FAQs) available to your customers.

You can give your assistant access to this information by adding a [search integration](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-search-add) to your assistant. The search integration uses IBM Watson® Discovery to return smart answers to natural language questions.





 5. Plan your handoff strategy 

Finally, prevent customers from hitting dead ends by [escalating conversations to a human agent](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-human-agent) if the assistant isn't able to resolve a customer's question or problem. As part of your planning, figure out what your escalation strategy is going to be. This strategy will vary depending on the deployment channel you choose.

If you deploy to your website, you have three options for escalating to a human agent:



* Inline
* Email address
* Phone number



If you opt for the inline approach, you can directly escalate to a human agent in your existing contact center tool without forcing the user to leave the web chat widget. This approach also provides the agent with the full context of the conversation. To use either the email address or phone number approach, provide the user with the agent’s email address or phone number. These approaches are simple to set up, but they can be more disconnected experiences for your customers.

If you deploy by using the phone integration, you can reach a human agent only by transferring the phone call to someone who can help.





 Start building an assistant 

If you're ready to start building an assistant, see [Editing actions](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-build-actions-overview) for more information.
The WebSocket API sends two types of parameters: query parameters, which are sent when phone integration connects to the service, and message parameters, which are sent as part of the JSON data in the request body. For a full list of parameters, see the [Text to Speech API documentation](https://cloud.ibm.com/apidocs/text-to-speech).





 command_info.type : disable_barge_in 

Disables speech barge-in so that playback isn't interrupted when the caller speaks while audio is being played back.

No parameters.





 command_info.type : enable_barge_in 

Enables speech barge-in so that callers can interrupt playback by speaking.

No parameters.





 Changing the assistant's voice 

You can change the voice of your assistant when it covers certain topics in the conversation that warrant it. For example, you might want to use a voice with a British accent for a branch of the conversation that applies only to customers in the UK.

This example shows how to specify a voice during the conversation:

{
"generic": [
{
"response_type": "text_to_speech",
"command_info": {
"type": "configure",
"parameters": {
"synthesize": {
"voice": "en-GB_KateV3Voice"
}
}
}
}
]
}

Show more

In the voice parameter, specify the voice model that you want to use. 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.