botbuilder-location-v2

Location Control for Microsoft Bot Framework

Overview

Use Google Maps and Bing Maps API to collect and validate the user's location with your Microsoft Bot Framework bot in Node.js. Google Maps validates the location based on the user's input utterance, and Bing Maps generates the static images.

Note that this is a fork from botbuilder-location, which uses Bing Maps API.

Prerequisites

To start using the control, you need to obtain a Bing Maps API subscription key and a Google places API key. You can sign up to get a free Bing Maps key with up to 10,000 transactions per month in Azure Portal.

You can find out how to sign up to get a free Google places API key here.

Code Highlights

Installation

Install the botbuilder-location module using npm.

npm install --save botbuilder-location-v2

Usage

Add the botbuilder-location-v2 library to your bot.

var locationDialog = require('botbuilder-location-v2');
bot.library(locationDialog.createLibrary(process.env.BING_MAPS_API_KEY, process.env.GOOGLE_MAPS_API_KEY));

Add a .env file containing the BING_MAPS_API_KEY and GOOGLE_MAPS_API_KEY variables.

Calling the location control with default parameters

The example initiates the location control with default parameters, which returns a custom prompt message asking the user to provide an address.

locationDialog.getLocation(session,
 { prompt: "Where should I ship your order? Type or say an address." });

Using FB Messenger's location picker GUI dialog

FB Messenger supports a location picker GUI dialog to let the user select an address. If you prefer to use FB Messenger's native dialog, pass the useNativeControl: true option.

var options = {
    prompt: "Where should I ship your order? Type or say an address.",
    useNativeControl: true
};
locationDialog.getLocation(session, options);

Handling returned location

The following example shows how you can leverage the location object returned by the location control in your bot code.

locationDialog.create(bot);
 
bot.library(locationDialog.createLibrary(process.env.BING_MAPS_API_KEY, process.env.GOOGLE_MAPS_API_KEY));
 
bot.dialog("/", [
    function (session) {
        locationDialog.getLocation(session, {
            prompt: "Where should I ship your order? Type or say an address."
        });
    },
    function (session, results) {
        if (results.response) {
            var place = results.response;
            session.send(place.streetAddress);
        }
        else {
            session.send("OK, I won't be shipping it");
        }
    }
]);

More Information

Read these resources for more information about the Microsoft Bot Framework, Bot Builder SDK and Bing Maps REST Services:

• Microsoft Bot Framework Overview
• Microsoft Bot Framework Bot Builder SDK
• Microsoft Bot Framework Samples
• Bing Maps REST Services Documentation