RingCentral SDK

Overview
1. Included
2. To Do
Documentation
Installation
Usage
Change Log
Links
Contributions
License

Overview

This is an unofficial Ruby SDK for the RingCentral for Developers Platform REST API (https://developers.ringcentral.com).

The core SDK objects follow the general design of the official RingCentral SDKs. Additional functionality is provided for ease of use including request helpers and generalized OAuth2 support.

This SDK is an early stage library and subject to breaking changes.

Included

OAuth2 authorization & token refresh via INTRIDEA OAuth2::AccessToken
Generic API requests handled via Faraday client
Fax request helper to create multipart/mixed messages
Docs via Read the Docs and RubyDoc

To Do

The following items are still needed for this SDK. Contributions are most welcome.

Subscriptions
Mock tests

Documentation

More documentation is available on Read the Docs and RubyDoc. The documentation philosophy is to use RubyDoc / YARD for brief documentation and code specific docs while using Read the Docs for user guide / tutorial / FAQ style documentation.

In addition the documentation for this Ruby SDK, refer to the official RingCentral guides for more information on individual API calls:

API Developer and Reference Guide for information on specific APIs.
API Explorer
CTI Tutorial

Installation

Via Bundler

Add this line to your application's Gemfile:

gem 'ringcentral_sdk'

And then execute:

$ bundle

Via RubyGems

$ gem install ringcentral_sdk

Usage

This provides a very basic guide to using the SDK. Please use the following resources for more information:

API Developer and Reference Guide

Instantiation

The RingCentral server URLs can be populated manually or via the included constants:

RingCentralSdk::Sdk::RC_SERVER_PRODUCTION
RingCentralSdk::Sdk::RC_SERVER_SANDBOX

require 'ringcentral_sdk'

rcsdk = RingCentralSdk::Sdk.new(
  "myAppKey",
  "myAppSecret",
  RingCentralSdk::Sdk::RC_SERVER_SANDBOX
)
platform = rcsdk.platform

Authorization

# Initialize using main phone number and extension number
platform.authorize("myUsername", "myExtension", "myPassword")

# Initialize using user phone number without extension number
# Extension defaults to company admin extension
platform.authorize("myUsername", nil, "myPassword")

Authentication Lifecycle

The platform class performs token refresh procedure automatically if needed. To save the access and refresh tokens between instances of the SDK, you can save and reuse the token as follows:

# Retrieve and save access token when program is to be stopped
# `token` is an `OAuth2::AccessToken` object
token_hash = rcsdk.platform.token.to_hash

After you have saved the token hash, e.g. as JSON, you can reload it in another instance of the SDK as follows:

# Reuse token_hash in another SDK instance
rcsdk2 = RingCentralSdk::Sdk.new(
  "myAppKey",
  "myAppSecret",
  RingCentralSdk::Sdk::RC_SERVER_SANDBOX
)
# set_token() accepts a hash or OAuth2::AccessToken object
rcsdk2.platform.set_token(token_hash)

Important! You have to manually maintain synchronization of SDK's between requests if you share authentication. When two simultaneous requests will perform refresh, only one will succeed. One of the solutions would be to have semaphor and pause other pending requests while one of them is performing refresh.

See the authorization docs for more info including token reuse.

API Requests

Requests are made using the inclued Faraday client which you can retrieve by calling rcsdk.platform.client or using it directly.

client = rcsdk.platform.client

SMS Example

SMS and other requests can be easily sent directly without helpers.

# SMS Example
response = client.post do |req|
  req.url 'account/~/extension/~/sms'
  req.headers['Content-Type'] = 'application/json'
  req.body = {
    :from =>   { :phoneNumber => '16505551212' },
    :to   => [ { :phoneNumber => '14155551212'} ],
    :text => 'RingCentral SMS demo using Ruby!'
  }
end

Fax Example

Request helpers are subclasses of RingCentralSdk::Helpers::Request and provide standard methods that can be called by the .request() method of the SDK and Platform objects. This enables the requisite information for Faraday to be generated in a standard way.

To create your own request helpers, please take a look at the fax one shown below:

The fax helper is included to help create the multipart/mixed HTTP request. This consists of instantiating a fax helper object and then executing a Faraday POST request. The helper can then be used with the standard faraday client or helper .request() method that takes the request helper object in its entirety.

# Fax example using request helper
fax = RingCentralSdk::Helpers::CreateFaxRequest.new(
  nil, # auto-inflates to [{:account_id => '~', :extension_id => '~'}]
  {
    # phone numbers are in E.164 format with or without leading '+'
    :to            => [{ :phoneNumber => '+16505551212' }],
    :coverPageText => 'RingCentral fax PDF demo using Ruby!'
  },
  :file_name     => '/path/to/my_file.pdf'
)

# sending request via request helper methods
response = sdk.request(fax)
response = sdk.platform.request(fax)

# sending request via standard Faraday client
response = client.post do |req|
  req.url fax.url
  req.headers['Content-Type'] = fax.content_type
  req.body = fax.body
end

Subscriptions

To make subscriptions with RingCentral, use the SDK object to create subscription Observer object and then add observers to it.

sub = rcsdk.create_subscription()

sub.subscribe(['/restapi/v1.0/account/~/extension/~/presence'])

class MyObserver
  def update(message)
    puts "Subscription Message Received"
    puts JSON.dump(message)
  end
end

sub.add_observer(MyObserver.new())

sub.destroy() # end the subscription

Versioning

This project is currently in development and the API can change. During initial development (Version 0.x.x), minor version changes will indicate either substantial feature inclusion or breaking changes.

Once the project is version 1.0.0 or above, it will use semantic versioning. At this time, breaking changes will be indicated by a change in major version.

Change Log

See CHANGELOG.md

Contributions

Any reports of problems, comments or suggestions are most welcome.

Please report these on Github

License

RingCentral SDK is available under an MIT-style license. See LICENSE.txt for details.