Context Variable Webhook

In this article we'll introduce the concept of the context variable webhook in Conversational AI Cloud and what it means for a developer to work with.

Introduction

The context variable webhook is used to evaluate the context of each individual interaction. It is triggered only when Conversational AI Cloud's recognition matches an article (Q&A), events, or dialog (node) that contains contextual answers. Context is not kept between interactions.

🚧

Allowed Values

Each context variable comes with a set of allowed values (defined in the Conv. AI Cloud CMS). Any value set in the context variable webhook that is not pre-defined in the allowed values will cause the default answer to be returned, and context to be ignored for that specific interaction.

Use Cases

The main use cases that the context variable webhook introduces is dynamic conversation context based on the state of the conversation (stored in conversation variables). It achieves this by:

• Calling the context variable webhook for each interaction that contains a contextual answer in the matched answer set.
• Providing the session in the request body (consisting of conversation variables)

An example of the request body for a context variable webhook could look like this:

JSON

{
     "session": {
          "conversation_variable_first_name": "Jon",
          "conversation_variable_last_name": "Snow",
          "conversation_variable_is_logged_in": "true"
     },
     "input": {
          "type": "qa",
          "value": "I want to cancel my order",
          "normalizedValue": "i want to cancel my order"
     },
     "contextVariables": [
          {
               "allowedValues": [
                    "yes",
                    "no"
               ],
               "key": "isLoggedIn",
               "value": "yes"
          }
     ],
     "request": {
          "queryParams": [
               {
                    "key": "value"
               }
          ],
          "location": "https://www.cm.com"
     },
     "sessionId": "00000000-0000-0000-000000000000",
     "culture": "en",
     "correlationId": "00000000-0000-0000-000000000000"
}

The response of the webhook requires each context variable to be returned, along with a set value. What this value is doesn't matter as long as it is one of the allowed values provided in the request body. An example response:

JSON

{
  "contextVariables": [
    {
      "key": "isLoggedIn",
      "value": "true"
    }
  ]
}

Best Practices

When working with the context variable webhook its important to keep a few things into account:

• The session (containing all conversation variables) is provided in the request body, and can be used to evaluate context variables.
• To keep implementations simple, make sure that context variables and conversation variables related to each other are named identical, this makes it easy to look up the value of a conversation variable in the session for a given context variable.
• Make sure to return all context variables in your response, leaving 1 value out will be considered an invalid response.
• Make sure to only set a context variable to a value that is provided in the "allowedValues" array in the request body, any value set that is not provided in the "allowedValues" will cause the entire response to be considered an invalid response.
• If the response is considered invalid, the default answer is always returned and context is ignored for that specific interaction.