vania-janet/multiturn-rag-retrieval-data huggingface dataset:
This documentation is for the classic Watson Assistant experience. To see the documentation for the new Watson Assistant, please go [here](https://cloud.ibm.com/docs/watson-assistant).



 Integrating with Facebook Messenger 

Facebook Messenger is a mobile messaging application that helps businesses and customers communicate directly with one another.

After you configure a dialog skill and add it to an assistant, you can integrate the assistant with Facebook Messenger.

There is currently no mechanism for identifying users who interact with the assistant through Facebook Messenger, which means that is no way to identify or delete data associated with a specific user. Do not use this integration method for deployments that must be GDPR compliant. See [Information security](https://cloud.ibm.com/docs/assistant?topic=assistant-information-security) for more details.



1. From the Assistants page, click to open the assistant tile that you want to deploy.
2. From the Integrations section, click Add integration.
3. Click Facebook Messenger.
4. Follow the instructions that are provided on the screen to complete the integration process.





 Dialog considerations 

The rich responses that you add to the dialog are displayed in a Facebook app as expected, with the following exceptions:



* Connect to human agent: This response type is ignored.
* Image: This response type embeds an image in the response. A title and description are not displayed before the image, whether or not you specify them.
* Audio: This response type embeds audio from various file formats in the response. A title and description are not displayed, whether or not you specify them.
* Video: This response type embeds a native video from various file formats in the response. A title and description are not displayed, whether or not you specify them.
* iframe: This response type inserts an embeddable third-party link in the response that displays interactive content (such as forms or maps). A title is displayed in the preview card. A description is not displayed, whether or not you specify it.
* Option: This response type shows a list of options that the user can choose from.
kafka_http_url: https://mh-<id>.private.us-south.messagehub.appdomain.cloud
6. From the [Monitoring dashboard](https://cloud.ibm.com/observe/monitoring), click Open dashboard for the Monitoring instance that you want to use.
7. Click Get Started > Configure a notification channel > Configure Notification Channel. The Settings page opens.
8. Click + Add Notification Channel and select the Webhook option.
9. Configure the webhook notification channel. After you create the webhook notification channel, you must continue to set up authentication for the channel.



* For URL, enter the kafka_http_url from the service key, and append the /topics/<topic>/records route to the URL. The <topic> is the name of the topic that you created in your Event Streams instance.
* For Name, enter a name for the webhook notification channel.
* Leave the other fields at the default settings.
* Click Save to create the channel.



10. [Get an IAM token](https://cloud.ibm.com/docs/monitoring?topic=monitoring-api_token) to authenticate your requests to the Monitoring API.
11. Curl the Monitoring API to list the notification channels.



* Replace <region> with the region of your Monitoring instance, such as us-east.
* Replace <token> with the IAM token that you previously retrieved.



curl ’https://<region>.monitoring.cloud.ibm.com/api/notificationChannels' --header ‘Authorization: Bearer <token>’ | jq

In the output, note the id of the notification channel where the options.url field matches the URL that you previously created.

{
"id": 123,
"version": 6,
...
"options": {
"notifyOnOk": true,
The settings include separate greeting messages for the desktop and mobile versions of the launcher.

The language of the default text shown within the launcher depends on the locale configured for the web chat. For more information, see [Languages](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=api-instance-methodslanguages). If you customize the greeting text, the text you provide is used regardless of the locale settings.





 Configuring the home screen 

By default, the web chat window shows a home screen that can welcome users and tell them how to interact with the assistant. The home screen replaces any greeting that would otherwise be sent by a Welcome node in a dialog skill, or by the Greet customer system action in an actions skill. (If you prefer to use a Welcome node or a Greet customer system action instead of the home screen, you can disable the home screen on the Home screen tab.)

![An example of the home screen](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/home-screen.png)



1. Add a greeting that is engaging and invites the user to interact with your assistant. A greeting is required.
2. Add three conversation starter messages.

These messages are displayed in the web chat as examples of the types of questions that customers can ask. Customers can click one of them to submit it to the assistant.

You must test each message that you add as a conversation starter. Use only questions that the assistant understands and knows how to answer well.

If your assistant has multiple skills attached to it, the dialog skill orchestrates the incoming messages. If you want an action that you created to respond to a conversation starter message, make sure your dialog is set up to call the action. For more information, see [Calling an actions skill from a dialog](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-call-action).

All three conversation starters are required.
Integrating with Zendesk 

IBM Cloud

Integrate web chat with a Zendesk service desk solution, so your customers always get the help they need.

Connect to Zendesk by deploying your assistant with the web chat integration that serves as the client interface. If, in the course of a chat with your assistant, a customer asks to speak to a person, you can transfer the conversation directly to a live agent.

Zendesk allows you to assist customers in real time, which increases customer satisfaction. And satisfied customers are happier customers. To learn more about this service desk solution, see the [Zendesk website](https://www.zendesk.com/service/).



 Before you begin 



1. Sign up for or switch to a [Zendesk Service account with an Enterprise plan](https://www.zendesk.com/enterprise/), which is required.
2. Create a subdomain for your service desk. After you sign up and specify a subdomain, your Zendesk console is available from a URL with the syntax: <subdomain>.zendesk.com. For example, ibm.zendesk.com.
3. Log in to your [Zendesk](https://www.zendesk.com/login/) subdomain.
4. Open the Zendesk Dashboard.
5. Click the Products icon in the header, and then select the Chat icon.

![Screen capture of the chat icon in the header.](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/zd-products-menu.png)
6. Click your profile, and then select Check Connection.

![Screen capture of the Zendesk user interface to show where the profile is located.]
For more information, see [Defining the webhook](https://cloud.ibm.com/docs/assistant?topic=assistant-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.
* I received the message “Query cancelled” when importing a skill

This message is displayed when the skill import stops because artifacts in the skill, such as dialog nodes or synonyms, exceed the plan limits. For information about how to address this problem, see [Troubleshooting skill import issues](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-skill-dialog-addskill-dialog-add-import-errors).

If a timeout occurs due to the size of the skill but no plan limits are exceeded, you can reduce the number of elements that are imported at a time by completing the following steps:



1. Make a copy of the JSON file that you are trying to import.
2. Open the copy of the JSON file in an editor, and delete the entities array.
3. Import the edited JSON file as a new skill.
4. If this step is successful, edit the original copy of the JSON file.
5. Remove the dialog_nodes, intents, and counterexamples arrays.
6. Update the skill by using the API. Be sure to include the workspace ID and the append=true flag, as in this example:



curl -X POST -H "content-type: application/json" -H "accept: application/json" -u "apikey:{apikey}" -d@./skill.json "url/api/v1/workspaces/{workspace_id}?version=2019-02-28&append=true"
* The training process takes a long time and appears stuck
You can call an extension that has been added to your assistant in order to interact with an external service. For example, you might use an extension to interact with a ticketing or customer relationship management (CRM) system, or to retrieve real-time data such as mortgage rates or weather conditions. For more information about calling an extension, see [Calling an extension](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-call-extension).





 Search for the answer ![Plus or higher plan only](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/plus.png) 

This option indicates that the assistant should use the IBM Watson® Discovery service to search an external data source for information related to the customer's question. To use this option, you must configure a search integration for your assistant. For more information about configuring a search integration, see [Leveraging existing help content](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-search-add).





 Connect to agent 

This option indicates that the assistant should transfer the conversation to a human agent. For more information, see [Connecting to a live agent](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-human-agent).





 End the action 

This option indicates that this action is complete. Any action variable values that were defined based on choices that the customer made during the action are reset. The action ends immediately, without executing any subsequent steps.

This option can be applied to more than one step in a single action because an action can define more than one branch of a conversation, controlled by step conditions. For example, the open an account action might have one conversational flow for creating a checking account and a separate one for creating a savings account. Each branch might have its own final step. Identifying the final step helps analytical tools that follow a customer's progress through an action to identify the success or failure of the action.
"url": "https://example.com/webchat"
}
}
}
}
]
}
Show more





 Ending the call 

You can instruct your assistant end a phone call by using the end_session response type, as shown in this example.

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

You can optionally include custom headers to include with the SIP BYE request that is generated when the phone integration receives this response type.

This example shows the end_session response type with custom SIP headers:

{
"generic": [
{
"response_type": "end_session",
"channel_options": {
"voice_telephony": {
"sip": {
"headers":
{
"name": "Customer-Header1",
"value": "Some-Custom-Info"
},
{
"name": "User-to-User",
"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 integration. For more information, see [Integrating with SMS](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-deploy-sms).

When you exchange a text with a customer during a conversation, the assistant 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 an action step, use the user_defined response type with the vgwActSendSMS command:

{
This documentation is for the classic Watson Assistant experience. To see the documentation for the new Watson Assistant, please go [here](https://cloud.ibm.com/docs/watson-assistant).



  Advanced development tasks 

A developer can extend the capabilities of your assistant by using tools that are provided within the product or the product APIs or a combination of both.



*  [Using webhooks](https://cloud.ibm.com/docs/assistant?topic=assistant-webhook-overview)
*  [Dialog skill development](https://cloud.ibm.com/docs/assistant?topic=assistant-skill-develop)
*  [Web chat development](https://cloud.ibm.com/docs/assistant?topic=assistant-web-chat-basics)
*  [Custom user interface development](https://cloud.ibm.com/docs/assistant?topic=assistant-api-overview)
This documentation is for the classic Watson Assistant experience. To see the documentation for the new Watson Assistant, please go [here](https://cloud.ibm.com/docs/watson-assistant).



  Advanced skill development 

A developer can extend the capabilities of a skill.

Learn more about what's possible in the following sections.



  Dialog skill development 



*  [Adding custom dialog flow for integrations](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-integrations)
*  [Defining responses using the JSON editor](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-responses-json)
*  [Handling phone interactions](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-voice-actions)
*  [Handling SMS with Twilio interactions](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-sms-actions)
*  [Making a programmatic call from dialog](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-webhooks)
*  [Requesting client actions](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-actions-client)
When a chat session is reset, the dialog loses any contextual information that it saved during the previous exchange with the user. For example, if the dialog asks for the user's name and then calls the user by that name throughout the rest of the conversation, then after the chat session ends and a new one begins, the dialog will start by asking for the user's name again.

To change the timeout, complete the following steps:



1. Click the menu for your assistant ![open and close list of options](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/kebab.png), and then choose Settings.
2. Change the time specified in the Timeout limit field. The choices and maximum timeout vary depending on your plan.
3. Close the settings page. Your change is saved automatically.







 Session limits 

The length allowed for an inactivity timeout differs by service instance plan type. The following table lists the limits.



Service plan details

 Service plan Chat session default inactivity period Chat session maximum inactivity period 

 Enterprise 1 hour 168 hours (7 days) 
 Premium (legacy) 1 hour 168 hours (7 days) 
 Plus 1 hour 24 hours 
 Trial 5 minutes 5 minutes 
 Lite 5 minutes 5 minutes
You are charged for the duration of any data that you send to the service, including the silence that you send to extend a session.



For more information, see [Timeouts](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-inputtimeouts). Ideally, you would establish a session just before you obtain audio for transcription and maintain the session by sending audio at a rate that is close to real time. Also, make sure your application recovers gracefully from closed sessions or connections.

IBM removed this functionality to ensure that it continues to offer all users a best-in-class, low-latency speech recognition service.





 10 April 2017 

Speaker labels now supported for US English, Spanish, and Japanese
: The service now supports the speaker labels feature for the following broadband models:



* US English broadband model (en-US-BroadbandModel)
* Spanish broadband model (es-ES-BroadbandModel)
* Japanese broadband model (ja-JP_BroadbandModel)



For more information, see [Speaker labels](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-speaker-labels).

New support for Web Media (WebM) audio format
: The service now supports the Web Media (WebM) audio format with the Opus or Vorbis codec. The service now also supports the Ogg audio format with the Vorbis codec in addition to the Opus codec. For more information about supported audio formats, see [audio/webm format](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-audio-formatsaudio-formats-webm).

New support for Cross-Origin Resource Sharing
: The service now supports Cross-Origin Resource Sharing (CORS) to allow browser-based clients to call the service directly. For more information, see [Leveraging CORS support](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-service-featuresfeatures-cors).
Repeat the configuration process, specifying the values that you want to use for the live environment.

If you are using multiple environments, follow the same steps to configure the extension for each environment. For more information, see [Adding and using multiple environments](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-multiple-environments).



The extension is now available in the environments that you configured, and it can be called from the assistant. For more information about how to call an extension from an action, see [Calling a custom extension](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-call-extension).





 Plan limits 

The number of custom extensions you can add to an assistant depends on your plan. If you already added the maximum number of extensions to the assistant, you must remove one before you can add a new one.



Extension limits by plan

 Plan Extensions per assistant 

 Enterprise 100 
 Premium (legacy) 100 
 Plus 10 
 Trial 5 
 Lite 3 
 Standard (legacy) 0
* [Transfer the conversation to the web chat integration](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-voice-actionsdialog-voice-actions-transfer-channel)
* [End the call](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-voice-actionsdialog-voice-actions-hangup)
* [Send a text message during a phone conversation](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-voice-actionsdialog-voice-actions-sms)



In some cases, you might want to combine response types to perform multiple actions. For example, you might want to implement two-factor authentication by requesting phone keypad entry and sending a text message from the same dialog node or step. For more information, see [Defining a sequence of phone actions](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-voice-actionsdialog-voice-actions-sequence).

For reference information about phone-specific repsonse types and related context variables, see [Phone context variables](https://cloud.ibm.com/docs/assistant?topic=assistant-phone-context).



 Adding phone-specific responses to your dialog or actions 

To initiate a voice-specific interaction from a dialog node or a step in an action, add a response within the output.generic array using the appropriate response type.

Although many response types can be specified using the Watson Assistant user interface, phone-specific response types must currently be added using the JSON editor.

For more information about using the JSON editor to add responses, see [Defining responses using the JSON editor](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-responses-json).





 Applying advanced settings to the Speech to Text service 

Use the speech_to_text response type to send configuration commands to the Speech to Text service instance used by the phone integration. By sending a speech_to_text response from a dialog node or action step, you can dynamically change the Speech to Text configuration during a conversation.
![Yes](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/checkmark-icon.svg) 





* The SMS integration supports ending a session by using the terminateSession action command.







 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/watson-assistant?topic=watson-assistant-phone-actionsphone-actions-hangup).





 Example 

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

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







 iframe 

Embeds content from an external website as an HTML iframe element.



 Integration channel support 



 Web chat Facebook 

 ![Yes](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/checkmark-icon.svg) ![Yes](https://cloud.ibm.com/docs-content/v1/content/ca9232b3702768f24bb897f48f10778fcda28718/watson-assistant/images/checkmark-icon.svg) 





* Currently, the web chat integration ignores the description and image_url properties. Instead, the description and preview image are dynamically retrieved from the source at run time.







 Fields 



 Name Type Description Required? 

 response_type string iframe Y 
 source string The URL of the external content. The URL must specify content that is embeddable in an HTML iframe element. Y
For more information, see [Handling phone interactions](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-voice-actionsdialog-voice-actions-transfer-channel).





 3 December 2021 

Configure webhook timeout
: 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?topic=assistant-webhook-overview).





 27 November 2021 

New API version
: The current API version is now 2021-11-27. This version introduces the following changes:



* The output.text object is no longer returned in message responses. All responses, including text responses, are returned only in the output.generic array.







 9 November 2021 

New phone response types
: New response types are available for controlling the configuration and behavior of the phone integration. These response types replace most of the older vgw actions, which are now deprecated. (The vgw actions will continue to work, so existing skills do not need to be changed.) For more information, see [Handling phone interactions](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-voice-actions).

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?topic=assistant-dialog-overviewdialog-overview-multimedia).





 4 November 2021 

Actions enhancement: Add variables to links
: In an actions skill, when including a link in an assistant response, you can now access and use variables. In the URL field for a link, type a dollar sign ($) character to see a list of variables to choose from.





 14 October 2021 

vgwHangUp message no longer sent