Serverless WebViews using Gupshup

Suppose you have a conversational shopping bot that allows your users to buy t-shirts. A typical user would click on the bot, choose size, color, design and other details. The bot then asks your user about delivery date and location and so on. Just before confirming the order, your user changes his mind and wants to select a different color. The user has to then cancel the current flow and restart the entire process via conversation again. This is cumbersome and highlights the a problem with having wholly conversational bots: Text isn't the best option when there are multiple inputs. Having structured messages to get each input doesn't solve the problem of having to re-enter data.

To help bot makers improve the experience for their users, Gupshup has developed Serverless WebViews which are webviews that you can customize and embed within your chatbot to collect data from the user. These Webviews do not explicitly need to be hosted on any server (hence the name “Serverless”) and they serve two main purposes:

1. Entry of multiple input fields
2. Provide a richer browsing experience

This guide will illustrate how you can create a custom Serverless WebView using the Gupshup Form Builder API and embed it within your chatbot. You can embed the webview within a chatbot on Facebook Messenger. These are the input fields that you can use in a Serverless WebView:

• Text box
• Drop down
• Radio button
• Check box
• Date
• Time
• TextArea

Gupshup Form Builder API

First you'll have to create a form using the Gupshup Form Builder API.

Go to gupshup.io, hover to 'Developers' Tab and click on 'API'. Once redirected to APIs page, click on the 'Form Builder' section. You will use the /facebook/smartmsg/form/create API to build a form. This is a POST request and to create a form you will have to specify the fields of the form in a JSON.

Here's a description of the JSON:

Serverless webviews using Facebook API

Here's a sample JSON:

{
    "title": "This is a test.",
    "autoClose": false,
    "message": "Thank You",
    "callback-url": "https://www.gupshup.io/developer/bot/{botName}/public",
    "fields": [{
        "type": "fbid",
        "name": "fbname",
        "label": "fbName"
    }, {
        "type": "input",
        "name": "name",
        "label": "Name",
        "validations": [{
            "regex": "^[A-Z a-z]+$",
            "msg": "Only alphabets are allowed in this field"
        }, {
            "regex": "^[A-Z a-z]{6,}$",
            "msg": "Minimum 6 characters required"
        }]
    }, {
        "type": "radio",
        "name": "gender",
        "label": "Gender",
        "options": [
            "Male",
            "Female"
        ],
        "validations": [{
            "regex": "",
            "msg": ""
        }]
    }, {
        "type": "select",
        "name": "account",
        "label": "AccountType",
        "options": [
            "current",
            "savings"
        ],
        "validations": [{
            "regex": "",
            "msg": ""
        }]
    }, {
        "type": "checkbox",
        "name": "interest",
        "label": "Interests",
        "options": [
            "Cooking",
            "Reading"
        ],
        "validations": [{
            "regex": "",
            "msg": ""
        }]
    }],
    "users": [
        "Testing"
    ]
}

You can copy the sample JSON replacing {botName} with the name of your bot, in the callback URL field and use the Form Builder API to create a new form. You can also create your custom form JSON. If all goes well you will get a sample response like this:

[
  {
    "embedlink": "https://smapi.gupshup.io/sm/api/facebook/smartmsg/embed/786d48b1-xxx-4ebf-9fe1-998393fadab4",
    "expired": false,
    "fb-button": {
      "messenger_extensions": true,
      "title": "This is a test.",
      "type": "web_url",
      "url": "https://smapi.gupshup.io/sm/api/facebook/smartmsg/embed/786d48b1-xxxx-4ebf-9fe1-998393fadab4",
      "webview_height_ratio": "tall"
    },
    "id": "786d48b1-xxxx-4ebf-9fe1-998393fadab4",
    "signed-for": {
      "display": "Testing",
      "subdisplay": "Testing"
    },
    "smid": "4436"
  }
]

Here 'embedlink' contains the link to the form that is created.
Webview_height_ratio refers to the size of the webview. It comes in three sizes - compact, tall and full.

Embedding the form

In our example above, we have specified the endpoint of the bot as the callback URL. For more details about handling the HTTP endpoints of a bot read this. Thus the user's response is handled in the HttpEndpointHandler() method. The user input is stored in the event.params.payload parameter. Use this parameter to extract out all the fields of the form that you have created and store it into a database.

In your HttpEndpointHandler() add this code snippet:

function HttpEndpointHandler(context, event) {
    formId = event.params.linkId;
    var userDetails = event.params.payload;
    for(var i=0; i < userDetails.length; i++)
    {
        if(userDetails[i]["fieldname"]=='name')
        {
            name = userDetails[i]["fieldvalue"];
            continue;
        }else if(userDetails[i]["fieldname"]=='account')
        {
            account = userDetails[i]["fieldvalue"];
            continue;
        }else if(userDetails[i]["fieldname"]=='gender')
        {
            gender = userDetails[i]["fieldvalue"];
            continue;
        }else
        {
            interests = userDetails[i]["fieldvalue"];
        }
    }
    context.simpledb.doGet(formId);
  }

Where 'name', 'account' and 'gender' correspond to the 'name' field of the JSON that we sent as part of the POST request earlier. We use the doGet method to query the database against the 'formId' of the form that was introduced earlier.

Do note that you cannot use a context.sendResponse within the HttpEndpointHandler() method. This is because the sendResponse will be sent to the Serverless Webview created and not the Messenger session that is in use.

In your DbGetHandler() method, we will construct a message using the input from the form. We will then use the Gupshup Send Message API to send this message back to the user.

function DbGetHandler(context, event) {
    var done = null;
    var apikey = '<API KEY>';
    botname = encodeURI(event.botname);
    contextobj = event.dbval;
    apikey = encodeURI(apikey);
    message = encodeURIComponent("Your Details are:\n" +
            "Name: "+ name + "\n" +
            "Gender: "+ gender + "\n" +
            "Account Type: "+ account + "\n" +
            "Interests: "+interests); 
    var url = "https://api.gupshup.io/sm/api/bot/" + botname + "/msg";
    var body = "context=" + contextobj + "&message=" + message;
    var headers = "{\"Accept\": \"application/json\",\"apikey\": \"" + apikey + "\",\"Content-Type\": \"application/x-www-form-urlencoded\"}";
    context.simplehttp.makePost(url, body, JSON.parse(headers), done); 
}

In the above example, the callback URL was the bot itself i.e the user input was sent back to the bot code hosted on Gupshup. You can chose to have an external callback as well. For example, we can use a Request Bin as a callback URL. Just modify the JSON that you are sending as part of the POST call.

{

    "title": "This is a test.",
    "autoClose": false,
    "message": "Thank You",
    "callback-url": "requestb.in/1i5oasr1?,
    "fields": [{
        "type": "fbid",
        "name": "fbname",
        "label": "fbName"
    }, {
        "type": "input",
        "name": "name",
        "label": "Name",
        "validations": [{
            "regex": "^[A-Z a-z]+$",
            "msg": "Only alphabets are allowed in this field"
        }, {
            "regex": "^[A-Z a-z]{6,}$",
            "msg": "Minimum 6 characters required"
        }]
    }, {
        "type": "radio",
        "name": "gender",
        "label": "Gender",
        "options": [
            "Male",
            "Female"
        ],
        "validations": [{
            "regex": "",
            "msg": ""
        }]
    }, {
        "type": "select",
        "name": "account",
        "label": "AccountType",
        "options": [
            "current",
            "savings"
        ],
        "validations": [{
            "regex": "",
            "msg": ""
        }]
    }, {
        "type": "checkbox",
        "name": "interest",
        "label": "Interests",
        "options": [
            "Cooking",
            "Reading"
        ],
        "validations": [{
            "regex": "",
            "msg": ""
        }]
    }],
    "users": [
        "Testing"
    ]
}

The sample URL for a callback looks like this:

{
    "linkId": "f42414e2-ce1a-xxx-b40a-e88e4d4d9aee",
    "payload": [{
                  "fieldname": "name",
                  "fieldvalue": "Alice"
               },{
                   "fieldname": "gender",
                   "fieldvalue": "Male"
               },{
                   "fieldname": "account",
                   "fieldvalue": "savings"
               },{
                   "fieldname": "interest",
                   "fieldvalue": "Cooking"
               }],
    "time": 1479904354249,
    "userid": "UserID"
}

Messenger Extensions

Like the name suggests, Facebook Messenger Extensions allow you to add functionality to your user's Messenger experience. With Extensions you can get information on the user, accept payments, auto-close webViews, make your bot viral with sharing, and deeply integrate with Messenger's UI.

To use Messenger Extensions in your bot, you must first whitelist the domain the webView is served from. Gupshup has an API to help you do this:

POST /sm/api/facebook/smartmsg/messenger/extension/enable

pageAccessToken= {FB page access token}

You can view this API here. The pageAccessToken can be obtained only once a FB App and FB page has been created.

Enabling auto-close

Facebook has a feature which closes the webView after a transaction is complete or the form is filled. To enable this, first whitelist the domain using the API mentioned above.
Then in the JSON used to construct your form, change the 'autoClose' parameter to 'true'.