Making a programmatic call from dialog

Defining the webhook

You can define one webhook URL for a dialog skill, and then call the webhook from one or more dialog nodes.

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

• The call must be a POST HTTP request.

• The format of the request and response must be in JSON. For example: Content-Type: application/json.

• The call must return in 8 seconds or less.

  For less efficient services that you need to call, you can manage the call through a client application and pass the information to the dialog as a separate step. For more information, see Calling a client application from a dialog node.

To add the webhook details, complete the following steps:

1. From the skill menu for the skill where you want to add the webhook, click Options.

2. Click Webhooks.

3. 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 the Language Translator service, specify the URL for your service instance.

   https://api.us-south.language-translator.watson.cloud.ibm.com/v3/translate?version=2018-05-01
   

   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. This setting is enabled to support adding different responses depending on the success or failure of the Webhook call. If you had a response specified for the node already, it becomes the first conditional response.

5. 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 Language Translator service, you must provide values for the following parameters:

   Parameter example

   Key	Value	Description
   model_id	"en-es"	Identifies the input and output languages. In this example, the request is for text in English (en) to be translated into Spanish (es).
   text	"How are you?"	This parameter contains the text string that you want the service to translate. You can hard code this value, pass a context variable, such as $saved_text, or pass the user input to the service directly, by specifying ` ` as this value.

   In more complex use cases, you might collect information during a conversation with a user about their travel plans, for example. You can collect dates and destination information and save it in context variables that you can pass to an external application as parameters.

   Travel parameters example

   Key	Value
   depart_date	$departure
   arrive_date	$arrival
   origin	$origin
   destination	$destination

6. Any response made by the callout is saved to the return variable. You can rename the variable that is automatically added to the Return variable field for you. If the callout results in an error, this variable is set to null.

   The generated variable name has the syntax webhook_result_n, where the appended _n is incremented each time you add a webhook callout to a dialog node. This naming convention ensures that context variable names are unique across the dialog skill. If you change the name, be sure to use a unique name.

7. In the conditional responses section, two response conditions are added automatically, one response to show when the webhook callout is successful and a return variable is sent back. And one response to show when the callout fails. You can edit these responses, and add more conditional responses to the node.

   • If the callout returns a response, and you know the format of the JSON response, then you can edit the dialog node response to include only the section of the response that you want to share with users.

     For example, the Language Translator service returns an object like this:

        {
        "translations":[
           {"translation":"¿Cómo estás?"}
        ],
        "word_count":3,
        "character_count":12
        }
     

     Use a SpEL expression that extracts only the translated text value.

     Conditional responses example

     Condition	Response
     $webhook_result_1	Your words in Spanish: .
     anything_else	The call to the external application failed. Please try again later.

     If you use the recommended format for the response and the translation response shown earlier is returned, the assistant's response to the user would be: Your words in Spanish: ¿Cómo estás?

   • If you want to provide a specific response if the callout returns an empty string, meaning the call is successful, but the value returned is an empty string, you can add a conditional response that has a condition with syntax like this:

     $webhook_result_1.size() == 0
     

8. When you are done, click the X to close the node. Your changes are automatically saved.

Testing webhooks

When you first add a webhook callout, it can be useful to see exactly what is returned in the response from the external application, the data and its format. To do this, add this expression as the text response for the successful callout conditional response: $webhook_result_n where n is the appropriate number for the webhook you are testing.

This response returns the full body of the return variable, so you can see what the callout is sending back and decide what to share with the user. You can then use the methods documented in Expression language methods to extract only the information you care about from the response.

Test whether certain user inputs can generate errors in the callout, and build in ways to handle those situations. Errors generated by the external application are stored in output.webhook_error.<result_variable>. You can use a conditional response like this while you are testing to capture such errors:

For example, you might not be authenticating the request properly (401), or you might be trying to pass a parameter with a name that is already in use by the external application. Test the webhook to discover and fix these types of errors before you deploy the webhook.

Removing a webhook

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 page. If the new service expects different parameters to be passed to it, be sure to update any dialog nodes that call it.