RingCentral-Add-In-Framework

This template aims to help you quickly set up your app with 3rd party webhook integration.

Prerequisites

• Download and install RingCentral App and login: https://www.ringcentral.com/apps/rc-app
• Nodejs and npm.

How It Works

There are 3 major parts involved:

• Setup:
  • Get RingCentral App info
  • Auth on 3rd party and subscribe to events
• Use:
  • Process and forward 3rd party event notifications to RingCentral App via webhook
• Revoke:
  • Unsubscribe and clear user info

Workflow Diagram

Note: if you don't have Markdown view, please open the flow diagram directly from diagram/flow.svg.

Development

Step.1 Start Web Tunnel

# install dependencies
npm i

# create db file - additional note: 'npm run refreshDB' command will clear DB and re-init it
npm run initDB 

# start proxy server, this will allow your local bot server to be accessed by the RingCentral service
npm run ngrok

# will show
Forwarding                    https://xxxx.ngrok.io -> localhost:6066
# Remember the https://xxxx.ngrok.io, we will use it later

ngrok will expose your local server to a public address where you can have other services interact with it.

Note: your local firewall might block certain ngrok regions. If so, try changing ngrok http -region us 6066 in package.json to other regions.

Step.2 Set Up Environment Info

There are several OAuth-related fields in .env need to be set. They can be found on your target 3rd party platform docs.

# .env file

# local server setup
APP_SERVER= # Copy `https://xxxx.ngrok.io` from last step

# 3rd party Oauth
CLIENT_ID=
CLIENT_SECRET=
ACCESS_TOKEN_URI=
AUTHORIZATION_URI=
SCOPES= # if SCOPES_SEPARATOR is ',', then SCOPES will be something like scope1,scope2,scope3
SCOPES_SEPARATOR=, # this field is default to ',', but can be changed

# RingCentral developer portal
IM_SHARED_SECRET= # You'll need a RingCentral App first, and this can then be found on developer portal, under App Settings

Step.3 Start Local Server and Client

Open 2 new terminals and run below commands respectively:

# open a new terminal
# start local server
npm run start

# open another new terminal
# start client app
npm run client

Online Developer Tool

For local development, we can use RingCentral notification app developer tool to simulate RingCentral App Gallery shell which handles communications between your app and RingCentral server.

To use above tool, there are two fields we want to fill in:

1. App Url: It is for this tool to retrieve the app's entry point to render. In our framework, it's set to https://xxxx.ngrok.io/setup
2. Webhook Url, there are 2 ways:
   1. Click Get a webhookUrl and login to your RingCentral App. Generate webhook url from your Team channel.
   2. Go to RingCentral App Gallery and add Incoming Webhook App to your conversation channel. As a result, you will get a webhook URL like https://hooks.glip.com/webhook/xxxxx (aka RC_WEBHOOK) and that's what we need here.

Now press Apply (workflow 1-2). We should be able to see the UI button gets rendered in top block.

(Important note: RingCentral notification app developer tool doesn't provide the environment for interactiveMessages(workflow 16-30). To have a test environment for that, you will need to create your sandbox app on RingCentral Developer Portal (Add-In is currently in beta, so you want to join beta on the same web page).)

POST Test Data

There is a simple HTTP POST script: scripts/test-data.js. If you need to have a quick test to mock 3rd party notification, please follow comments inside the file.

# run test post data
node scripts/test-data.js

Step.4 Write Your Code and Try It

Now that development environment is all set, let's make some changes to the code.

There is a few spots that need your input. Note: If you want to test your changes, you'll need to kill the server which runs npm run start and start it again.

1. Go to src/server/routes/authorization.js and follow the instruction on top. After this step, click Connect to 3rd Party Service and Subscribe(workflow 3-7) and you'll be able to auth user for 3rd party platform. Then Developer Tool should show Subscribe and Unsubscribe and Logout buttons.
2. Go to src/server/routes/subscription.js and follow the instruction on top. After this step, click subscribe(workflow 8-11) button on Developer Tool, your RingCentral App conversation should receive an example message from webhook.
3. Go to src/server/routes/notification.js and follow the instruction on top. After this step, it would send message(workflow 12-15) with data transformed from 3rd party platform notification where there's any new event that you subscribe to.
4. Go back to src/server/routes/authorization.js, follow the instruction in revokeToken method. After this step, click Unsubscribe and Logout(workflow 31-33) button and there will be no more notifications from 3rd party platform.

Tips

• Adaptive Cards Designer is a great online tool to design your Adaptive Cards. Json files under src/server/adaptiveCards follow the same format as in CARD PAYLOAD EDITOR, so you can design your card on Adaptive Cards Designer and copy over the payload directly.
• npm run refreshDB to delete existing db file and create a new one

Additional Note

There are several npm packages to be highlighted here:

• adaptivecards-templating: Tool to inject data into Adaptive Cards json files.
• sequelize: Node.js database ORM tool
• axios: Promise based HTTP client for the browser and node.js
• client-oauth2: OAuth2 wrapper
• serverless: serverless framework

When start development, it's recommended to use 3rd party's official npm package for its API calls.

Test

This template uses supertest and nock for testing. A few examples are in tests folder. To start test:

npm run test

Deployment

Register App on RingCentral Developer Website

Create your app following this guide.

Deploy with Heroku

Use Heroku deploy button on the top to do initial deployment. Then link your repository with Heroku for future deployments using git push heroku {branch}.

Note: For environment variables, you may ignore APP_SERVER and ASSETS_PATH for initial deployment and fill in later.

Environment Variables

After the initial deployment, we can easily get full info on environment variables. Go to Heroku app setting page and update them accordingly:

• APP_SERVER: your heroku app domain
• ASSETS_PATH: if you host client under server itself, then it's {APP_SERVER}/client. Otherwise fill in the address of your own host

More Info

• Heroku Button
• This template is configured with Heroku Postgres
• Integrate with Other Heroku Add-on