RingCentral-Add-In-Framework(Github Demo)

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

Try It

Let's give it a quick try.

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

Firstly, we want to create a OAuth App on https://github.com/settings/developers. In app creation page, fill Authorization callback URL with https://xxxx.ngrok.io/oauth-callback. Note: Homepage URL isn't important, you can fill it with a dummy url.

After it's created, we'll see ClientId and let's also generate a ClientSecret.

Rename sample.env to .env and sample.env.test to env.test(env for test). There are several OAuth-related fields in .env need to be set.

# .env file

# local server setup
PORT=6066
APP_HOST=localhost
# Copy `https://xxxx.ngrok.io` from last step
APP_SERVER=https://xxxxxx.ngrok.io
# This is the key string to encrypt server-client communication credentials
APP_SERVER_SECRET_KEY=sampleKey 

# Github Oauth
# ClientId from Github OAuth App
CLIENT_ID= 
# ClientSecret from Github OAuth App
CLIENT_SECRET= 
ACCESS_TOKEN_URI=https://github.com/login/oauth/access_token
AUTHORIZATION_URI=https://github.com/login/oauth/authorize
SCOPES=admin:repo_hook,read:user,repo
SCOPES_SEPARATOR=,

# This can be any repo name that you want to watch, it's recommended to create a new test repo for initial try
GITHUB_REPO_NAME= 

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

# db uri
DATABASE_CONNECTION_URI=sqlite://./db.sqlite
# client-side UI asset path
ASSETS_PATH=http://localhost:8081

Step.3 Start Local Server and Client

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

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

Go to RingCentral App and add your app to a conversation, Auth -> Subscribe -> Finish. It should then provide the ability to listen to New Issue event and also give user ability to add any label to the issue.

To test it, go to your Github repo and create a new issue. There should be an adaptive card sent to your RingCentral App conversation which also provides buttons for you to add labels to your issue.

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

Workflow Diagram

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

Refer to Workflow Diagram, sections are explained with user actions as below:

• Authorization (workflow 3-7): Press Connect to 3rd Party Service and Subscribe. And do authorization on a new page rendered by 3rdp arty service.
• Subscription (workflow 8-11): Upon the close of auth page, the framework will automatically trigger subscription creation (in practice, it's recommended to create a separate flow for auth and subscription).
• Notification (workflow 12-15): Once the subscription is created, notifications from 3rd party service should be sent to our endpoint on https://xxxx.ngrok.io/notification. And notification data will be transformed and sent to RingCentral App.
• Interactive Message (workflow 16-30): Any user in RingCentral App conversation who has the 3rd party account would be able to perform actions within RingCentral App. New users will need to authorize first.
• Revoke (workflow 31-33): Press Unsubscribe and Logout, and incoming notifications will stop being sent to RingCentral App.

Additional Note

There are several npm packages to be highlighted here:

• octokit rest: Github's official npm package to make API calls easy.
• 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.

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}.

More Info:

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