RingCentral SDK

Table of contents

1. Overview
   1. Included
   2. To Do
2. Documentation
3. Installation
4. Usage
   1. Instantiation
   2. Authorization
   3. API Requests
   4. SMS Example
   5. Fax Example
5. Change Log
6. Links
7. Contributions
8. 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:

1. API Developer and Reference Guide for information on specific APIs.
2. API Explorer
3. 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:

1. 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 user phone number without extension number

platform.authorize("myUsername", nil, "myPassword")

# Initialize using main phone number and extension number

platform.authorize("myUsername", "myExtension", "myPassword")

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

Change Log

• 2015-05-31: 0.1.2
  • Add Ruby 1.8.7 support
  • Add CI for Ruby 2.2.0 & 2.1.6: 2.2.2, 2.2.0, 2.1.6, 2.1.0, 2.0.0, 1.9.3, 1.8.7
• 2015-05-31: 0.1.1
  • Add Ruby 2.2.2 support
• 2015-05-31: 0.1.0
  • Add OAuth token refresh
  • Add OAuth2::AccessToken support
  • Add Code Climate hook
• 2015-05-19: 0.0.4
  • Add RingCentralSdk::Helpers::Request as request helpers base class
  • Add sdk.request() and platform.request() methods added to handle request helpers
  • Fax helper uses file mime-type in preference to generic octet-stream
  • Initial mkdocs and Read the Docs effort added
  • Travis CI and Coveralls hooks added
• 2015-05-14: 0.0.3
  • First public release
• 2015-03-08: 0.0.2
  • Convert methods from camelCase to under_scores
• 2015-03-07: 0.0.1
  • Initial release

Links

Project Repo

• https://github.com/grokify/ringcentral-sdk-ruby

RingCentral API Docs

• https://developers.ringcentral.com/library.html

RingCentral API Explorer

• http://ringcentral.github.io/api-explorer

RingCentral Official SDKs

• https://github.com/ringcentral

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 for details.

RingCentral SDK © 2015 by John Wang