Documentation

Your First Conversation

How to have your first conversation through Conversational AI Cloud's Gateway API

Suggest Edits

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

Introduction

Conversational AI Cloud is a Conversational AI Platform that makes it easy to have a conversation with your customers. In order to have a basic conversation we offer a single API called our Gateway API. There’s also other API’s like the Context Store API, or our web hook based integrations, but those generally come into play whenever customers are looking to create a more personalised and integrated conversation.

In this guide we’ll be relying on the Gateway API to send in questions, and receive answers (also called an interaction), and to manage our conversation through what is called a session. We’ll be looking at the response models, and looking at the most important parts of the response in order to get started with our API(s).

📘

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

Any code examples in this guide are written in Node, but feel free to code along in any language you prefer.

Your first message

Sending a message to the Conversational AI Cloud means calling the /ask endpoint on the Gateway API.

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: 'Hello! How are you doing?'
  }
  headers: {
  	Accept: 'application/json, standard'
	}
};

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

The above request is a simple example of a GET request. Submitting this request will provide us with the following response object:

{
  "outputs": [
    {
      "outputId": 0,
      "kbaId": 272,
      "interactionValue": "Hello! How are you doing?",
      "isDefault": true,
      "dimensionValues": [],
      "outputParts": [
        {
          "type": "answer",
          "text": "I'm doing great! Is there anything I can help you with today?",
          "links": [],
          "projectConstants": [],
          "dialogOptions": [],
          "metadata": {},
          "images": [],
          "videos": []
        }
      ],
      "kbaCategories": []
    }
  ],
  "sessionId": "0d5bf3ad-2f4f-4a57-ab1d-c3b20f229e72",
  "interactionId": "e187019a-2b4d-4d33-bbc3-0b465f59c432",
  "culture": "en",
  "inputs": {
    "originalInputText": "Hello! How are you doing?"
  }
}

Inspecting the root of the response object shows us a few key variables:

  • Outputs, an array containing the answer response on the first index.
  • InteractionId, a unique GUID generated for this specific interaction. The interaction ID can be used to provide feedback, or examine the interaction in our analytics environment.
  • SessionId, a unique GUID generated for each new session on the Conversational AI Cloud gateway.

Taking a look at the answer response contained in the outputs array provides us with the following: 

{
  "outputId": 0,
  "kbaId": 272,
  "interactionValue": "Hello! How are you doing?",
  "isDefault": true,
  "dimensionValues": [],
  "outputParts": [
  {
    "type": "answer",
    "text": "I'm doing great! Is there anything I can help you with today?",
    "links": [],
    "projectConstants": [],
    "dialogOptions": [],
    "metadata": {},
    "images": [],
    "videos": []
  }],
  "kbaCategories": []
}

We can see that the answer object contains a number of properties, most of which we won’t get into in this article. A few topics are particularly important when getting started with Conversational AI Cloud:

  • interactionValue, the original question we sent in to the Gateway
  • outputParts, the object containing the actual answer text along with any additional properties such as media, links, and dialog options

And last, but not least. If we look specifically at the outputParts section we get:

{
  "type": "answer",
  "text": "I'm doing great! Is there anything I can help you with today?",
  "links": [],
  "projectConstants": [],
  "dialogOptions": [],
  "metadata": {},
  "images": [],
  "videos": []
}

We see that the outputParts section consists of the following properties:

  • type, the type of response (always set to ‘answer’)
  • text, the answer text containing the response
  • links, images, videos: arrays of objects containing information on the specific media type or link.
    • Each media type has a different format, the ID in the object is referenced in the replacement tag when present in the response (see the “replacement tag” section of this article).
  • projectConstants, all project constants present in the answer text (pre-replaced)
  • dialogOptions, any dialog options defined in the CMS content for this answer
  • metadata, any values added to the answer that can be used by the caller to further process the request

Continuing the conversation

Now that we’ve sent our first message through the Gateway API, it's time for us to continue the conversation. Whenever a single interaction is sent to the Gateway API, it generates an interaction ID (learn more about interactions here), and a session ID (learn more about sessions here). These ID’s are used to both continue the conversation (session ID), or to look up a specific interaction in Conversational AI Cloud’s analytics environment (interaction ID).

For this section of the guide we’ll be looking specifically at continuing the conversation using through the session ID. As stated before, a unique session ID is generated for any interaction without a session ID, or for any interaction with an expired session ID. A session in Conversational AI Cloud is:

  • Unique to each customer-project-culture combination
  • Valid for a period of 15 minutes, or 24 hours.
  • A way to group individual interactions together into a conversation
  • A container for any information that you want to keep in the session in order to personalise and optimise interactions to better serve your end-users.

Sessions are required for more extensive interactions with the Gateway API like (transactional) dialogs. Continuing a conversation through sessions is as easy as providing the session ID provided in the response from one interaction, as a query parameter for the next interaction:

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: 'Can you help me with returning my order?',
    // Here we include the session ID returned from a previous interaction
    'session.id': '0d5bf3ad-2f4f-4a57-ab1d-c3b20f229e72'
  }
  headers: {
  	Accept: 'application/json, standard'
	}
};

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

All we did to carry on the conversation within the session that was generated for us is include the ‘session.id’ query parameter. This is enough for Conversational AI Cloud to process the interaction in the scope of the session. If the provided session ID has expired, a new session will be generated (linked to the previous session) and returned in the output.

Next steps

In this guide we took a look at the /ask endpoint on the Gateway API. We sent in two interactions, the first one generating a new session, and the second interaction picking up the conversation through the use of the session id parameter. By taking those two steps, we essentially have the basics of a conversation between your end-users and Conversational AI Cloud!

Of course there's a lot of other Conversational AI Cloud features you could integrate it! Make sure to take a look at some of our other articles that explain core concepts like events, dialogs, and context to learn more about how to get started with CM.com's Conversational AI Cloud!

Updated 7 months ago