Your First Dialog

Welcome to the Conversational AI Cloud getting started guide aimed at getting your first dialog interactions off the ground! 🚀

Introduction

In our guide called Your First Conversation we took a look at:

• Sending in basic interactions to Conversational AI Cloud through the Gateway API
• Using the session ID to continue the conversation after your first interaction

The next step in shaping your end-users' conversational experience is to implement what are called dialogs. Dialogs are a way for you to have a back-and-forth with your end-users in the conversation to guide them towards their goal. It is essentially a decision tree that your end-user walks through, where you can guide them with (dialog) options along the way. So, let's take a look at how to implement this using the Gateway API, building on what we already explored in our previous getting started guide.

In this guide we'll be:

• Triggering a dialog by sending in a question to the /ask endpoint on the Gateway API
• Looking at the response object to find out how we can tell whether or not we're in a dialog
• Using the session ID, and one of the dialog options, we'll continue the conversation through the dialog

📘

Pre-requisites

To follow along with this guide you'll need to have the following available to you:

• Conversational AI Cloud environment provisioned, and ready-to-use
• Project within your Conversational AI Cloud environment
• Your projects credentials ready-to-use:
  • Customer key
  • Project key
  • Culture of your projects content
  • API key for your project
• A dialog set-up in your projects content
• An article (Q&A) that triggers a dialog in your projects content

Triggering a Dialog

Triggering a dialog is done by triggering an event, or asking a question that links to an article with a dialog as its answer. For now, we're going to send in a question through the /ask endpoint on the Gateway, and then we'll take a look at the response to see if we find anything different from what we've seen before.

const axios = require("axios").default;

const options = {
  method: 'GET',
  url: 'https://api.digitalcx.com/ask',
  params: {
    customerKey: 'your-customer-key',
    projectKey: 'your-project-key',
    culture: 'your-projects-culture',
    apiKey: 'your-api-key',
    q: 'What options do you have available for me?'
  }
  headers: {
    Accept: 'application/json, standard'
  }
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});

If we send in this request we'll get a response that roughly looks like this:

{
    "outputs": [
        {
            "outputId": 129,
            "kbaId": 282,
            "dialogPath": "83:43",
            "interactionValue": "What options do you have available for me?",
            "isDefault": true,
            "dimensionValues": [
                []
            ],
            "outputParts": [
                {
                    "type": "answer",
                    "text": "I understood that you're looking for more information around returning your order. I'd be happy to help you further.  \n  \nFirst off, what specifically do you want me to help you out with?\n\r\n\r\n\r\n* %{DialogOption(I want to know about your return policy)}\r\n* %{DialogOption(I want to return my order)}",
                    "links": [],
                    "projectConstants": [],
                    "dialogOptions": [
                        "I want to know about your return policy",
                        "I want to return my order"
                    ],
                    "metadata": {},
                    "images": [],
                    "videos": []
                }
            ],
            "kbaCategories": []
        }
    ],
    "sessionId": "36088b09-7082-4c15-bebf-3cd4a4540dd3",
    "interactionId": "00000000-0000-0000-0000-000000000000",
    "culture": "en",
    "inputs": {
        "originalInputText": "What options do you have available for me?"
    }
}

Immediately there's a few things that stand out:

• The dialogPath property is filled inside the outputs
• Looking at the outputParts as part of the outputs array we see that the dialogOptions array is filled with two options: I want to know about your return policy and I want to return my order

If we're looking for a way to reliably determine if the conversation is in a dialog, we should always look at the dialogPath property since dialog options are optional, and dependent on the content defined.

🚧

Session ID

Make sure to always send in a session ID if you have one! That way Conversational AI Cloud can continue stateful interactions such as dialogs, and match interactions from the same user in its analytics environment 🤓

Now let's continue through this dialog by calling the Gateway API again with one of the dialog options as input, and the session ID as a query parameter:

const axios = require("axios").default;

const options = {
  method: 'GET',
  url: 'https://api.digitalcx.com/ask',
  params: {
    customerKey: 'your-customer-key',
    projectKey: 'your-project-key',
    culture: 'your-projects-culture',
    apiKey: 'your-api-key',
    q: 'I want to know about your return policy',
    'session.id': '36088b09-7082-4c15-bebf-3cd4a4540dd3',
  }
  headers: {
    Accept: 'application/json, standard'
  }
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});

And if we look at the response from the Gateway it'll look something like:

{
    "outputs": [
        {
            "outputId": 130,
            "kbaId": 44,
            "dialogPath": "83:43/44",
            "interactionValue": "I want to know about your return policy",
            "isDefault": true,
            "dimensionValues": [
                []
            ],
            "outputParts": [
                {
                    "type": "answer",
                    "text": "You can return any order within 14 days of receiving it.  \n  \nI could help you with that if you want, just let me know and we can get started!\n\r\n\r\n\r\n* %{DialogOption(Yes)}\r\n* %{DialogOption(No thank you)}",
                    "links": [],
                    "projectConstants": [],
                    "dialogOptions": [
                        "Yes",
                        "No thank you"
                    ],
                    "metadata": {},
                    "images": [],
                    "videos": []
                }
            ],
            "kbaCategories": []
        }
    ],
    "sessionId": "36088b09-7082-4c15-bebf-3cd4a4540dd3",
    "interactionId": "00000000-0000-0000-0000-000000000000",
    "culture": "en",
    "inputs": {
        "originalInputText": "I want to know about your return policy"
    }
}

If we take another look at the response we see that:

• The session ID that was returned to us hasn't changed (sessions expire after 15 mins or 24 hours of inactivity)
• The outputParts contain a different answer, with the information we requested (information on the return policy)
• The outputParts contain new dialog options to continue through the dialog
• The dialogPath has changed from 83:43 to 83:43/44 meaning that we went one step further in the dialog!

So by providing the session ID, and choosing one of the dialog options returned by the Gateway API we've been able to step through the dialog as if we were an end-user.

As a developer you can easily tell if your end-user is in a dialog or not by looking at the dialogPath property, and you can help your end-users by providing them with suggestions in the form of dialog options!

Different Types of Dialogs

So far we've taken a look at just one type of dialog in Conversational AI Cloud, but there's actually a total of two different types of dialogs:

• (standard) dialogs, and;
• transactional dialogs

A (standard) dialog is a decision tree that guides users through your conversational content. It helps them get from a broad question, or issue to a more specific answer to resolve their initial question. A dialog can have different paths depending on the options a user selects. On the other hand we have transactional dialogs.

A transactional dialog is how we actively request data from an end-user as part of a process (or transaction). A transactional dialog is a linear flow with a clearly defined starting point, and ending point where at the end of the transactional dialog we've received all the data required to complete any given transaction.

For now we only took a look at (standard) dialogs from a developers point of view, if you want to know more about transactional dialogs, there's a separate guide for that coming soon, so stay tuned!

Next Steps

Now that you've had Your First Conversation and know how to work with dialogs 👏 it's time to dive a bit deeper into other conversational concepts available in Conversational AI Cloud.

Make sure to take a look at the different Concepts in Conversational AI Cloud's API's to see what's possible, or take a look at Getting started with Web Conversations to see what our standard UI modules could mean for you!