Build a RingCentral Bot Using Node

Last updated: 2020-10-08 Contributors Byrne ReesePaco Vu
Edit this page

This guide will take you through the process of building your first bot using RingCentral's Javascript Bot Framework. Let's begin!

Setup Your Project

To begin, create a project directory and install some prerequisites.

$ mkdir my-bot
$ cd my-bot
$ yarn add ringcentral-chatbot sqlite3
$ yarn add --dev dotenv ngrok

Start a Proxy

Bots operate via a server which RingCentral communicates with. To allow RingCentral to send messages to your bot, we need to setup a proxy/tunnel first.

$ ./node_modules/.bin/ngrok http 3000

When the proxy has started, you will see a screen on which is a URL you will need to make note of.

Create an App

With our proxy running, we now have all the information we need to create an app in the RingCentral Developer Portal. This can be done quickly by clicking the "Create Chat Bot App" button below. Just click the button, enter a name and description if you choose, and click the "Create" button. If you do not yet have a RingCentral account, you will be prompted to create one.

Create Chat Bot App

  1. Login or create an account if you have not done so already.
  2. Go to Console/Apps and click 'Create App' button.
  3. Select "Bot App for Team Messaging" under "What type of app are you creating?"
  4. Select "Other Non-UI" under "Where will you be calling the API from?"
  5. Select "Only members of my organization/company" under "Who will be authorized to access your app?"
  6. On the second page of the create app wizard, enter your app's name and description. Then select the following permissions:
    • Glip
    • Webhook Subscriptions
    • Edit Extensions
  7. Leave "OAuth Redirect URI" blank for now. We will come back and edit that later.

Enter your Redirect URI

Upon clicking the Create Bot App button, you will be taken to a form to complete the app creation process. Be sure to enter in the Redirect URI using the address of your proxy.

When you are done, you will be taken to the app's dashboard. Make note of the Client ID and Client Secret. We will be using those momentarily.

Edit .env

Create a file called .env in your project folder. Then copy and paste the contents below. Be sure to add/substitute values accordingly.


Initialize Your Database

Bots need to be stateful in order to maintain webhook and notification subscriptions, and other information. In this guide we use sqlite3, which must first be initialized. Edit your .env and set the connection URI to a full path to a file called db.sqlite in your project directory.


Then use the bot framework to setup your database.

$ curl -X PUT -u admin:admin https://<CHATBOT_SERVER>/admin/setup-database

Create Your Bot

We are now ready for the code to power your bot. Create a file called express.js in your project folder using the contents below.

const createApp = require('ringcentral-chatbot/dist/apps').default

const handle = async event => {
  const { type, text, group, bot } = event
  if (type === 'Message4Bot' && text === 'ping') {
    await bot.sendMessage(, { text: 'pong' })
const app = createApp(handle)

Start Your Bot Server

$ node -r dotenv/config express.js

Add Your Bot to RingCentral

Login to your Developer Console, click on your bot in the application listing, and navigate to the Bot tab. Then click the button labeled "Add to Glip."

Then follow the on-screen instructions.

Test Your Bot

Your bot will appear as a user inside of the RingCentral App. Login to the RingCentral Team Messaging sandbox and start a chat with the bot app you just added.

Type "ping" and see what happens.

Publish Your App

Congratulations on creating your first RingCentral application. The last step is to publish your application. We recommend going through this process for your first application so you can understand the steps to take in the future, but also to come to appreciate the care taken by RingCentral to ensure that only high-quality apps are allowed into our production environment.