https://github.com/ringcentral/ringcentral-js
RingCentral Connect Platform JS SDK
https://github.com/ringcentral/ringcentral-js
Last synced: 3 months ago
JSON representation
RingCentral Connect Platform JS SDK
- Host: GitHub
- URL: https://github.com/ringcentral/ringcentral-js
- Owner: ringcentral
- License: mit
- Created: 2015-01-15T20:19:38.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2024-04-23T06:18:05.000Z (about 2 years ago)
- Last Synced: 2024-04-23T09:19:05.003Z (about 2 years ago)
- Language: TypeScript
- Homepage: http://developers.ringcentral.com
- Size: 10 MB
- Stars: 63
- Watchers: 26
- Forks: 55
- Open Issues: 34
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# RingCentral JavaScript SDK
[](https://github.com/ringcentral/ringcentral-js/actions)
[](https://coveralls.io/github/ringcentral/ringcentral-js)
[](https://ringcentral.github.io/join-ringcentral/)
[](https://twitter.com/RingCentralDevs)
The RingCentral Javascript SDK is most often used by the following developers:
* RingCentral customers needing to access data in their account to automate a business process
* RingCentral [ISV partners](https://www.ringcentral.com/partner/isv.html) building and promoting products for RingCentral customers to integrate with an external system or fill a feature gap in the product
Developers use the SDK to build both client and server-side javascript applications that interface with the RingCentral platform. The SDK can assist developers with the following:
* [Send and receive SMS](https://developer.ringcentral.com/api-products/sms)
* [Send and receive fax messages](https://developers.ringcentral.com/fax-api)
* [Create chat and other messaging bots](https://developer.ringcentral.com/api-products/team-messaging)
* [Download and archive call logs and recordings](https://developers.ringcentral.com/overview/call-reporting)
* [Automate account setup & provisioning](https://developers.ringcentral.com/api-reference/provisioning)
* [Access webinar participant data](https://developers.ringcentral.com/guide/webinar)
* [Schedule video meetings](https://developers.ringcentral.com/guide/video/api)
As an emerging leader in the CPaaS industry, the RingCentral platform is also being used by more and more developers as their preferred communications platform for their own product or company.
## Prerequisites
To use this SDK and access RingCentral APIs, you must:
* be a RingCentral customer, or have signed up for a developer account
* [registered an application](https://developers.ringcentral.com/guide/getting-started/register-app) and acquired a client ID and secret
##### Are you a first-time RingCentral Developer?
If this is your first time building a RingCentral application, we recommend you get started online using our SMS Quick Start guide which will help you get up-and-running in minutes.
* [Get Started Using RingCentral »](https://developers.ringcentral.com/guide/sms/quick-start)
##### Packages included in this SDK
The RingCentral Javascript SDK contains two packages useful to developers. They are:
- [SDK](sdk). The main SDK package used for calling RingCentral's REST APIs.
- [Subscriptions](subscriptions). An additional SDK to assist developers in subscribing and responding to events via Web Sockets.
**Are you building a client application for RingCentral?**
If you are building a front-end-heavy client application for making and receiving phone call, sending and receiving SMS messages, engaging with team chat, and more, then you may want to take a closer look at [RingCentral Embeddable](https://apps.ringcentral.com/integration/ringcentral-embeddable/latest/), which is designed specifically for those use cases.
## Installation
The RingCentral Javascript SDK can be installed easily via npm.
```
npm install @ringcentral/sdk --save
```
Many code samples throughout RingCentral's documentation assume you are using `.env` files to store key values used by your application. To read a `.env` file, we recommend you install the [dotenv](https://www.npmjs.com/package/dotenv) module. We have provided a sample `.env` below for your convenience. You may find some code samples utilize environment variables not included below, requiring you to edit this file according to your needs.
```
# Core values
RC_SERVER_URL = 'https://platform.ringcentral.com'
RC_CLIENT_ID = ''
RC_CLIENT_SECRET = ''
# This credential is used for JWT-grant types
RC_JWT = ''
```
## Usage
You will find a wide range of code samples throughout our [RingCentral Developer Guide](https://developers.ringcentral.com/guide/), which we recommend you consult as a more complete and relevant code sample. However, the following code sample can help you get a sense of how the SDK works at a high-level and how to connect successfully for the first time.
### Authentication
##### Using a JWT credential
JWT is an ideal authentication method for server-to-server use cases. One can pass a JWT credential to the `login` method to authenticate.
```js
const RC_SDK = require('@ringcentral/sdk').SDK
var rcsdk = new RC_SDK({
'server': process.env.RC_SERVER_URL,
'clientId': process.env.RC_CLIENT_ID,
'clientSecret': process.env.RC_CLIENT_SECRET
});
var platform = rcsdk.platform();
platform.login({ 'jwt': process.env.RC_JWT })
```
##### Setting the access token manually
If your application uses OAuth auth token flow, you may have stored or cached an access token. You can set your access token directly by creating an auth object and calling the `setData()` method.
```js
var platform = rcsdk.platform();
var data = platform.auth().data();
data.token_type = "bearer"
data.expires_in = "your_AccessToken_Expiration"
data.access_token = "your_AccessToken"
data.refresh_token = "your_RefreshToken"
data.refresh_token_expires_in = "your_RefreshToken_Expiration"
platform.auth().setData(data)
```
### Making an API call
Once you have successfully authenticated, you can begin making REST API calls using either the `get()`, `post()`, `put()` or `delete()` methods. The following code snippet shows how one can initiate a phone call using the RingOut methodology.
```js
try {
var resp = await platform.post('/restapi/v1.0/account/~/extension/~/ring-out', {
'from': { 'phoneNumber': "" },
'to': { 'phoneNumber': "