How to build a RingCentral bot using Javascript

Last updated: 2021-06-02 Contributors EdwardByrne ReesePaco Vu
Edit this page

A RingCentral Team Messaging bot provides a conversational interface for performing common tasks. In this guide, you will learn how to setup one of the simplest possible bots to introduce you to the development process using the RingCentral Javascript bot framework. The bot you will create is a a ping-pong bot.

The RingCentral Javascript bot framework simplifies much of the process of creating a bot, and will help you devote more of your time to the conversational interface that powers your bot's interactions.

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
% touch db.sqlite

Start a Proxy

Bots operate via a server which RingCentral communicates with over HTTP. To enable RingCentral to send messages to the bot you are building on your local development machine, we need to setup a proxy/tunnel first.

$ ./node_modules/.bin/ngrok http 3000

When the proxy has started, you will see something similar to the following:

Make note of the https forwarding URL, we will use that later when configuring your bot.

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 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 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 "Only members of my organization/company" under "Who will be authorized to access your app?"
  5. On the second page of the create app wizard, enter your app's name and description. Then select the following permissions:
    • Edit Extensions
    • Glip
    • Read Accounts
    • Webhook Subscriptions

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, with /bot/oauth appended to the end. For example:

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

Create and 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.


Configuring your database

In a subsequent step we will be initializing a simple SQLite database. Before we can do that, we need to tell the bot framework where to find your database file. When you setup your project directory above, you touched a file called db.sqlite. In your .env file, enter the full and complete path to that file. The URL will look like this (the three forward slashed "///" is intentional):


Create your bot server

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 === 'TextMessage' && text === 'ping') {
    await bot.sendMessage(, { text: 'pong' })
const app = createApp(handle)

Start your bot server

The code above is all you need to create a simple RingCentral bot. Let's start your bot server.

$ node -r dotenv/config express.js

Initialize your database

With your bot server running, let's continue the setup process by initializing your database. This is done by calling a URL running on your bot server like so:

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

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 RingCentral."

Then follow the on-screen instructions and pick a name for your bot.

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. If successful, the bot should respond simply with "pong."

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.