RingCentral SDK for Ruby

Gem Version Build Status Coverage Status Dependency Status Code Climate Scrutinizer Code Quality Downloads Docs Docs License

Table of contents

  1. Overview
  2. Documentation
  3. Installation
  4. Usage
    1. Instantiation
    2. Authorization
    3. Password Grant
    4. Authorization Code Grant
    5. Token Reuse
    6. API Requests
    7. Generic HTTP Requests
    8. SMS Example
    9. Fax Example
    10. Advanced Use Cases
  5. Supported Ruby Versions
  6. Releases
    1. Versioning
    2. Change Log
  7. Links
  8. Contributions
  9. License

Overview

:warning: YOU MUST HAVE A RINGCENTRAL ACCOUNT TO USE THE API :warning:
Get an account at: https://developers.ringcentral.com/login.html

www.ringcentral.com - RingCentral Complete Cloud Communications System.

A library for using the RingCentral REST API. Click here to read the full documentation.

Documentation

Full documentation and resources are available at:

  1. Ruby SDK Developer Guide - Read the Docs
  2. Ruby SDK Reference Guide - RubyDoc.info

For API information, see the official RingCentral resources:

  1. API Developer and Reference Guide
  2. API Explorer
  3. CTI Tutorial

Installation

Via Bundler

Add 'ringcentral_sdk' to Gemfile and then run bundle:

$ echo "gem 'ringcentral_sdk'" >> Gemfile
$ bundle

Via RubyGems

$ gem install ringcentral_sdk

Usage

Instantiation and Authorization

How you instantiate the SDK can depend on whether you use OAuth 2.0 password grant or the authorization code grant which are both described here.

It is also necessary to specify your RingCentral API end point URL which are included constants:

  • RingCentralSdk::RC_SERVER_PRODUCTION
  • RingCentralSdk::RC_SERVER_SANDBOX

Password Grant

The OAuth 2.0 resource owner password grant flow is designed for server applications where the app and resource owners are the same.

require 'ringcentral_sdk'

# Returns RingCentralSdk::Platform instance
client = RingCentralSdk::REST::Client.new(
  'myAppKey',
  'myAppSecret',
  RingCentralSdk::RC_SERVER_SANDBOX
)

# extension will default to company admin extension if not provided
client.authorize_password('myUsername', 'myExtension', 'myPassword')

Authorization Code Grant

The OAuth 2.0 authorization code grant is designed for where authorization needs to be granted by a 3rd party resource owner.

Using the default authorization URL:

# Initialize SDK with OAuth redirect URI
client = RingCentralSdk::REST::Client.new(
  'myAppKey',
  'myAppSecret',
  RingCentralSdk::RC_SERVER_SANDBOX,
  redirect_uri: 'http://example.com/oauth'
)

# Retrieve OAuth authorize url using default redirect URL
auth_url = client.authorize_url()

On your redirect page, you can exchange your authorization code for an access token using the following:

code  = params['code'] # e.g. using Sinatra to retrieve code param in Redirect URI
client.authorize_code(code)

More information on the authorization code flow:

  1. Full documentation
  2. Sinatra example

Token Reuse

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:

# Access `OAuth2::AccessToken` object as hash
token_hash = client.token.to_hash

You can reload the token hash in another instance of the SDK as follows:

# set_token() accepts a hash or OAuth2::AccessToken object
client.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

API requests can be made via the included Faraday client or RingCentralSdk::Helpers::Request subclasses. These are described below.

Generic HTTP Requests

To make generic API requests, use included Faraday client which can be accessed via client.http. The client automatically adds the correct access token to the HTTP request and handles OAuth token refresh using the OAuth gem.

This is useful to access many API endpoints which do not have custom wrappers and for debugging purposes.

http = client.http

SMS Example

client.messages.sms.create(
  from: '+16505551212',
  to: '+14155551212',
  text: 'Hi there!'
)

Fax Example

Fax files:

client.messages.fax.create(
  to: '+14155551212',
  coverPageText: 'Hi there!',
  files: ['/path/to/myfile.pdf']
)

Fax text:

client.messages.fax.create(
  to: '+14155551212',
  coverPageText: 'Hi there!',
  text: 'Hi there!'
)

Subscription Example

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

# Create an observer object
class MyObserver
  def update(message)
    puts "Subscription Message Received"
    puts JSON.dump(message)
  end
end

# Create an observable subscription and add your observer
sub = client.create_subscription()
sub.add_observer(MyObserver.new())

# Subscribe to an arbitrary number of event filters
sub.subscribe(['/restapi/v1.0/account/~/extension/~/presence'])

# End the subscription
sub.destroy()

Advanced Use Cases

  1. Subscribing to All Extensions
  2. Managing Call Queue Member Status

Supported Ruby Versions

This library is tested against this list of Ruby implementations.

Releases

Releases with release notes are availabe on GitHub releases. Release notes include a high level description of the release as well as lists of non-breaking and breaking changes.

Versioning

  • Versions 1.0.0 and above follow semantic versioning. Breaking changes will be indicated by a change in major version.
  • Versions below 1.0.0 are in active development. During initial development (Version 0.x.x), minor version changes will indicate either substantial feature inclusion or breaking changes.

Change Log

See CHANGELOG.md

Links

Project Repo

RingCentral API Docs

RingCentral API Explorer

RingCentral Official SDKs

Contributing

  1. Fork it ( http://github.com/grokify/ringcentral-sdk-ruby/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

License

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

RingCentral SDK © 2015-2016 by John Wang