Skill Level: Intermediate

In this recipe, you will learn how to consume a content available via an external API directly from Watson Conversation dialog via IBM Cloud functions.


- Watson Conversation instance & dialog

- IBM Cloud Function

- Watson Discovery or an external services exposed via an API


  1. Implement an IBM Cloud Function

    Actions to do:

    1. Go to IBM Cloud Console https://console.bluemix.net
    2. Search in the Catalog “Functions”
    3. Click on Functions service
    4. Click on “Start Creating”
    5. Click on “Create an action”
    6. Type your Action name [action_name]
    7. Create a package [package_name]
    8. (optional) Select your language. In that recipe, I wil use Node.js
    9. Create your function (https://www.ibm.com/blogs/bluemix/2016/12/node-js-code-openwhisk-actions/) or import the one I have done and will illustrate in that recipe to query Watson Discovery and retrieve passages (https://github.com/vperrinfr/MyIBMCloud_Functions).
    10. Save your action
    11. Click on “Change Input”

    Example of an input:


       “authorization”: “”,

    And finally, click on “Invoke” to test the connection.

    You should see a JSON content with content passages of relevant documents.


    Retrieve Namespace (for the next step configuration):

    • Go to “Getting started”
    • Copy Namespace value



  2. Implement an IBM Function call within Watson Conversation

    December 7th, we have introduce a new capability in Watson Conversation in Beta : IBM Cloud Functions integration to make callouts directly from a dialog node.

    Watson Conversation implement an “Anything Else” feature to provide an response even when the chatbot is not able to capture an intent.

    Leveraging IBM Watson Discovery server can help to find an appropriate answer within a corpus of documents, instead of answering a generic answer will help you to have a more performant, relevant chatbot.

    Actions to do:

    • Open Watson Conversation dialog
    • Go to Anything Else node (it could be another one of course)
    • Open JSON editor of the response

    Use a similar JSON content:

       “output”: {
        “text”: {
        “values”: [
        “[YOUR INTRODUCTION OF THE TEXT] : <? $wds.passages[0].passage_text ?>”
        “selection_policy”: “sequential”
    “actions”: [
       “name”: “/[namespace]/[package_name]/[action_name]”,
       “type”: “server”,
       “parameters”: {
          “url”: “”,
          “input”: “<? input.text ?>”,
          “authorization”: “”,
          “collection_id”: “”,
          “environment_id”: “”
     “credentials”: “$mycreds”,
     “result_variable”: “context.wds”

    It should be something like this



    • Test the call. You should have as a result of your message the passe retrieved via Watson Discovery.



  3. Improvements

    Potential improvements or adaptation:

    • Implement threshold on confidence in the Function not to a “bad” passage but a generic message. The threshold could be a parameter of the function.
    • Accept User & password instead of authorization key

2 comments on"Watson Conversation & IBM Cloud Functions together"

  1. When trying to invoke the Discovery function within OpenWhisk, I get an error 500:

    “error”: {
    “error”: null,
    “response”: {
    “statusCode”: 500,
    “body”: “\nenv:ClientInternal Error (from client)”,
    “headers”: {
    “content-type”: “text/xml”,
    “x-dp-watson-tran-id”: “gateway01-422529587”,
    “x-backside-transport”: “FAIL FAIL”,
    “connection”: “close”

  2. Where to find below ids?

Join The Discussion