[ Build Status ][travis]

restcomm-ruby

A module for using the Restcomm REST API and generating valid RCML. Click here to read the full documentation.

Installation

To install using Bundler grab the latest stable version:

gem 'restcomm-ruby', '~> 1.2.0'

To manually install restcomm-ruby via Rubygems simply gem install:

gem install restcomm-ruby

To build and install the development branch yourself from the latest source:

git clone [email protected]:Mobicents/restcomm-ruby.git
cd restcomm-ruby
make install

Getting Started With REST

Setup Work

require 'rubygems' # not necessary with ruby 1.9 but included for completeness
require 'restcomm-ruby'

# put your own credentials here
account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
host = 'IP_ADDRESS_RESTCOMM_INSTANCE'

# set up a client to talk to the Restcomm REST API
@client = Restcomm::REST::Client.new account_sid, auth_token, host



# and then you can create a new client without parameters
@client = Restcomm::REST::Client.new

Send an SMS

@client.messages.create(
  from: '+14159341234',
  to: '+16105557069',
  body: 'Hey there!'
)

Do Some Stuff With Calls

# make a new outgoing call
@call = @client.calls.create(
  from: 'sip:+14159341234',
  to: 'sip:+18004567890',
  url: 'http://example.com/call-handler'
)

# hangup a ringing call, but don't touch it if it's connected
@call.cancel

# if you have the call sid, you can fetch a call object via:
@call = @client.calls.get('CA386025c9bf5d6052a1d1ea42b4d16662')

# redirect an in-progress call
@call.redirect_to('http://example.com/call-redirect')

# hangup a call, no matter whether it is ringing or connected
@call.hangup

List Calls after a certain time

# list calls made or received on or after May 13, 2013
@client.calls.list("start_time>" => "2013-05-13") # Notice we omit the "=" in the "start_time>=" parameter because it is automatically added

Getting Started With RCML

RCML support is based on the Builder library. You can construct a RCML response like this:

require 'rubygems' # not necessary with ruby 1.9 but included for completeness
require 'restcomm-ruby'

# build up a response
response = Restcomm::RCML::Response.new do |r|
  r.Say 'hello there', voice: 'alice'
  r.Dial callerId: '+14159992222' do |d|
    d.Client 'jenny'
  end
end

# print the result
puts response.text

This will print the following (except for the whitespace):

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say voice="alice">hello there</Say>
  <Dial callerId="+14159992222">
    <Client>jenny</Client>
  </Dial>
</Response>

Supported Ruby Versions

This library supports and is [tested against][travis] the following Ruby implementations:

Ruby 1.9.3 and above
JRuby
Rubinius

More Information

There are more detailed examples in the included examples directory. Also for thoose upgrading, the upgrade guide is available in the restcomm-ruby github wiki.