https://github.com/ringcentral/ringcentral-js-client
RingCentral Connect Platform JS Client
https://github.com/ringcentral/ringcentral-js-client
Last synced: 12 months ago
JSON representation
RingCentral Connect Platform JS Client
- Host: GitHub
- URL: https://github.com/ringcentral/ringcentral-js-client
- Owner: ringcentral
- License: mit
- Created: 2015-11-20T03:14:11.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2021-06-25T23:06:26.000Z (about 5 years ago)
- Last Synced: 2025-06-19T19:18:34.853Z (about 1 year ago)
- Language: TypeScript
- Size: 522 KB
- Stars: 13
- Watchers: 5
- Forks: 16
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# RingCentral Client
[](https://travis-ci.org/ringcentral/ringcentral-js-client)
[](https://coveralls.io/github/ringcentral/ringcentral-js-client?branch=master)
[](https://devcommunity.ringcentral.com/ringcentraldev)
[](https://twitter.com/RingCentralDevs)
__[RingCentral Developers](https://developer.ringcentral.com/api-products)__ is a cloud communications platform which can be accessed via more than 70 APIs. The platform's main capabilities include technologies that enable:
__[Voice](https://developer.ringcentral.com/api-products/voice), [SMS/MMS](https://developer.ringcentral.com/api-products/sms), [Fax](https://developer.ringcentral.com/api-products/fax), [Glip Team Messaging](https://developer.ringcentral.com/api-products/team-messaging), [Data and Configurations](https://developer.ringcentral.com/api-products/configuration)__.
[API Reference](https://developer.ringcentral.com/api-docs/latest/index.html) and [APIs Explorer](https://developer.ringcentral.com/api-explorer/latest/index.html).
## Overview
This is a library implemented in TypeScript which provides convenient APIs for TypeScript and JavaScript developers to access RingCentral webservice(https://developer.ringcentral.com/api-docs/latest/index.html).
# Table of contents
- [Getting Started](#getting-started)
- [API Call Examples](#api-call-examples)
- [Telephony Calls](#telephony-calls)
- [Send SMS](#send-sms)
- [Send Fax](#send-fax)
- [Extension management](#extension-management)
## Getting started
### Install
```shell
npm install ringcentral-client --save
npm install @ringcentral/sdk # Install the peerDependency
yarn add ringcentral-client @ringcentral/sdk
```
### Import the module
#### In Typescript or ES6 (Recommended)
```typescript
import RingCentralClient, {SERVER_SANDBOX} from "ringcentral-client";
import { SDK } from "@ringcentral/sdk";
```
#### In commonjs(node.js, webpack and browserify)
```javascript
var ringcentral = require("ringcentral-client");
var RingCentralClient = ringcentral.Client;
var SERVER_SANDBOX = ringcentral.SERVER_SANDBOX;
var SDK = require("@ringcentral/sdk").SDK;
```
#### Used in browser through the prebuilt javascript bundle
All APIs are exposed on the global variable `RingCentral`.
```html
console.log("All api", RingCentral);
var RingCentralClient = RingCentral.Client;
var SERVER_SANDBOX = RingCentral.SERVER_SANDBOX;
var SDK = RingCentral.SDK;
// ...
```
### Quick Start
Login, logout, get account info.
```typescript
const sdk = new SDK({
server: SERVER_PRODUCTION, // Optional, default is production server
clientId: process.env.CLIENT_ID,
clientSecret: process.env.CLIENT_SECRET
});
const client = new RingCentralClient(sdk);
// Log into RingCentral
sdk.platform().login({
"username": process.env.USERNAME,
"extension": process.env.EXTENSION,
"password": process.env.PASSWORD
}).then(() => {
console.log("Login success");
return client.account().get(); // Call RingCentral REST API
}).then((accountInfo) => {
console.log("Current account info", accountInfo);
return sdk.platform().logout(); // Logout
}).then(() => {
console.log("logout success");
}).catch(e => {
console.error("Error occured", e);
});
```
## API Call Examples
### Telephony Calls
1. Make phone calls by ringout(https://developer.ringcentral.com/api-docs/latest/index.html#!#MakeRingOut.html):
```javascript
client.account().extension().ringout().post({
from: { phoneNumber: "xxx" },
to: { phoneNumber: "xxx" },
callerId: { phoneNumber: "xxx" }
}).then(ringout => {
console.log("Ringout sucess", ringout);
// To check the call status: `client.account().extension().ringout(ringout.id).get();`
}, e => {
console.error("Fail to ringout", e);
});
```
2. Track the telephony status
To get notications when calls come in, go out or ends, subscribe to the **Presence Event**:
```javascript
let subscription = client.createSubscription();
subscription.on(subscription.events.notification, function (msg) {
let presenceEvt = msg.body; // Detail for presence event: https://developer.ringcentral.com/api-docs/latest/index.html?section=RefNotifications.html#!#RefGetDetailedPresenceEvent
console.log("@@@@presence event", presenceEvt);
console.log("telephonyStatus", presenceEvt.telephonyStatus);
console.log("activeCalls", presenceEvt.activeCalls);
});
subscription
.setEventFilters(['/account/~/extension/~/presence?detailedTelephonyState=true ']) // a list of server-side events
.register()
.then((subscription) => {
console.log("Subscription created", subscription.json());
}, e => {
console.error("Fail to create subscription", e);
});
```
3. View the list of active calls
```javascript
client.account().extension().activeCalls().list({
page: 1, // Get the 1st page of the result
direction: "Inbound" // Specify the direction of the call, omit to get all directions
}).then(results => {
console.log("Active calls", results.records);
}, e => {
console.error("Fail to get active calls", e);
});
```
4. View the recent calls
```typescript
let dateFrom = new Date(Date.now() - 24 * 60 * 60 * 1000); // A day ago
client.account().extension().callLog().list({ dateFrom: dateFrom.toISOString() }).then(results => {
console.log("Recent call logs", results.records);
}, e => {
console.error("Fail to get call logs", e);
});
```
### Send SMS
```typescript
client.account().extension().sms().post({
to: [{
phoneNumber: "{receiverPhoneNumber}"
}],
from: {
phoneNumber: "{yourSmsNumber}"
},
text: "Sms content"
}).then(function(messageInfo) {
console.log("Sms sent successfully", messageInfo);
}).catch(function(e) {
console.error("Fail to send sms", e);
});
```
### Send Fax
For all supported options and mediatype, please refer to https://developer.ringcentral.com/api-docs/latest/index.html#!#RefFaxMessages.html.
```typescript
import * as fs from "fs";
client.account().extension().fax().post({
to: [{ phoneNumber: "{receiverPhoneNumber}" }],
faxResolution: 'High'
}, [ // Second argument is an array of attachments, attachment can be string, Blob, node readable stream.
"{Message text}",
fs.createReadStream("{filePath}") // In node only
]);
});
```
### Extension management
Get detail information of an extension:
```typescript
client.account().extension('theExtensionId').get().then(function (extInfo) {
console.log("The extension info", extInfo);
}).catch(function (e) {
console.error("Get extension error", e);
});
```
List extensions of an account:
```typescript
client.account("theAccountId").extension().list().then(function (extensions) {
console.log("The list of extension info", extensions.records);
}).catch(function (e) {
console.error("Get extension list error", e);
});
```
Update infomation of an extension:
```typescript
client.account().extension().put({ status: "Enabled" }).then(function () {
console.log("Success to update extension.");
}).catch(function () {
console.error("Fail to update extension.");
});
```