Building a bot outside Bot Builder tool.

Gupshup allows you to write the bot code outside Gupshup's Bot Builder tool in any programming language of your choice.You can then associate a callback to the bot on Gupshup's platform.This callback will be the location of your bot code on the server where you have hosted the code. Whenever the bot is called by the user, Gupshup will send the relevant details to your bot through the callback URL using which you can respond back to the user.

Let's see how this can be achieved through an example using Java as the programming language.

Follow these steps below to build, deploy and test a weatherbot that responds to user's query about the weather in any city :

1.  Create a bot on Gupshup platform - Go to My Bots section and then click on the '+' sign on the bottom right and give a name to the bot.

2.  Write the bot's code in your IDE -
When a user interacts with the bot a GET call is made to the callback URL with additional parameters.The below table illustrates all the parameters which are sent to the bot.

Now handle these in your code to define your bot logic. For Java let's create a Java Servlet.

Pseudo code -

protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException 
{
    String contextobj = request.getParameter("contextobj");
    String senderobj = request.getParameter("senderobj");
    String messageobj = request.getParameter("messageobj");
}

When you map your bot to the Proxy Bot for testing, a “botmappedevent” event is triggered. You can read more about Proxy Bots here. So you should handle this event to send a text to the user asking him/her to enter the city or you can also send this text if someone says 'Hi' to your bot.

Pseudo code -

JSONObject messageobjObj = JSONObject(messageobj); 
String conversationType = messageobjObj.getString("type");
String message = messageobjObj.getString("text");
if((conversationType.equalsIgnoreCase("event")&&   message.equalsIgnoreCase("botmappedevent"))|| (message.equalsIgnoreCase("hi")) )
{
  response.setContentType("text/html");
  PrintWriter out = response.getWriter();
  out.print("Enter the city name");
  out.flush();
  out.close();
}

Once user provides the city name, call an external API to get the weather details

Pseudo code -

JSONObject messageobjObj = JSONObject(messageobj)
String conversationType = messageobjObj.getString("type");
String cityName = messageobjObj.getString("text");
if(conversationType.equalsIgnoreCase("msg"))
{
  String URL = "https://api.worldweatheronline.com/free/v2/weather.ashx?q="+cityName+"&format=json&num_of_days=1&key={Your apikey}";

  okhttp3.OkHttpClient client = new okhttp3.OkHttpClient();
  okhttp3.Request request = new okhttp3.Request.Builder()
                              .url(URL)
                              .get()
                              .build();
  okhttp3.Response response = client.newCall(request).execute();
}

In the example we have used the API of World Weather Online but you can choose any other API available. The apikey for this API is provide by World Weather Online after registration.

Once you have the response from the external API you can send the message to the user. There are two ways to do so -

  a.  Immediate response - In this you return a HTTP response back to the callback without any delay.

Pseudo code -

response.setContentType("text/html"); 
PrintWriter out = response.getWriter();
out.print("Weather in"+cityName+" is -"+responseofWeatherAPI);
out.flush();
out.close();

  b.  Delayed response - In this you can use the Gupshup send message API. For details please read this guide.

Pseudo code -

String botname = "weatherbot";
String botmessage = "Weather in"+cityName+" is -"+responseofWeatherAPI";
String URL = "http://api.gupshup.io/sm/api/bot/weatherbot/msg";
String body = "apikey={Your Gupshup API key}&botname="+botname+"&context="+contextobj+"&message="+botmessage;
okhttp3.OkHttpClient client = new okhttp3.OkHttpClient();
okhttp3.MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType,body);
okhttp3.Request request = new okhttp3.Request.Builder()
                           .url(URL)
                           .post(body)
                           .build();
okhttp3.Response response = client.newCall(request).execute();

Once your code is ready, run it on the local server.

3.  Deploy locally and associate the callback - To deploy the bot locally and associate the callback please read this guide

4.  Testing your bot - You can test your bot either using the Proxy Bots or you can publish your bot to the specific messaging channel and test.

Testing flow for the bot which we have built above -

    1.  Mapping the bot to Proxy Bot and getting the help text for the mapping event.

    2.  Entering the city name and getting the result.

Here is a sample code