vania-janet/multiturn-rag-retrieval-data huggingface dataset:
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-data-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 is is returned. For more information, see [Making a call before processing a message](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-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-data?topic=assistant-data-dialog-webhooks).

For environments where private endpoints are in use, keep in mind that a webhook sends traffic over the internet.
However, provisioning the new number might take several minutes.





 Adding more phone numbers 

If you are using existing phone numbers you configured via a SIP trunk provider, you can add multiple numbers to the same phone integration.

If you generated a free phone number, you cannot add more numbers.

To add more phone numbers:



1. In the phone integration settings, go to the Phone number tab.
2. Use one of the following methods:



* To add phone numbers one by one, click Add phone number in the table, and enter the phone number along with an optional description. Click the Add button to save the number.
* To import a set of phone numbers that are stored in a comma-separated values (CSV) file, click the Upload a CSV file icon (![Add phone number][images/phone-integ-import-number.png]), and then find the CSV file that contains the list of phone numbers.

The phone numbers you upload will replace any existing numbers in the table.









 Setting up live agent escalation 

If you want your assistant to be able to transfer a conversation to a live agent, you can connect your phone integration to a contact center. For more information, see instructions for the supported platform:



* [Genesys](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-deploy-phone-genesys)
* [Twilio Flex](https://cloud.ibm.com/docs/watson-assistant?topic=watson-assistant-deploy-phone-flex)







 Phone integration limits 

Any speech service charges incurred by the phone integration are included as Voice add-on charges in your Watson Assistant service plan usage. The Voice add-on use is charged separately and in addition to your service plan charges.

Plan usage is measured based on the number of monthly active users, where a user is identified by the caller's unique phone number. An MD5 hash is applied to the phone number and the 128-bit hash value is used for billing purposes.

The number of concurrent calls that your assistant can participate in at one time depends on your plan type.



Plan details

 Plan Concurrent calls 

 Enterprise 1,000
If the external application that you call returns a response, it must be able to send back a response in JSON format. For the Language Translator service, for example, you must specify the format in which you want the result to be returned. You can do so by passing a header to the service.
4. In the Headers section, add any headers that you want to pass to the service one at a time by clicking Add header.

For example, add a header that indicates that you want the resulting value to be returned in JSON format.



Header example

 Header name Header value 

 Content-Type application/json 



5. If the external service requires that you pass basic authentication credentials with the request, then provide them. Click Add authorization, add your credentials to the User name and Password fields, and then click Save.

The product creates a base-64 encoded ASCII string from the credentials and generates a header that it adds to the page for you.



Header example

 Header name Header value 

 Authorization Basic ` ` 



For testing purposes, you can submit an API key over basic authentication. Click Add authorization, and then add apikey to the User name field, and paste the API key value into the Password field. Click Save.



Your webhook details are saved automatically.





 Adding a webhook callout to a dialog node 

To use a webhook from a dialog node, you must enable webhooks on the node, and then add details for the callout.



1. From the skill menu, click Dialog.
2. Find the dialog node where you want to add a callout. The callout to the webhook will occur whenever this node is triggered during a conversation with a user.

For example, you might want to send a callout to the webhook from the General_Greetings node.
3. Click to open the dialog node, and then click Customize.
4. Scroll down to the Webhooks section, and switch the toggle to On, and then click Apply.

If you did not have it enabled already, the Multiple conditional responses setting is switched on automatically and you cannot disable it.
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/watson-assistant?topic=watson-assistant-phone-actionsphone-actions-transfer), specifying your phone number as the sip.uri (replace {phone_number} with the phone number of your SIP trunk):



{
"generic": [
{
"response_type": "connect_to_agent",
"transfer_info": {
"target": {
"service_desk": {
"sip": {
For more information, see the [API reference](https://cloud.ibm.com/apidocs/assistant-data-v1listlogs) and the [Filter query reference](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-filter-reference).





 Can I export and import dialog nodes? 

No, you cannot export and import dialog nodes from the product user interface.

If you want to copy dialog nodes from one skill into another skill, follow these steps:



1. Download as JSON files both the dialog skill that you want to copy the dialog nodes from and the dialog skill that you want to copy the nodes to.
2. In a text editor, open the JSON file for the dialog skill that you want to copy the dialog nodes from.
3. Find the dialog_nodes array, and copy it.
4. In a text editor, open the JSON file for the dialog skill that you want to copy the dialog nodes to, and then paste the dialog_nodes array into it.
5. Import the JSON file that you edited in the previous step to create a new dialog skill with the dialog nodes you wanted.







 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?
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.

If you want to see the secret as you enter it, click on the Show password icon ![view icon](https://cloud.ibm.com/docs-content/v1/content/icons/view.svg) before you start typing. After you save the secret, the string is replaced by asterisks and can't be viewed again.
6. Click the appropriate checkboxes to select which kinds of activity you want to log:



* To log messages and responses, select Subscribe to conversation logs.
* To log CDR events for the phone integration, select Subscribe to CDR (Call Detail Records).



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.

After you save the header value, the string is replaced by asterisks and can't be viewed again.



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. From the assistant overview page, 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 > Log webhook.
3.
At run time, if the conversation reaches this child node, the dialog is passed to a human agent at that point.



Your dialog is now ready to support transfers from your assistant to a service desk agent.

For more information about different service desk solutions, see the following resources:



* [Adding service desk support to the web chat](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-web-chatdeploy-web-chat-haa)
* [Integrating with Intercom](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-intercom)







 Measuring containment 

From the Analytics page, you can measure conversation containment. Containment is the rate at which your assistant is able to satisfy a customer's request without human intervention per conversation.

To measure containment accurately, the metric must be able to identify when a human intervention occurs. The metric primarily uses the Connect to human agent response type as an indicator. If a user conversation log includes a call to a Connect to human agent response type, then the conversation is considered to be not contained.

However, not all human interventions are transacted by using a Connect to human agent response type. If you use an alternate method to deliver additional support, you must take additional steps to register the fact that the customer's need was not fulfilled by the assistant. For example, you might direct customers to your call center phone number or to an online support ticket form URL. If so, you need to flag these types of redirects so the containment metric is able to pick them up.

To enable the containment metric, complete the following steps:



1. For any dialog nodes that transfer the chat to a service desk agent, add a Connect to human agent response type.

For more information, see [Adding a Connect to human agent response type](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-overviewdialog-overview-add-connect-to-human-agent).
2. For any dialog nodes that redirect customers to alternate forms of customer support, add a context variable named context_connect_to_agent and set it to true.
However, there might be times when you want to route a customer to a different Salesforce agent queue. For example, your dialog might have a root dialog node that conditions on a close_account intent. For that branch of the conversation only, you want to transfer customers to agents in the sales queue who are authorized to offer incentives as a way to retain customers. You can direct transfers to specific agent queues by adding routing logic to your dialog.

You can specify alternate routing preferences based on:



* browser information
* the current topic of conversation





 Routing based on browser information 

When a customer interacts with the web chat, information about the current web browser session is collected. For example, the URL of the current page is collected. You can use this information to add custom routing rules to your dialog. For example, if the customer is on the Products page when a transfer to a human is requested, you might want to route the chat transfer to a queue with agents who are experts in your product portfolio. If the customer is on the Returns page, you might want to route the chat transfer to a queue with agents who know how to help customers return merchandise.

For more information, see [Web chat: Accessing browser information](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-integrationsdialog-integrations-chat-browser-info).





 Routing by topic 

When you enable transfers to the Salesforce service desk, you copy and paste code snippets from Salesforce into the service desk transfer setup page. These code snippets define how transferred conversations are handled within Salesforce. Routing rules are included in the initial transfer configuration. The routing rules identify the queue of agents to which messages from the assistant are transferred by default.

The code that you add to the setup page when you configure the service desk integration shares the following required information with Watson Assistant:



* organization_id: Unique ID of the organization. A company can have more than one organization set up in Salesforce.
* chat_api_endpoint: Salesforce API endpoint that is used by the integration to communicate with Salesforce.
* deployment_id: Unique ID of the deployment.
Zendesk support is generally available
: Integrate your web chat with Zendesk so your assistant can transfer customers who asks to speak to a person to a Zendesk agent who can answer their questions. And now you can secure the connection to Zendesk. For more information, see [Adding support for transfers](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-zendesk).

Pricing plan changes
: We continue to revamp the overall service plan structure for Watson Assistant. In April, we announced [a new low cost entry point](https://cloud.ibm.com/docs/assistant?topic=assistant-release-notes1April2020) for the Plus plan. Today, the Standard plan is being retired. Existing Standard plan users are not impacted; they can continue to work in their Standard instances. New users do not see the Standard plan as an option when they create a service instance. For more information, see the [Pricing](https://www.ibm.com/cloud/watson-assistant/pricing/) page.





 27 May 2020 

Full language support for new system entities
: The new version of the system entities is generally available in dialog skills of all languages, including Arabic, Chinese (Simplified), Chinese (Traditional), Korean, and Japanese. For more information, see [Supported languages](https://cloud.ibm.com/docs/assistant?topic=assistant-language-support).

New system entities are enabled automatically
: All new dialog skills use the new version of the system entities automatically. For more information, see [New system entities](https://cloud.ibm.com/docs/assistant?topic=assistant-system-entities).





 22 May 2020 

Spelling correction in v2 API
: The v2 message API now supports spelling correction options. For more information see the [API Reference](https://cloud.ibm.com/apidocs/assistant/assistant-v2message).





 21 May 2020 

Preview link URL change
: The URL for the preview link was changed.
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. The most common such situation is transferring a conversation to the web chat integration, to take advantage of web chat features such as service desk integration. For more information, see [Adding a Channel transfer response type](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-overviewdialog-overview-add-channel-transfer).

Intercom and WhatsApp integrations now available in Lite plan
: The integrations for Intercom and WhatsApp are now available in the Lite plan for Watson Assistant. For more information, see [Integrating with Intercom](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-intercom) and [Integrating with WhatsApp](https://cloud.ibm.com/docs/assistant?topic=assistant-deploy-whatsapp).





 16 March 2021 

Session history now generally available
: Session history allows your web chats to maintain conversation history and context when users refresh a page or change to a different page on the same website. It is enabled by default. For more information about this feature, see [Session history](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=tutorials-session-history).

Session history persists within only one browser tab, not across multiple tabs. The dialog provides an option for links to open in a new tab or the same tab. See [this example](https://web-chat.global.assistant.watson.cloud.ibm.com/docs.html?to=tutorials-session-historyTutorial1) for more information on how to format links to open in the same tab.
[Overflow menu](https://cloud.ibm.com/docs-content/v1/content/a2b18c153837bce00a5b4de496e4b4ca64bbf56e/assistant-data/images/kebab.png) icon, and then choose Settings.
2. Click Webhooks > Post-message webhook.
3. Set the Post-message webhook switch to Enabled.
4. Decide whether to return an error if the webhook call fails.

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



* If you have a critical postprocessing step that must be taken before you want to allow the response to be sent to the customer, then enable this setting.
* When this setting is disabled, the assistant ignores any errors it encounters and continues to process the response without taking the processing step. If the postprocessing step is helpful but not critical, consider keeping this setting disabled.



5. In the URL field, add the URL for the external application to which you want to send HTTP POST request callouts.

For example, maybe you store your assistant's responses in a separate content management system. When the skill understands the input, the processed dialog node returns a unique ID that corresponds to a response in your CMS. To call a service that retrieves a response from your CMS for a given unique ID, specify the URL for your service instance.

https://my-webhook.com/get_answer

You must specify a URL that uses the SSL protocol, so specify a URL that begins with https.

You cannot use a webhook to call a Cloud Functions action that uses token-based Identity and Access Management (IAM) authentication. However, you can make a call to a Cloud Functions web action or a secured web action.
6. In the Secret field, add a private key to pass with the request that can be used to authenticate with the external service.

The key must be specified as a text string, such as purple unicorn. Maximum length is 1,024 characters. You cannot specify a context variable.
"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 human 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 agent. You can use the Connect to human agent response type in a dialog node or action step to initiate a transfer to a human agent at a specific point in the conversation. When a Connect to human 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 human agent during the conversation, see the following documentation:



* [Adding Connect to human agent response type](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-overviewdialog-overview-add-connect-to-human-agent) (dialog node)
* [Deciding what to do next](https://cloud.ibm.com/docs/assistant?topic=assistant-actionsactions-what-next) (action step)



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