Overview

In this guided tutorial you will learn how to create a bot on the RingCentral Glip messaging platform. The guide is broken up into three sections:

1. Learn how to setup, configure and add a bot to Glip.
2. Walk-through the code that powers this bot and others you might want to create.
3. Take on challenges to augment the bot with new behavior.

When you are finished, you will be able to apply what you have learned, and this bot framework to build your own bots that can be used by anyone on the RingCentral platform.

Prepare Your Environment

Before you begin building anything, let's get your local development environment setup with everything you need.

Install Server Components

Let's begin by installing the various software and server components required to host this bot. Please download and install the following as necessary:

1. Node (version 8.10 or greater)
2. Yarn (we recommend you use the --without-node flag when installing)

Clone Repository

Next, let's download and setup the bot code. Run the following commands:

git clone git@github.com:ringcentral-tutorials/ringcentral-ai-bot.git

Or, as needed:

git clone https://github.com/ringcentral-tutorials/ringcentral-ai-bot.git

Then, after the repository is cloned, install the necessary prerequisites:

cd ringcentral-ai-bot
yarn

Sign-up for Google Cloud APIs

Note If you want to see how it work quickly, you do can skip this part, bot will still work, just with fake demo data.

This demo relies on Google's Cloud Speech API for transcription, and its Natural Language API for analysis. This will require you to create and activate a Google Cloud API account, and download access credentials to your local machine.

Accounts are free, and to access the APIs required by this guide you will need to enter in a valid credit card. Your credit card will not be charged unless you manually upgrade to a paid account.

Google will prompt you to download your GOOGLE_APPLICATION_CREDENTIALS file. Save this file as google_cloud.json and save it to the root of the git repository you cloned above.

Setup Your Proxy

Open a terminal window and navigate to ringcentral-ai-bot. Then run the following command to open up a public tunnel to your local development environment:

yarn proxy

Running this command will launch ngrok and display to you on the screen the ngrok URL to which requests can be sent. Make note of the HTTPS URL displayed in your terminal. It will look something like this:

Forwarding        https://1234abcd.ngrok.io -> localhost:7867

Create Your Apps

Next, we need to login to developers.ringcentral.com and create the two apps utilized by this framework to host a bot. Below you will be guided through the process of:

• Creating two apps, one for the bot, and the second for the web-based authorization flow for users to grant the bot access to their voicemail.
• Adding your bot to Glip.

Create Your Bot App

The first app you will create is the Bot App. Create an app using the parameters and values below. Be careful during this process as some of these parameters cannot be edited once the app is created.

• General Settings
  • Choose a name and description you prefer.
• App Type and Platform
  • Application Type: Public
  • Platform Type: Server/Bot
  • Carrier: accept the default values
• OAuth Settings
  • Permissions Needed: All of them (ReadContacts, ReadMessages, ReadPresence, Contacts, ReadAccounts, SMS, InternalMessages, ReadCallLog, ReadCallRecording, WebhookSubscriptions, Glip)
  • OAuth Redirect URI: Using your ngrok HTTPS URL from above, enter in the following value: https://1234abcd.ngrok.io/oauth-bot

If you experience any trouble, or would like additional help with setting up the bot app, watch this youtube video of detailed walk through.

When you are done, you will be taken the app's dashboard. Make note of the app's Client ID and Client Secret as we will use those values when editing the config file later.

Create Your Browser App

The second app is utilized by the framework to give end users the ability to authorize the bot to access their personal account data in RingCentral. Create an app using the parameters and values below:

• General Settings
  • Choose a name and description you prefer.
• App Type and Platform
  • Application Type: Public
  • Platform Type: Browser-based
  • Carrier: accept the default values
• OAuth Settings
  • Permissions Needed: All of them (ReadContacts, ReadMessages, ReadPresence, Contacts, ReadAccounts, SMS, InternalMessages, ReadCallLog, ReadCallRecording, WebhookSubscriptions, Glip)
  • OAuth Redirect URI: Using your ngrok HTTPS URL from above, enter in the following value: https://1234abcd.ngrok.io/oauth-user

If you experience any trouble, or would like additional help with setting up the user app, watch this youtube video of detailed walk through.

When you are done, you will be taken the app's dashboard. Make note of the app's Client ID and Client Secret as we will use those values when editing the config file later.

Start Your Server

Edit Your Config File

With your apps created, we complete the setup process by editing your config parameters and then start the servers. Begin by creating and editing your config file. Open another terminal window, and run the following commands:

cd ringcentral-ai-bot
cp .sample.env .env

Edit the .env you just created, and set the following parameters according the values you made note of above:

• RINGCENTRAL_BOT_CLIENT_ID
• RINGCENTRAL_BOT_CLIENT_SECRET
• RINGCENTRAL_USER_CLIENT_ID
• RINGCENTRAL_USER_CLIENT_SECRET
• GOOGLE_APPLICATION_CREDENTIALS

For the Google credentials, enter in the path to the google_cloud.json file you downloaded and saved earlier, or leave empty, then bot will use fake demo data to demo the process.

Start the Server

We are almost done. Next, start your bot and web server by running the following command:

yarn dev

Add the Bot to Glip

As the last step, we need to add your bot as a user in the Glip messaging interface.

1. Login to developers.ringcentral.com
2. Click the Apps tab, and then click your bot app
3. From the App dashboard, select the "Bot" tab
4. Under General Settings, select "Add to Glip"

Clicking "Add to Glip" will initiate the authorization flow between Glip and your bot. If successful, the "Add to Glip" button will change to a "Remove" button. If you experience trouble with this step, consult the server's console log, and your ngrok proxy (load http://localhost:4040 in your browser) for details that will help you troubleshoot the issue.

Test Your Bot

Everything should now be setup properly. To speak to your bot, login to https://glip-app.devtest.ringcentral.com, and click the bot's name from People list to open up a conversation with the bot.

After that, just follow the bot's prompts and have fun. If everything is working properly the chat will look something like this:

Code Walk-through

Now that you have the bot working properly, let's take a brief tour of the various components of the bot framework that powers it. In this section you will take a closer look at:

• Bot Authentication
• Subscribing to Bot Events
• Responding to Bot Webhooks
• Posting a Bot Message
• User Authorization of the Bot
• Subscribing to Voicemail Events
• Responding to User Webhooks
• Processing Incoming Voicemails

Bot Authentication

When a developer clicks the "Add to Glip" button, this triggers RingCentral to transmit to the bot via it's OAuth Redirect URI the access token it will need when making API calls to RingCentral. You can monitor this exchange by opening up your ngrok web-based console. The framework handles the standard OAuth flow for you. Let's take a closer look.

The request is routed to bot-oauth.js where the bot it instantiated and the temporary auth token is passed into the authorize() method. The authorize() method then passes the auth token back to RingCentral to obtain a permanent access token for the bot. This access token is then saved locally so that it is persisted between server restarts.

If the developer clicks the "Remove Bot" button, the access token is invalidated. If the developer clicks "Add to Glip" again, an entirely new access token is granted.

Whenever a new access token is provisioned to the bot, we must call bot.renewWebhooks() to resubscribe to the bot events that power our bot.

We will use the code(event.queryStringParameters.code) provided by the request to do authorize, and store the fetched accessToken/user id etc to database. Those events are:

• When a user adds the bot to a chat group
• When a message is posted in chat group

We will dive into how we subscribe to these events next.

Subscribing to Bot Events

When you subscribe to an event, you need to provide RingCentral with the following:

1. The list of events to subscribe to
2. How to deliver the event, e.g. the URL to post the event to
3. How long the subscription will last

Subscriptions are bound to the access token that created them. Since a bot's access token never expires, it stands to reason that your subscriptions should never expire as well. That is why we set expiresIn to such a large value.

We instruct RingCentral to notify us of events via a "webhook" and to post the webhook to a URL we specify.

You specify the events you want to subscribe to through an array of event names or "filters."

const botEventFilters = () => [
  '/restapi/v1.0/glip/posts',
  '/restapi/v1.0/glip/groups'
]

If an error occurs subscribing to the event, the bot framework will attempt to resubscribe again in one minute.

Next we will show how to receive an event notification and respond to it.

Responding to Bot Webhooks

With the subscription setup, now our server will receive an HTTP POST whenever a user performs the following actions:

• A user adds the bot to a chat group
• A message is posted in the chat group

The event is routed to bot-webhook.js for processing. A switch statement is used to identify the type of event received, and then to determine on a case-by-case basis what is the proper response to send back to the user.

Next we will show how to post a message back to the user.

Posting a Bot Message

Your bot could be interacting with any number of user simultaneously, so we need a way to identify the specific user to direct messages to. This is done through the groupId which identifies the specific conversation taking place between a user and the bot. We will therefore POST our response to the following URL:

/restapi/v1.0/glip/groups/{groupId}/posts

The framework will handle for you authorization, which is done by setting the HTTP Authorization header properly to "Bearer" plus the access token value.

More information on the API is available here:

• Create Post API

This bot requires a user to grant the bot permission to access their voicemail. Next, we will review how this authorization flow is enabled.

User Authorization of the Bot (step 1)

When we clicked "Add bot to Glip" we gave the bot permission to access our Glip organization and be notified of messages posted to it. But to fully-enable this use case, the bot need to ask each individual user to speaks with permission to access their personal voice mails. This is done by a distinct OAuth authorization flow handled by the bot framework.

To do that, we prompt the user via a bot message to visit a URL to grant the bot the permission it needs. The code to the right helps us construct this URL.

Next, we will send it to the user when necessary.

User Authorization of the Bot (step 2)

When the user clicks the authorization URL, they will be directed to their web browser where they can authorize the bot through a stand OAuth flow.

Similar to bot authorization process, RingCentral posts to us a temporary auth token which we exchange for a permanent access token, which we then store locally. This token can subsequently be used to subscribe to voicemail events and access the user's account on their behalf.

Next, we will subscribe to voicemail events.

Subscribing to Voicemail Events

The process and API for subscribing to Voicemail events is the same as subscription to Glip events.

We will subscribe to these event filters:

[
  '/restapi/v1.0/account/~/extension/~/message-store',
  '/restapi/v1.0/subscription/~?threshold=59&interval=15'
]

• The message-store event will be triggered when a new voicemail is received.
• The /restapi/v1.0/subscription/~?threshold=59&interval=15 event will be triggered whenever the message-store event is about to expire. This ensures that as long as the bot is running, we will continually renew our subscription to voicemail events. In the event that the bot server is taken down, then the subscription will be permitted to expire gracefully.

Learn more about reminder hooks from RingCentral's github repository.

Next, we will see how to respond to a voicemail event.

Responding to User Webhooks

Voicemail events are processed in a similar fashion to Glip events. Events received by the framework are routed to user-webhook.js. Here we identify the event received and handle each one accordingly. You can see for example how we distinctly handle two different events we have subscribed to:

• subscription expiration
• new voicemail received

As you work to expand the capabilities of your bot, this is how you might handle other events emitted by RingCentral.

Next, we will process the voicemail.