sdk-ruby

SDK in Ruby for CALLR API

Quick start

Install via Rubygems

gem install callr

Or get sources from Github

Initialize your code

Gem

require 'callr'
api = CALLR::Api.new('login', 'password')

Source

load 'lib/callr.rb'
api = CALLR::Api.new('login', 'password')

Exception management

begin
  api = CALLR::Api.new('login', 'password')
  api.call('sms.send', 'SMS')
rescue CALLR::CallrException, CALLR::CallrLocalException => e
  puts "ERROR: #{e.code}"
  puts "MESSAGE: #{e.msg}"
  puts "DATA: ", e.data
end

Usage

login as :

api.set_login_as('user', 'foo') # login as user foo
api.set_login_as('account', 'foo') # login as account foo
api.set_login_as(nil, nil) # Remove login-as

Sending SMS

Without options

result = api.call('sms.send', 'SMS', '+33123456789', 'Hello world!', nil)

Method

• sms.send

Personalized sender

Your sender must have been authorized and respect the sms_sender format

result = api.call('sms.send', 'Your Brand', '+33123456789', 'Hello world!', nil)

Method

• sms.send

If you want to receive replies, do not set a sender - we will automatically use a shortcode

result = api.call('sms.send', '', '+33123456789', 'Hello world!', nil)

Method

• sms.send

Force GSM encoding

optionSMS = { :force_encoding => 'GSM' }

result = api.call('sms.send', '', '+33123456789', 'Hello world!', optionSMS)

Method

• sms.send

Objects

• SMS.Options

Long SMS (availability depends on carrier)

text = 'Some super mega ultra long text to test message longer than 160 characters ' +
           'Some super mega ultra long text to test message longer than 160 characters ' +
           'Some super mega ultra long text to test message longer than 160 characters'
result = api.call('sms.send', 'SMS', '+33123456789', text, nil)

Method

• sms.send

Specify your SMS nature (alerting or marketing)

optionSMS = { :nature => 'ALERTING' }

result = api.call('sms.send', 'SMS', '+33123456789', 'Hello world!', optionSMS)

Method

• sms.send

Objects

• SMS.Options

Custom data

optionSMS = { :user_data => '42' }

result = api.call('sms.send', 'SMS', '+33123456789', 'Hello world!', optionSMS)

Method

• sms.send

Objects

• SMS.Options

Delivery Notification - set URL to receive notifications

optionSMS = {
    :push_dlr_enabled => true,
    :push_dlr_url => 'http://yourdomain.com/push_delivery_path',
    # :push_dlr_url_auth => 'login:password' # needed if you use Basic HTTP Authentication
}

result = api.call('sms.send', 'SMS', '+33123456789', 'Hello world!', optionSMS)

Method

• sms.send

Objects

• SMS.Options

Inbound SMS - set URL to receive inbound messages (MO) and replies

Do not set a sender if you want to receive replies - we will automatically use a shortcode.

optionSMS = {
    :push_mo_enabled => true,
    :push_mo_url => 'http://yourdomain.com/mo_delivery_path',
    # :push_mo_url_auth => 'login:password' # needed if you use Basic HTTP Authentication
}

result = api.call('sms.send', '', '+33123456789', 'Hello world!', optionSMS)

Method

• sms.send

Objects

• SMS.Options

Get an SMS

result = api.call('sms.get', 'SMSHASH')

Method

• sms.get

Objects

• SMS

SMS Global Settings

Get settings

result = api.call('sms.get_settings')

Method

• sms.get_settings

Objects

• SMS.settings

Set settings

Add options that you want to change in the object

settings = {
    :push_dlr_enabled => true,
    :push_dlr_url => 'http://yourdomain.com/push_delivery_path',
    :push_mo_enabled => true,
    :push_mo_url => 'http://yourdomain.com/mo_delivery_path'
}

result = api.call('sms.set_settings', settings)

Returns the updated settings.

Method

• sms.set_settings

Objects

• SMS.settings

---

REALTIME

Create a REALTIME app with a callback URL

options = {
    :url => 'http://yourdomain.com/realtime_callback_url'
}

result = api.call('apps.create', 'REALTIME10', 'Your app name', options)

Method

• apps.create

Objects

• REALTIME10
• App

Start a REALTIME outbound call

target = {
    :number => '+33132456789',
    :timeout => 30
}

callOptions = {
    :cdr_field => '42',
    :cli => 'BLOCKED'
}

result = api.call('dialr/call.realtime', 'appHash', target, callOptions)

Method

• dialr/call.realtime

Objects

• Target
• REALTIME10.Call.Options

Inbound Calls - Assign a phone number to a REALTIME app

result = api.call('apps.assign_did', 'appHash', 'DID ID')

Method

• apps.assign_did

Objects

• App
• DID

---

DIDs

List available countries with DID availability

result = api.call('did/areacode.countries')

Method

• did/areacode.countries

Objects

• DID.Country

Get area codes available for a specific country and DID type

result = api.call('did/areacode.get_list', 'US', nil)

Method

• did/areacode.get_list

Objects

• DID.AreaCode

Get DID types available for a specific country

result = api.call('did/areacode.types', 'US')

Method

• did/areacode.types

Objects

• DID.Type

Buy a DID (after a reserve)

result = api.call('did/store.buy_order', 'OrderToken')

Method

• did/store.buy_order

Objects

• DID.Store.BuyStatus

Cancel your order (after a reserve)

result = api.call('did/store.cancel_order', 'OrderToken')

Method

• did/store.cancel_order

Cancel a DID subscription

result = api.call('did/store.cancel_subscription', 'DID ID')

Method

• did/store.cancel_subscription

View your store quota status

result = api.call('did/store.get_quota_status')

Method

• did/store.get_quota_status

Objects

• DID.Store.QuotaStatus

Get a quote without reserving a DID

result = api.call('did/store.get_quote', 0, 'GOLD', 1)

Method

• did/store.get_quote

*Objects/

• DID.Store.Quote

Reserve a DID

result = api.call('did/store.reserve', 0, 'GOLD', 1, 'RANDOM')

Method

• did/store.reserve

Objects

• DID.Store.Reservation

View your order

result = api.call('did/store.view_order', 'OrderToken')

Method

• did/store.buy_order

Objects

• DID.Store.Reservation

---

Conferencing

Create a conference room

params = { :open => true }
access = []

result = api.call('conference/10.create_room', 'room name', params, access)

Method

• conference/10.create_room

Objects

• CONFERENCE10
• CONFERENCE10.Room.Access

Assign a DID to a room

result = api.call('conference/10.assign_did', 'Room ID', 'DID ID')

Method

• conference/10.assign_did

Create a PIN protected conference room

params = { :open => true }
access = [
    { :pin => '1234', :level => 'GUEST' },
    { :pin => '4321', :level => 'ADMIN', :phone_number => '+33123456789' }
]

result = api.call('conference/10.create_room', 'room name', params, access)

Method

• conference/10.create_room

Objects

• CONFERENCE10
• CONFERENCE10.Room.Access

Call a room access

result = api.call('conference/10.call_room_access', 'Room Access ID', 'BLOCKED', true)

Method

• conference/10.call_room_access

---

Media

List your medias

result = api.call('media/library.get_list', nil)

Method

• media/library.get_list

Create an empty media

result = api.call('media/library.create', 'name')

Method

• media/library.create

Upload a media

media_id = 0

result = api.call('media/library.set_content', media_id, 'text', 'base64_audio_data')

Method

• media/library.set_content

Use Text-to-Speech

media_id = 0

result = api.call('media/tts.set_content', media_id, 'Hello world!', 'TTS-EN-GB_SERENA', nil)

Method

• media/tts.set_content

---

CDR

Get inbound or outbound CDRs

from = 'YYYY-MM-DD HH:MM:SS'
to = 'YYYY-MM-DD HH:MM:SS'

result = api.call('cdr.get', 'OUT', from, to, nil, nil)

Method

• cdr.get

Objects

• CDR.In
• CDR.Out

---

SENDR

Broadcast messages to a target (BETA)

target = {
    :number => '+33123456789',
    :timeout => 30
}

messages = [131, 132, 'TTS|TTS_EN-GB_SERENA|Hello world! how are you ? I hope you enjoy this call. good bye.']

options = {
    :cdr_field => 'userData',
    :cli => 'BLOCKED',
    :loop => 2
}

result = api.call('sendr/simple.broadcast_1', target, messages, options)

Without options

target = {
    :number => '+33123456789',
    :timeout => 30
}

messages = [131, 132, 134]

result = api.call('sendr/simple.broadcast_1', target, messages, nil)

Method

• sendr/simple.broadcast_1

Objects

• Target
• SENDR.Simple.Broadcast1.Options