Build an enterprise-connected virtual assistant with no code

You can quickly and easily build a chatbot using Watson Assistant, with no custom code to manage, secure, or maintain. Also, you can quickly and easily build an API using IBM App Connect. Then, your chatbot can natively call your API via a webhook.

IBM App Connect allows you to “connect anything to anything” and build workflows to “do anything” between those connections. We are talking workflows or business logic and transformations.

IBM App Connect can run two kinds of flows: event driven flows and flows for APIs. In this tutorial, you’ll build an API that acts as a router for incoming calls from our Watson Assistant chatbot. For example, I was able to add a ServiceNow problem creation conversation to my Watson Assistant in less than 15 minutes, including the creation of the ServiceNow sandbox.

Architecture of our sample app

Image of Architecture

Note: IBM API Connect is shown in the architecture above but not explicitly used in this tutorial. IBM App Connect actually contains API Connect functionality (we use this built in functionality to publish the API below). In an enterprise, you may want to consider using the IBM API Connect service externally as shown above.

Prerequisites

Steps

Step 1: Create the Watson Assistant bot

  1. Sign in to your IBM Cloud account

  2. Create a Watson Assistant service. Use the Lite plan. For my own solution, I used the Plus version that comes with an incredibly simple way to embed the bot into a web page.

  3. Launch Watson Assistant. Then, on the Management page of your Watson Assistant, click the Assistants menu in the left nav bar.

  4. Click Create Assistant. Follow the steps in the Getting started with Watson Assistant document to create the assistant and create a skill.

  5. Click the skill you created to edit its contents – the intents, entities, dialog, and other settings of your assistant. Click Create intent to add an intent called “#get_my_ip” and complete it as shown below.

    Image of Architecture

    Close the intent (the down arrow at top of the screen).

  6. Click the Dialog tab to define a dialog, including a webhook. First, click the Add node button. Then, click the Customize gear icon, and in the dialog that is displayed, turn the Webhooks slider to on, and click Apply. In the dialog node settings, some additional fields are displayed for you to define the webhook.

    Image of Architecture

The parameters section allows you to send data with your webhook call. We will be creating an API that accepts a type parameter later. For this demo, let’s add the type parameter and give it a value of getIPAddress. Any number of parameters can be sent.

The Return variable is automatically populated with a name but can be changed to anything you want. This becomes a Watson Assistant context variable (called $webhook_result_1 in this example) and will be filled with all the data that is returned by the webhook call later. Context variables can be accessed and used in your dialogs.

The “Assistant responds” section is also pre-populated with a couple of values. If you change the variable name above, you’ll need to change the name in this section too.

  • The first line basically says, “if we get a result back from the webhook (that is, the variable is populated), then say x“. If the bot recognizes $webhook_result_1, then respond with My IP address is <? $webhook_result_1.responseData ?>. The <? x ?> format basically inserts a variable into the dialog reply and can be used with any context variable used within Watson Assistant.

  • The second line handles errors and Watson Assistant returns errors in a particular format, shown below. If assistant recognizes anything else (that is, an error), then reply with The callout generated this error: <? output.webhook_error.webhook_result_1 ?>.

We return two variables in our API call: responseData and responseBody. We set responseData to contain the IP Address value and responseBody to contain the whole of the JSON object returned by the API we call. To display the whole JSON object, we can use <? $webhook_result_1.responseBody ?> in the Watson Assistant dialog.

The last part to complete in Watson Assistant is setting the webhook, but we need to create the API to call first! We will use IBM App Connect to create the API. Within IBM App Connect, we can then create as many integrations as we want (each called via a different type parameter), which can be called via that one API.

Step 2: Create an API using IBM App Connect

  1. In your IBM Cloud account, create an IBM App Connect instance. Use the Lite plan and follow the setup steps.

  2. Once the setup completes, open IBM App Connect, click Manage, and then click the Launch App Connect button.

  3. In the Dashboard section, click the New button, and select Create flows for an API. Give your API a name. Then, give your model a name and click Create model.

    Image of Architecture

  4. Set your API properties. Set type, requestBody, responseBody, and responseData as String properties.

    All the fields are required exactly as shown in this tutorial except for responseData, which I used that to return raw data in my test but we don’t discuss that here.

    Image of Architecture

  5. Click the Operations option, and select Add a custom operation. Specify routeAutomation as the display name, and optionally provide a description. Specify POST as the HTTP verb. For the operation name, specify routeAutomation. Finally, select automation for both the request body and response body.

    Image of Architecture

  6. Click the Implement Flow button. In the drag and drop flow editor, click the + between the Request and Response objects, click the Toolbox option, and add an “If (conditional)” block as shown below.

    Image of Architecture

    • Click the yellow diamond icon in the if block, and configure the if statement. Select the type parameter by clicking in the first field then clicking the icon to the right of the field.

      Image of Architecture

    • Add an Application by clicking the + icon, click the Applications option, and select HTTP. Select the Invoke method link. Click the Connect button. You don’t need to add any details in the Account settings for this example, all the fields can be left blank because we will not be calling an API that requires authentication or any special connection details.

      Image of Architecture

    • Once added, edit the settings of the HTTP application. Select GET for the HTTP method. For the URL, specify https://api.ipify.org?format=json which is the API we will be calling, and it just returns the IP address of the calling system in JSON format.

      Image of Architecture

    • Add another node to the flow by clicking the + icon to the right of the HTTP node, and selecting JSON Parser from the Toolbox list. By using the JSON Parser node, we can select exactly what data that is returned from the HTTP node is returned by the If statement. Otherwise, only the whole output of the HTTP node (a JSON object) is returned and your Assistant will need to handle extracting the data (which may actually be desired in some situations).

      Image of Architecture

      Configure the JSON Parser node as follows. Use the 3-bar icon in the field to select Response body from the HTTP Invoke method drop-down (not the Request drop-down).

      Image of Architecture

      In the Output Schema section, enter an example output as shown below {"ip":"192.168.0.1"} and then click the Generate schema button.

      In this case we know what the example output is (because I’ve called it previously) but obviously you’d need find out yourself what any other API you want to call produces. This may seem fiddly, but it’s required; otherwise, the flow doesn’t know what data it has to map of course.

      Image of Architecture

  7. Back on the flow, click the yellow If icon again. We are going to configure the output of the getIPAddress If statement. Click the Output schema drop down, and configure the settings as shown below. This is where the actual output of the whole If flow is configured. In our case we could remove the type property if we wanted. I have left it in place.

    Image of Architecture

  8. Click on the Output data drop down, and select the options shown below.

    • responseBody comes from the HTTP node (and contains the full JSON response of the API we called).
    • type comes from the request object (that is, it is passed through all the way).
    • responseData comes from the JSON Parser node (and is the value of the IP key obtained from the full JSON response of the HTTP node).

      Image of Architecture

  9. We need to publish the API so that Watson Assistant can call it via its webhook feature. Click the Done button, and then select the Manage option (next to Define).

    As it says, “To get started, scroll down to ‘Sharing Outside of Cloud Foundry organization’ and click on ‘Create API key’. Follow the ‘API Portal Link’ link to explore the API in the portal and invoke it by clicking on ‘Try it'”.

    Give the API key any name you want.

    Image of Architecture

    You’ll end up with an API key and a URL linking to the API definition as shown below.

    Image of Architecture

    Copy the link and paste to a new browser window. You’ll see something similar to the page below.

    Image of Architecture

    The endpoint URL is what you’ll need to paste into the Watson Assistant webhook setting (along with the API Key that you created above).

  10. Finally, we need to start the flow in IBM App Connect so it is callable. At the top of the page you’ll see three dots. Click those three dots, and select Start API. If all goes well, the circle should turn green, and our API is running.

    If you want to edit the flow later, you’ll need to stop the flow first, make your updates, and then start it again.

Step 3: Putting it all together

  1. Back in Watson Assistant, go to your skill, and select Options, and Webhooks.

  2. Paste the API endpoint URL into the Webhook URL field.

  3. Add three headers (using the Add header option below the headers section): Content-Type (application/json), Accept (application/json), and X-IBM-Client-Id (the API Key from above).

    Image of Architecture

We can now try the integration! Click on the Try it out link at the top right of the page and type “what’s your ip address?”. The result should come back as shown below!

Image of Architecture

Summary and next steps

In this tutorial, we looked at giving Watson Assistant the ability to take action in an enterprise environment.

The powerful webhook feature of Watson Assistant and the drag and drop API creation feature of IBM App Connect were combined to show how this could be achieving with no code being written.

Learn more about the IBM App Connect application connectors to see what other enterprise solutions you can create with no code needed! Along with these application connectors, the HTTP connector allows developers to connect into any other API-enabled service. Also, check out the new Watson Assistant web widget to embed a functional web chat into your website.

Use this Watson Assistant learning path to help you get started creating chatbots for your enterprise.