{"id":21406699,"url":"https://github.com/ringcentral/ringcentral-add-in-framework-js","last_synced_at":"2025-07-14T00:32:44.179Z","repository":{"id":61574966,"uuid":"397447938","full_name":"ringcentral/ringcentral-add-in-framework-js","owner":"ringcentral","description":"JavaScript framework for building RingCentral Message Add-ins.","archived":false,"fork":false,"pushed_at":"2022-11-10T08:44:07.000Z","size":570,"stargazers_count":9,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-07T20:42:31.650Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://developers.ringcentral.com/guide/team-messaging/adaptive-cards","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ringcentral.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-08-18T02:23:21.000Z","updated_at":"2024-06-12T02:34:45.000Z","dependencies_parsed_at":"2022-10-19T13:00:36.747Z","dependency_job_id":null,"html_url":"https://github.com/ringcentral/ringcentral-add-in-framework-js","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/ringcentral/ringcentral-add-in-framework-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringcentral%2Fringcentral-add-in-framework-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringcentral%2Fringcentral-add-in-framework-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringcentral%2Fringcentral-add-in-framework-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringcentral%2Fringcentral-add-in-framework-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ringcentral","download_url":"https://codeload.github.com/ringcentral/ringcentral-add-in-framework-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringcentral%2Fringcentral-add-in-framework-js/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265227898,"owners_count":23731059,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-22T16:41:58.154Z","updated_at":"2025-07-14T00:32:41.791Z","avatar_url":"https://github.com/ringcentral.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [RingCentral Add-In Framework](https://github.com/ringcentral/ringcentral-add-in-framework-js)\r\n\r\n[![Build Status](https://github.com/ringcentral/ringcentral-add-in-framework-js/actions/workflows/release.yaml/badge.svg)](https://github.com/ringcentral/ringcentral-add-in-framework-js/actions)\r\n[![Latest release](https://img.shields.io/github/v/release/ringcentral/ringcentral-add-in-framework-js)](https://github.com/ringcentral/ringcentral-add-in-framework-js/releases)\r\n\r\n\r\nThe framework will help you create a [RingCentral Add-In App](https://developers.ringcentral.com/guide/team-messaging/add-ins) that enables easy integration to RingCentral App.\r\n\r\n# Prerequisites\r\n\r\n- Download and install RingCentral App and login: https://www.ringcentral.com/apps/rc-app\r\n- Nodejs and npm.\r\n\r\n# Framework\r\n\r\nThis framework should be used as a boilerplate project. There are two types of Add-Ins that can be installed with this framework:\r\n- [Bot](#bot)\r\n- [Notification App](#notification-app)\r\n\r\n## Bot\r\n\u003cdetails\u003e\r\n  \u003csummary\u003eHow to install a bot template\u003c/summary\u003e\r\n\r\n### Install Bot Template\r\n\r\nTo install a `bot-template`, use:\r\n\r\n```bash\r\nnpx create-rc-add-in bot\r\n```\r\n\u003c/details\u003e\r\n\r\n\u003cdetails\u003e\r\n  \u003csummary\u003eHow to use a bot template\u003c/summary\u003e\r\n\r\n### Quick Try\r\nA `bot-template` would be up-and-running without any extra code. Here's how:\r\n\r\n1. run `npm i` and then `npm run ngrok`. We'll get `https://xxxxxx.ngrok.io` as our server address.\r\n2. Create a Bot Add-In on developer.ringcentral.com, and go to app settings. (Additional Info on creating a bot: https://developers.ringcentral.com/guide/team-messaging/bots/walkthrough)\r\n   1. OAuth Redirect URI: `https://xxxxxx.ngrok.io/bot/oauth`\r\n   2. App Permissions: Read Messages, Read Accounts, Team Messaging, Webhook Subscriptions, Edit Messages\r\n   3. Outbound Webhook URL: `https://xxxxxx.ngrok.io/interactive-messages`\r\n   4. Note down `SharedSecret`\r\n3. We'll also get `ClientId` and `ClientSecret` for the app after created. Let's then fill in `.env` file with:\r\n\r\n```bash\r\nRINGCENTRAL_CHATBOT_SERVER=https://xxxxxxx.ngrok.io\r\n\r\nRINGCENTRAL_CHATBOT_CLIENT_ID={ClientId}\r\n\r\nRINGCENTRAL_CHATBOT_CLIENT_SECRET={ClientSecret}\r\n\r\nRINGCENTRAL_SERVER=https://platform.devtest.ringcentral.com\r\n\r\nRINGCENTRAL_CHATBOT_EXPRESS_PORT=6066\r\n\r\nRINGCENTRAL_CHATBOT_DATABASE_CONNECTION_URI=sqlite://./db.sqlite\r\n\r\n# Credentials for admin actions\r\nRINGCENTRAL_CHATBOT_ADMIN_USERNAME=admin\r\nRINGCENTRAL_CHATBOT_ADMIN_PASSWORD=password\r\n\r\n# RingCentral Add-In App interactive message shared secret\r\nRINGCENTRAL_SHARED_SECRET={SharedSecret}\r\n```\r\n\r\n4. Open another terminal and run `npm run start`\r\n5. On developer portal, go to your bot app's `Bot` tab and do `Add To RingCentral`\r\n6. Go to `https://app.devtest.ringcentral.com` to test it with direct message or @{yourBotName} in a team conversation with command `hello` and `card`\r\n\r\n### Development\r\n\r\nNew bot command, in `src/handlers/botHandler.js`, add a new `case`:\r\n\r\n```javascript\r\ncase 'new command':\r\n    // send text\r\n    const myText = '';\r\n    await bot.sendMessage(group.id, { text: myText });\r\n    // Or, send adaptive card. Here we use adaptive card template package, please refer to the use of it in the template\r\n    // https://adaptivecards.io/designer/ is a great tool to design your card\r\n    const card = {};\r\n    await bot.sendAdaptiveCard(group.id, card);\r\n```\r\n\r\n\u003c/details\u003e\r\n\r\n\u003cbr\u003e\r\n\r\n## Notification App\r\n\r\n\u003cdetails\u003e\r\n  \u003csummary\u003eHow to install a notification app template/demo\u003c/summary\u003e\r\n\r\n### Install Notification App Template\r\n\r\nThis framework contains several app template variations due to the fact that different 3rd party platforms have different designs on their APIs. Before starting the installation, please:\r\n1. Go to 3rd party platform and register a new app there. For most platforms who have OAuth flow implementation, there will be `ClientId` and `ClientSecret` generated for your app.\r\n2. If 3rd party platform uses `OAuth`, please check if it uses `accessToken` + `refreshToken` OR just `accessToken`.\r\n3. If 3rd party platform uses `OAuth`, please find their API endpoints for authorization and access token exchange.\r\n   \r\nThen install a `app-template` with following commands:\r\n\r\n```bash\r\nnpx create-rc-add-in app\r\n```\r\n\r\nWe also have simple `app-demo` that are based on the template and they'll be up and running with a few steps to configure. Demos can be installed with:\r\n\r\n```bash\r\nnpx create-rc-add-in app-demo\r\n```\r\n\u003c/details\u003e\r\n\r\n\u003cdetails\u003e\r\n  \u003csummary\u003eHow to use a notification app template\u003c/summary\u003e\r\n\r\n### Use Notification App Template\r\n\r\nTo work with a plain `app-template`, we want to fill in our business logic in handlers which are for:\r\n- Authorization (authorize Add-In server with user's 3rd party platform account)\r\n- Subscription (create event subscription on 3rd party platform)\r\n- Notification (receive and format data from 3rd party platform when subscribed events happen)\r\n\r\n### Coding\r\n\r\nPlease follow the steps inside the handlers. For example, authorization handler in `template` looks like:\r\n\r\n```javascript\r\n// Step.1: Get user info from 3rd party API call\r\nconst userInfoResponse = { id: \"id\", email: \"email\", name: \"name\"}   // [REPLACE] this line with actual call\r\nconst userId = userInfoResponse.id; // [REPLACE] this line with user id from actual response\r\n// Find if it's existing user in our database\r\nlet user = await User.findByPk(userId);\r\n// Step.2: If user doesn't exist, we want to create a new one\r\nif (!user) {\r\n    user = await User.create({\r\n        id: userId,\r\n        accessToken: accessToken,\r\n        refreshToken: refreshToken,\r\n        tokenExpiredAt: expires,\r\n        email: userInfoResponse.email, // [REPLACE] this with actual user email in response, [DELETE] this line if user info doesn't contain email\r\n        name: userInfoResponse.name, // [REPLACE] this with actual user name in response, [DELETE] this line if user info doesn't contain name\r\n    });\r\n}\r\n```\r\n\r\nFocus on `[REPLACE]` and `[DELETE]` tags. If we want to integrate Asana, then it'd be:\r\n\r\n```javascript\r\n// Step1: Get user info from 3rd party API call\r\nconst client = Asana.Client.create().useAccessToken(accessToken); // create Asana client object\r\nconst userInfo = await client.users.me();   // call Asana to get user info\r\nconst userId = userInfo.gid; // get user id\r\n// Find if it's existing user in our database\r\nlet user = await User.findByPk(userId);\r\n// Step2: If user doesn't exist, we want to create a new one\r\nif (!user) {\r\n    await User.create({\r\n        id: userId,\r\n        accessToken: accessToken,\r\n        refreshToken: refreshToken,\r\n        tokenExpiredAt: expires\r\n    });\r\n}\r\n```\r\n\r\n\u003c/details\u003e\r\n\r\n\u003cdetails\u003e\r\n  \u003csummary\u003eHow to use a notification app demo\u003c/summary\u003e\r\n\r\n### Use Notification App Demo\r\n\r\nIt's a lot easier than using a `template`, and `demos` are essentially `templates` with platform-dependent logic written to implement simple functionality. Therefore a few cli commands would make it up and run.\r\n\r\nAt the moment, we have `demos` for `Github`, `Asana` and `Gitlab`.\r\n\r\n\u003c/details\u003e\r\n\r\n# Detailed Info\r\n\r\nFor further Information, please refer to the `README.md` that's inside your generated template or demo and [RingCentral App Developer Guide](https://developers.ringcentral.com/guide/applications)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fringcentral%2Fringcentral-add-in-framework-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fringcentral%2Fringcentral-add-in-framework-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fringcentral%2Fringcentral-add-in-framework-js/lists"}