How to build a RingCentral bot from scratch

Last updated: 2021-05-25 Contributors Byrne Reese
Edit this page

A RingCentral Team Messaging bot provides a conversational interface for performing common tasks. In this guide, you will learn how to build a simple ping-pong bot from scratch, giving you a closer look at the bot design pattern.

Try the RingCentral bot framework to get up and running faster and with less code.

Before you begin, make sure you have logged into your RingCentral developer account via the RingCentral Developer Console.

Step 1. Start ngrok

Bot servers must be accessible over the open Internet to allow RingCentral to send them messages. When developing a bot locally a tunneling tool like ngrok is useful.

Install ngrok
  • Go to and download the version that corresponds to your platform. In our case, we'll be downloading the Mac OS X 64-bit version.
  • You can extract ngrok into the folder of your preference and run ngrok from there.

Launch ngrok by running the following command:

% ngrok http 3000

If every thing goes well you should see the following screen.

Make note of your https forwarding URL, we will use that shortly when creating your config file.

Step 2. Create a bot application

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.

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:
    • Glip
    • Webhook Subscriptions
    • Edit Extensions
    • Read Accounts

Set your OAuth redirect URL

Before you create your bot app, you will need to set the OAuth redirect URL. Into that URL enter in the ngrok URL from above, with /oauth appended to the end. For example:

Step 3. Clone the sample application

To help you get started, we have a sample application that stubs out much of what you will need to create. Clone this Github repository like so:

% git clone
% cd ringcentral-bot-demo

Step 4. Setup and start the bot server

Ok, the basics are in place. Now it is time to build your bot server using node. The repository you cloned above has all the prerequisites you will need specified in package.json. Install them by running the following command:

% npm install

Next, copy the contents of .env.template to .env.

% cp .env.template .env

Edit the .env you just created and enter in the values for CLIENT_ID and CLIENT_SECRET that you received when you created the bot in the RingCentral Developer Console above. Then, set REDIRECT_HOST to your ngrok server URL. I would look something like this:

Finally, launch your server.

npm start

Return to the Developer Console and navigate to the "Bot" tab for the app you recently created. Click on the "Add to RingCentral" button.

This will install the bot into your Developer Sandbox. When a bot is installed, RingCentral will attempt to verify that the bot server is running by sending it a quick message to the OAuth redirect URI.

At the same time it will transmit auth credentials necessary for making future API calls. RingCentral will transmit an authorization code for public apps, and an access key for private apps.'/oauth', function (req, res) {
    if (req.body.access_token) {
        bot_token = req.body.access_token;
    console.log("Verifying redirect URL for bot server.")

    // This is a bit of a hack. We are bypassing the login() method
    // of the SDK in favor of setting the access key directly.
    // The hack here is to set the refresh token to effectively a null
    // value since it is not transmitted to us.
    // There is probably a more elegant solution for this
    var data = platform.auth().data();
    data.token_type = "bearer"
    data.expires_in = 1000000
    data.access_token = bot_token
    data.refresh_token = 'xxx'
    data.refresh_token_expires_in = 1000000

    // Subscribe to webhooks relating to team messaging posts. This
    // will alert your bot when a message has been posted so the bot
    // can parse the message and respond to it. 
        subscribeToEvents( bot_token );
    // You may wish to store the bot token if you intend to re-use it
    // for other calls to the RingCentral API
    // TODO - store bot_token to make responding to future posts easier
    } else {

The bot provisioner will only use the first URL specificed in the oAuth settings.

The access token obtained is a permanent access token. It's the developer responsibility to manage this access token. For public applications this would mean storing the bot token in a database and mapping to a customerId. They would then use the customerId to retrieve the access token before posting back to RingCentral.

Step 6. Subscribe to webhooks

We can now subscribe to RingCentral events using the code below:

function subscribeToEvents(token){
    console.log("Subscribing to post and group events")
    var requestData = {
        "eventFilters": [
        "deliveryMode": {
            "transportType": "WebHook",
            "address": REDIRECT_HOST + "/callback"
        "expiresIn": 604799
    };'/subscription', requestData)
        .then(function (subscriptionResponse) {
            console.log('Subscription Response: ', subscriptionResponse.json());
            subscription = subscriptionResponse;
            subscriptionId =;
        }).catch(function (e) {
            console.error('There was a problem subscribing to events. ', e);
            throw e;

Step 7. Talk to the bot

Now login to using your sandbox credentials and search for the bot name. Click on the bot name and type in "Hi" to start communicating with it.

Step 8. Receive webhook notifications

When a person joins or leaves a team, or when a message is posted to a team, you should now receive an event from RingCentral which will be displayed in your console or in your ngrok inspector.

    "timestamp": "2017-03-21T18:29:27.408+0000",
    "subscriptionId": "a45645-0001-cc71-9de3-674476722",
    "uuid": "b11c9430-9687-4498-b12b-3fcb470bfe04",
    "event": "/restapi/v1.0/glip/posts",
    "body": {
        "eventType": "PostAdded",
        "id": "0000001",
        "type": "TextMessage",
        "text": "Hi!",
        "creatorId": "123456789",
        "groupId": "1234",
        "creationTime": "2017-03-21T18:29:20Z",
        "lastModifiedTime": "2017-03-21T18:29:27Z"


With events now being delivered to your bot server, you can begin posting messages back to the team to build your conversational interface.

This guide has walked you through the creation of a simple bot server using Javascript. The bot server itself is rudimentary, but should help to understand the basic underlying components and functions your bot server will be responsible for. If you are a Javascript developer, be sure to checkout RingCentral's Javascript bot framework which provides a more full-featured bot server in a box.