Notoriously Punctual Manatee

    ringcentral-call-control
    TypeScript icon, indicating that this package has built-in type declarations

    0.2.8 • Public • Published

    RingCentral Call Control JS SDK

    Coverage Status NPM Version Build Status

    RingCentral Call Control JS SDK is wrapper of RingCentral JS SDK to help developers call RingCentral Call Control API more functionally.

    Features:

    We added the following key features to do the heavy lifting for you.

    • Call session management to load existing call sessions or create call session.
    • Call session event. Handle telephony session notifications, manage call session lifecycle
    • Call session management with functional API.
    • Devices management to load user’s devices.

    Notice: This library doesn't provide ability of voice transmission. For working with WebRTC voice transimission, please use RingCentral Call JS SDK. It combines WebRTC voice transimission and Call Control RESTful APIs.

    Prerequisites

    • You will need an active RingCentral account to create RingCentral app. Don't have an account? Get your Free RingCentral Developer Account Now!
    • A RingCentral app
      • App type: Browser-Based or Server/Web
      • Permissions: 'Call Control', 'Read Accounts', 'Read Presence', 'Webhook Subscriptions'

    Table of Contents

    Install

    Use npm or yarn

    $ yarn add @ringcentral/sdk @ringcentral/subscriptions ringcentral-call-control

    CDN

    <script type="text/javascript" src="https://unpkg.com/es6-promise@latest/dist/es6-promise.auto.js"></script>
    <script type="text/javascript" src="https://unpkg.com/pubnub@latest/dist/web/pubnub.js"></script>
    <script type="text/javascript" src="https://unpkg.com/whatwg-fetch@latest/dist/fetch.umd.js"></script>
    <script type="text/javascript" src="https://unpkg.com/@ringcentral/sdk@latest/dist/ringcentral.js"></script>
    <script type="text/javascript" src="https://unpkg.com/@ringcentral/subscriptions@latest/dist/ringcentral-subscriptions.js"></script>
    <script type="text/javascript" src="https://unpkg.com/ringcentral-call-control@0.2.0/build/index.js"></script>

    Usage

    For this example you will also need to have RingCentral JS SDK and RingCentral JS Subscriptions SDK installed.

    Configure and new Call Control instance:

    // npm import
    // import { RingCentralCallControl } from 'ringcentral-call-control';
    // or use CDN
    // window.RingCentralCallControl
    
    var appClientId = '...'; 
    var appClientSecret = '...';
    var appName = '...';
    var appVersion = '...';
    
    var sdk = new RingCentral.SDK({
      clientId: appClientId,
      clientSecret: appClientSecret,
      appName: appName,
      appVersion: appVersion,
      server: RingCentral.SDK.server.production // or .sandbox
    });
    var subscriptions = new RingCentral.Subscriptions({
      sdk: sdk
    });
    var platform = sdk.platform();
    
    platform
      .login({
        username: '...',
        password: '...'
      })
      .then(function() {
        var rcCallControl = new RingCentralCallControl({ sdk: sdk });
        var subscription = subscriptions.createSubscription();
    
        subscription.setEventFilters(['/restapi/v1.0/account/~/extension/~/telephony/sessions']);
        subscription.on(subscription.events.notification, function(msg) {
           rcCallControl.onNotificationEvent(msg)
        });
        subscription.register();
        return rcCallControl;
      })

    Demo

    $ git clone https://github.com/ringcentral/ringcentral-call-control-js.git
    $ cd ringcentral-call-control-js
    $ yarn
    $ yarn build
    $ yarn start

    Open http://localhost:8080/demo/, and login with RingCentral Sandbox account to test.

    Get online demo here.

    API

    Init

    Firstly, we need to create Call Control instance after user login with RingCentral JS SDK. Then connect onNotificationEvent with subscription notification event.

    var rcCallControl = new RingCentralCallControl({ sdk: sdk });
    var initialized = false;
    var subscription = subscriptions.createSubscription();
    subscription.setEventFilters(['/restapi/v1.0/account/~/extension/~/telephony/sessions']);
    subscription.on(subscription.events.notification, function(msg) {
      rcCallControl.onNotificationEvent(msg)
    });
    subscription.register();
    rcCallControl.on('initialized', function() {
      initialized = true;
    });

    Events

    New session event

    var session = null;
    
    rcCallControl.on('new', (newSession) => {
      session = newSession;
    });

    Initialized

    rcCallControl.on('initialized', function() {
      initialized = true;
    });

    Sessions List

    var sessions = rcCallControl.sessions;

    Session API

    Create a Call Session

    var session = null;
    var deviceId = rcCallControl.devices.filter(d => d.status === 'Online')[0].id;
    rcCallControl.createCall(deviceId, { phoneNumber: 'phoneNumberToCall' }).then((newSession) => {
      session = newSession;
      // ...
    })

    Drop Session

    Drops a call session.

    session.drop().then(...);

    Hold Unhold

    Puts the party to stand-alone mode and starts to play Hold Music according to configuration & state to peers. There is a known limitation for Hold API - hold via REST API doesn't work with hold placed via RingCentral apps or HardPhone. It means that if you muted participant via Call Control API and RingCentral Desktop app, then you need to unhold both endpoints to remove Hold Music and bring media back.

    session.hold().then(...);
    session.unhold().then(...);

    Mute Unmute

    Callee will be put on mute or unmute

    session.mute().then(...);
    session.unmute().then(...);

    To Voicemail

    session.toVoicemail().then(...);

    Ignore in call queue

    session.ignore({ deviceId: 'your_device_id' }).then(...);

    Answer

    session.answer({ deviceId: 'your_device_id' }).then(...);

    Reply with message

    session.reply({ replyWithText: 'On my way' }).then(...);
    session.reply({
      replyWithPattern: {
        pattern: 'WillCallYouBack',
        time: 10,
        timeUnit: 'Minute'
      }
    }).then(...);

    Forward

    Distributes a non-answered call to the defined target. Applicable for "Setup" or "Proceeding" states

    session.forward({ phoneNumber: 'phoneNumber' }).then(...);

    Transfer

    Transfers a party by placing a new call to the specified target

    session.transfer({ phoneNumber: 'phoneNumber' }).then(...);

    Flip

    Performs call flip procedure by holding opposite party and calling to the specified target.

    session.flip({ callFlipId: 'callFlipId' }).then(...);

    Park

    Performs call park procedure to set on park one of the call parties in call dialog.

    session.park().then(...);

    Recording

    Starts a new call recording for the party

    session.createRecord().then(...);

    Pause/resume recording

    session.pauseRecord('recordingId').then(...);
    session.resumeRecord('recordingId').then(...);

    Supervise

    Allows to monitor a call in 'Listen' mode. Input parameters should contain extension number of a monitored user and internal identifier of a supervisor's device. Call session should be specified in path. Currently is not supported for Sandbox environment.

    session.supervise({
      mode: 'Listen',
      deviceId: 'your deviceId',
      extensionNumber: 'extensionNumber'
    }).then(...);

    Session Events

    Status

    session.on('status', (event) => {
      // on status changed
      var party = event.party;
      var status = party.status;
      // ...
    });

    Muted

    session.on('muted', () => {
      // on muted changed
      var muted = session.muted;
      // ...
    });

    Devices

    Get current extension's all devices:

    var devices = rcCallControl.devices;

    Refresh devices:

    rcCallControl.refreshDevices().then(() => {
      var devices = rcCallControl.devices;
    });

    Install

    npm i ringcentral-call-control

    DownloadsWeekly Downloads

    100

    Version

    0.2.8

    License

    MIT

    Unpacked Size

    308 kB

    Total Files

    55

    Last publish

    Collaborators

    • embbnux