Bot Context Handler

The bot context handler can be used by the bot creator to engage the bot with the user in a conversational manner. To get started with the context handler, you must define a conversation flow as a context map. The keys that need to be used in the context map are explained in a table below. But before that take a look at the below-given examples where the context handler will come in handy.

1.  A service-desk bot is a good example to understand the working of the bot context handler easily. This bot can be used to handle simple service-desk roles such as handling asset requests, replying to queries and also raise a request for the user. For example, if a user would like to raise a request to install a particular software, the bot can get the necessary information from the user with a series of questions and raise the request! The bot will collect the response to each question before the final action. 
2. You can ask your bot to create a lead for you in CRM or create an issue in Projects and this definitely cannot be done with a single message! Instances like these can be easily handled using the context handler. 

The context map should have the following keys :

Every entry in the params list can have the following attributes:

Sample syntax for params map

"params":[
  {
    "name": "movie",
    "question": "Give me the movie name!"
  },
  {
    "name": "seats",
    "question": "Number of seats?",
    "value": {
      "text": "3"
    }
  },
  {
    "name": "place",
    "question": "This movie is available in the following theatres! Choose an option, for me to proceed.",
    "suggestions": {
      "list": [
        {
          "text": "Regal IMAX"
        },
        {
          "text": "Livermore Cinemas"
        }
      ]
    }
  }
]

The following attributes are passed to the context handler which will be triggered after collecting all the inputs in the params map :

Sample response for the context map

  {  
      "movie":{  
         "text":"Justice League"
      },
      "seats":{  
         "text":"3"
      },
      "place":{  
         "text":"Regal IMAX"
      }
   }

Sample Use Case

Let us consider a hotel bot, which helps the customers with the Wi-Fi password, cab bookings, room service and other related queries. The bot shows a list of options to the user as suggestions and when the user selects an option, moves on to further questions on the topic. The message handler is triggered to show the initial list of suggestions. The responses made by the user are passed to the context handler through the context map, and any further action is performed using the bot context handler. Take a look at the sample code snippet shown below! 

Sample Message Handler Code

response = Map();
if(message.containsIgnoreCase("ROOM SERVICE"))
{
	context = {"id":"Room Service","timeout":"300","params":[{"name":"room service","question":"Great! Here is a list of options for you to choose from.","suggestions": {"list":[{"text":"House Keeping"},{"text":"Maintenance"}]}},{"name":"time","question":"Okay cool. When can I send them over?","suggestions":{"list":[{"text":"Now"},{"text":"In half hour"}]}}, {"name":"confirmation","question": "Please confirm your request once!", "suggestions": {"list":[{"text":"Yes"},{"text":"No"}]}}]};
	response.put("context", context);
}
else if(message.containsIgnoreCase("WIFI"))
{
	context = {"id": "Wifi", "timeout":"300","params":[{"name":"Wi-fi","question":"Confirm if you are in Room 307!", "suggestions":{"list":[{"text":"Yes"},{"text":"No"}]}}]};
	response.put("context",context);
}
else if(message.containsIgnoreCase("CAB"))
{
	context = {"id": "Cab","timeout":"300","params":[{"name":"Cab","question": "When can I book the cab for you?","suggestions":{"list":[{"text":"Now"},{ "text": "After 1 hour"}]}}]};
	response.put("context",context);
}
else
{
	response = {"text": "Hi! I am Lyte, the Room Service Bot. Heres what I can help you with! :happy!:", "suggestions":{"list":[{"text":"Room Service"},{"text":"Wifi"},{"text":"Cab"}]}};
}
return response;

Sample Context Handler Code

response = Map();
info answers;
if(context_id.matches("Room Service"))
{
	confirm = "Please check our other options then!";
	if(answers.get("confirmation").containsIgnoreCase("YES"))
	{
		// Make api calls for the room service options!
		confirm = "Great! I've arranged for the " + answers.get("room service").get("text") + " to be there " + answers.get("time").get("text") + ". :thumbsup:";
	}
	response.put("text",confirm);
}
else if(context_id.matches("Wifi"))
{
	txt = 'Please try again or call 0000 for more information!';
	if(answers.get("Wi-fi").containsIgnoreCase("YES"))
	{
		txt = 'Here is your wifi ID and password. \n ID - Room_307 \n Password - Hotel123';
	}
	response.put("text",txt);
}
else if(context_id.matches("Cab"))
{
	if(answers.containKey("cabconfirm"))
	{
		if(answers.get("cabconfirm").containsIgnoreCase("Yes, Please"))
		{
			txts = 'Your cab has been booked. :smile:';
		}
		else
		{
			txts = 'Umm, try again then!';
		}
		response.put("text",txts);	
		return response;
	}
	if(answers.get("Cab").containsIgnoreCase("Now"))
	{
		book_cab = {"id":"Cab","timeout":"100","params":[{"name":"cabconfirm","question":"There are no cabs to book now. Can I try after 15 mins?","suggestions":{"list":[{"text":"Yes, Please!"},{"text":"No,Thanks!"}]}}]};
		response.put("context",book_cab);
	}
	else
	{
		txt = "Your Cab has been booked. Please meet the driver at the hotel lobby. :thumbsup:";
		response.put("text",txt);
	}
	
}
return response;

Here's how this code gets executed to unfold the conversation between the bot and the user.

Continuation of a conversation in the context handler:

When the handler returns a context, it can be considered in two ways:

• As a new context.  
• Continuation of the existing context.

In case of continuation of the existing context, then all you've to do is use the ID of the context. This context can contain new questions or can act as a checkpoint for questions you might want to confirm once again with the user

A case in point is the movie bot, that can book tickets for the user once it gets the necessary information. The catch here is, this bot can book only up to 5 tickets for the user. So when a user tries to enter an option which is not present in the bot options. The can easily rephrase the question and let the user know the ticket quantity restrictions.  This particular question is rephrased in the context handler. The existing context in the message handler can be continued from the context handler by using the same 'id' param. ("id":"movies") The code snippet is shown below - 

//Map defined in the message handler : 

response = Map();
if(message.containsIgnoreCase("Yes"))
{
	context = {"id":"movies","timeout":"300","params":{{"name":"movie","question":"Please select the movie!","suggestions":{"list":{{"text":"Iron Man"},{"text":"Batman"},{"text":"Justice League"}}}},{"name":"quantity","question":"Awesome. How many tickets do you need?","suggestions":{"list":{{"text":"1"},{"text":"2"},{"text":"3"},{"text":"4"},{"text":"5"}}}}}};
	response.put("context",context);
	response.put("text","Welcome To *Movie Booking* \n Please answer the following questions!");
}
else if(message.containsIgnoreCase("No"))
{
	response.put("text","Oh! But I can help you with only that right now :upset:");
}
else if(message.containsIgnoreCase("OK"))
{
	response.put("text","Great! I'll book the tickets right away!");
}
else
{
	response = {"text":"Hi! Would you like to book a movie?","suggestions":{"list":{{"text":"Yes"},{"text":"No"}}}};
}
return response;

// Map defined in the context handler:

response = Map();
if(context_id.matches("movies"))
{
	ticket_quantity = {"1","2","3","4","5"};
	if(answers.contains("confirm"))
	{
		if(answers.get("confirm").get("text").containsIgnoreCase("yes"))
		{
			text = "Here's the booking details: \n Movie: *" + answers.get("movie").get("text") + "* \n Tickets: *" + answers.get("quantity").get("text") + "* \n Multiplex: *" + answers.get("multiplex").get("text") + "* \n Send an *OK* for me to proceed booking!";
		}
		else
		{
			text = 'Okay then. I will book the tickets. :thumbsup:';
		}
		response.put("text",text);
		return response;
	}
	if(!ticket_quantity.contains(answers.get("quantity").get("text")))
	{
		context = {"id": "movies","timeout":"30","params":[{ "name":"quantity","question":"I am sorry! But you can only choose from the list of options given.","suggestions":{"list":[{"text":"1"},{"text":"2"},{"text":"3"},{"text":"4"},{"text":"5"}]}}]};
	}
	else
	{
		context = {"id":"movies","timeout":"30","params":{{"name":"multiplex","question":"These multiplexes are playing the movie *" + answers.get("movie").get("text") + "*","suggestions":{"list":{{"text":"Regal IMAX"},{"text":"Livermore Cinemas"}}}},{"name":"confirm","question":"Great! You are done. Can you confirm before I proceed?","suggestions":{"list":{{"text":"Yes"},{"text":"Just book!"}}}}}};

	}
	response.put("context", context);
}
else
{
	response = {"text":"Hi! Would you like to book a movie?","suggestions":{"list":{{"text":"Yes"},{"text":"No"}}}};
}
return response;

Below is a GIF illustrating the conversation flow, when the user response is from the list of options for the 'Number of tickets' question.

Now, let's see how the bot reacts when the user's response is not from the list of suggestions for the same question.