Skip to main content
REST API - Devices - Overview

A Device represents different addresses through which a User may be contacted. Devices are represented where possible as Uniform Resource Identifiers (URI) where the type is determined by the URI scheme. Examples of URI schemes include: mailto:, Skype:, and ribbit:.

Certain Device types can also be configured as:

  • Inbound Devices are those that can be linked to the Ribbit platform so that calls to that device can be received by Ribbit applications on behalf of the user. Examples of inbound devices are PSTNs (the regular Public Service Telephone Network) and mobile phones.

    Incoming Calls can be forwarded by using Conditional Call Forwarding (CCF), thus allowing mobile phones to be linked to the Ribbit Platform. Incoming calls are then routed to Ribbit if the mobile phone is not answered and the mobile phone voicemail is no longer used. This feature allows developers to link mobile phones to their Applications.

    If Inbound Devices are configured as 'AutoAnswer = true', then calls will be answered automatically by the Ribbit platform without call forwarding or voicemail. This allows developers to take control of the calls, and they can then choose to write their own custom IVR applications (e.g. voicemail) to drive the calls.

  • Outbound Devices allow Applications to place calls to any phone number or online Application. In other words, an outbound device is one on which a Ribbit application can reach a Ribbit User. Examples include: Ribbit Flash Phone™, PSTN, Mobile, GoogleTalk, Skype.

    • Devices on which a user can receive calls originated from Ribbit
    • All inbound Devices are by default outbound Devices as well
  • Purpose Numbers are specially assigned numbers from the Ribbit system that allow the outside world to call a designated User in the Ribbit system. Any Ribbit application can retrieve a list of available purpose numbers by specifying a count.

  • Notifications can be configured to notify users in the event of new voicemails or missed calls:

    • Devices on which you can receive voicemail notifications
    • Mobile Devices via Short Message Service (SMS), e.g. text messages)
    • Email Device via email
    • Instant Messaging (IM) Devices via IM text

    Notifications include the message transcription and the message envelope information such as the caller name, number, and the time of the call.

The following Device address formats are supported:

Device Type
Example
In Device
Out Device
Notifications
EMAIL address
mailto:foo@bar.com
 X X √
PSTN / Mobile numbers
tel:14089107689
 √ √ √
XMPP addresses
XMPP:foo@gmail.com
 X √ √
SKYPE names
skype:foobar
 X√  √
Ribbit numbers (Purpose Numbers)
ribbit:14153760712
 √X
X
 
REST API - Devices - Methods

 

Method
Resource
Response
Notes
GET /devices/<guid> (200) Collection of DevicesRetrieve all Devices for a specified User.
POST
/devices/<guid>
(201) Location of new Device
Create a Device.
GET
/devices/<guid>/<devId>
(200) Single Device entry
Retrieve details for a single Device for the specified User.
PUT
/devices/<guid>/<devId>
(202) Modified Device resource
Update Device details. Note: Purpose Numbers can not be updated.
DELETE
/devices/<guid>/<devId>
(204) No content
Delete a Device such as tel, Skype.
GET
/devices/<guid>/<purpose number>
(200) Purpose Number
Retrieves details for the specified Purpose Number.
REST API - Devices - Properties
Name
Methods
Value
Notes
idGET, POST, PUT
string (req) Unique Device identifier prefixed by schema to reflect Device type (e.g. mailto:foo@bar.com).
nameGET, PUT, POST
string (req) Name to refer to this Device.
verifiedGETboolean (opt) This Device has been verified. For example, in the case of telephone numbers the device has passed a ccfCheck test.
callmeGET, PUT, POST   
boolean (opt) If this flag is set to true this Device can be used as an inbound "CallMe" number.
carrierGET, POST, PUTstring (opt) ID of the carrier for this Device (e.g. Google, AT&T, etc.).
callbackreachmeGET, PUT, POST boolean (opt) This Device can be used as a "reach me" number.
sharedGET, PUT, POST boolean
(opt) This Device is shared by other people.
ringstatusGET, PUT, POST boolean
(opt) Ring this Device when an inbound call arrives.
notifyvmGET, PUT, POST boolean
(opt) Send notifications to this Device on new voicemails.
notifytranscriptionGET, PUT, POST boolean
(opt) Send notifications to this Device on new transcriptions.
notifymissedcallGET, PUT, POST boolean
(opt) Send notifications to this Device on missed calls.
keyGET, PUT, POST string
(opt) Security access code to enable this Device.
label
GET, PUT, POST string
(opt) A label for the Device.
attachmessage
GET, PUT, POST boolean 

(opt) Send voicemail file as an attachment to email notifications.

usewave
GET, PUT, POST boolean 
(opt) Send voicemail files in WAV format rather than MP3.
mailtext
GET, PUT, POST boolean
(opt) Include transcribed message content in notifications if available.
showcalled
GET, PUT, POST boolean
(opt) Show the callerID of the person called in the notification.
verifyBy
POST, PUT
string

(opt) Initiate a test to verify this Device. Currently supported tests include ccfCheck for mobiles and mailCheck for email addresses.

allowCCFGET, PUT, POSTboolean(opt) If true this device may be used for CCF.  In the US, the following carriers can be CCF to the Ribbit platform:  Alltel, AT&T, Sprint / Nextel, T-mobile, Verizon
autoAnswerGET, PUT, POSTboolean(opt) If true the device will be answered automatically for cusom IVR appliations and not be forwarded to voicemail or Outbound devices
answersecurity
POST, PUT
boolean
 
REST API - Devices - Examples

Retrieving all Devices for a Given User

A GET against a User's Device collection will return all the Devices configured for this User.  
<< GET /rest/1.0/devices/9764e31d-65bf-4b2a-a3f1-8b0cdad6e8d6

>> 200 OK
   { entry : [
     {"id": "skype:foobar", "label":"skype", "carrier":"Skype" },
     {"id": "tel:16504568790", "label":"cell phone", "carrier":"ATT", "ccfCheck":"true"},
     {"id": "xmpp:foo@bar.com", "label":"gtalk", "carrier":"Google"},
     {"id": "mailto:foo@bar.com", "label":"email", "mailCheck":"true"}
     {"id": "ribbit:14089107654", "label":"purpose number","carrier":"PSTN","verfied":true}
   ] }

Adding a New Telephone Number

To add a new telephone number, the number must be POSTed as the ID with the schema prefix "tel:". The  callme and ringstatus properties  must both be set to "true" for the Device to act as an "inbound" Device which will ring whenever calls are received on the platform. The Location header will contain the GUID and the phone number.

Note: Phone numbers must have "tel:" before the phone number, and should be fully normalised by including the country code as a prefix 

<< POST /rest/1.0/devices/9764e31d-65bf-4b2a-a3f1-8b0cdad6e8d6
   { "id":"tel:16502346754", "label":"cell phone", "callme":true, "ringstatus":true}

>> 201 CREATED
   LOCATION: http://myhost.com/rest/1.0/devices/9764e31d-65bf-4b2a-a3f1-8b0cdad6e8d6/tel:16502346754

Adding an Inbound SMS Device

Use the following example to add a new inbound SMS Device.

<< POST /rest/1.0/devices/9764e31d-65bf-4b2a-a3f1-8b0cdad6e8d6
   { "id":"@sms/uk","name":"inboundSMS"}                  

>> 201 CREATED
   LOCATION: http://myhost.com/rest/1.0/devices/9764e31d-65bf-4b2a-a3f1-8b0cdad6e8d6/sms:44321321321321234

Adding an In Device

Use the following example to add a new inbound Device.

Note: May fail if not unique.

<< POST /rest/1.0/devices/9764e31d-65bf-4b2a-a3f1-8b0cdad6e8d6
   { "id":"tel:16502346754", "label":"cell phone", "callme":true, "ringstatus":true}                 

>> 201 CREATED
   LOCATION: http://myhost.com/rest/1.0/devices/9764e31d-65bf-4b2a-a3f1-8b0cdad6e8d6/tel:16502346754

Adding an Out Device

Use the following example to add a new outbound Device.

<< POST /rest/1.0/devices/9764e31d-65bf-4b2a-a3f1-8b0cdad6e8d6
   { "id":"tel:16502346754", "label":"cell phone", "callbackreachme":true, "ringstatus":true}                  

>> 201 CREATED
   LOCATION: http://myhost.com/rest/1.0/devices/9764e31d-65bf-4b2a-a3f1-8b0cdad6e8d6/

Removing a Device

The DELETE method may be used to remove a Device. Deleted purpose or SMS numbers will no longer incur charges. The Removed header will contain the deleted Device information.

<< DELETE /rest/1.0/devices/9764e31d-65bf-4b2a-a3f1-8b0cdad6e8d6/tel:15108768904

>> 204 Succeeded 
   REMOVED: /rest/1.0/devices/9764e31d-65bf-4b2a-a3f1-8b0cdad6e8d6/tel:15108768904

Verifying CCF for a Mobile Number

Before verifying Conditional Call Forwarding (CCF) on a device users should complete the following steps:

  • Make sure that the mobile device has been created using a POST request
  • Configure CCF on the mobile device

Ribbit is then able to verify this has been configured correctly by calling the mobile number to check that the call is then routed to Ribbit's voicemail service. To initiate this test a verifyBy:ccfCheck may be PUT against the corresponding device. When this call is triggered it is important the call is not answered and left to forward to voicemail otherwise the test will fail.

The verified property in the Response will be "false", but once verification completes a GET against the device will confirm that the test passed and the verified property will be set to "true". 

<< PUT /rest/1.0/devices/9764e31d-65bf-4b2a-a3f1-8b0cdad6e8d6/tel:14153459807
   { "verifyBy":"ccfCheck" }

>> 200 OK
   { id:"tel:14153459807" , verified:false}

Configuring an Auto Answer IVR Device

To configure a device for use in an IVR application  'autoAnswer' must be true and allowCCF must be false. When Devices are answered automatically by the platform it is the responsibilty of the application to play appropriate messages and ringtones to the caller. For more information on IVR see - [link here]


<< PUT /rest/1.0/devices/9764e31d-65bf-4b2a-a3f1-8b0cdad6e8d6/tel:140811111111
   { "autoAnswer":true, "allowCCF":false }

>> 200 OK

Requesting a Purpose Number

POSTing requests to a User's Device collection may be used request dedicated inbound Purpose Numbers for a given user. Purpose Numbers are always displayed with "ribbit" before the phone number, e.g. ribbit:14156783456. 

Ribbit provides a pool of telephone numbers which can be assigned to Ribbit users to accept inbound calls onto the platform for various purposes (Purpose Numbers). These numbers may be requested by creating a Device with an '@purpose' ID. The real number that has been assigned will be returned in the response location ("@purpose/usa", "@purpose/uk"). 

Note: There may be a charge incurred for requesting a Purpose Number.

In the following example a USA Purpose Number was requested. 

POST /rest/1.0/devices/9764e31d-65bf-4b2a-a3f1-8b0cdad6e8d6
   { "id":"@purpose/usa" }

>> 201 CREATED
   LOCATION: http://myhost.com/rest/1.0/devices/9764e31d-65bf-4b2a-a3f1-8b0cdad6e8d6/ribbit:14153760712 
   ] }

In the following example a UK Purpose Number was requested. UK phone numbers must start with "44" followed by the ten-digit phone number. The first digit of the phone number cannot be a "7" as this is reserved for mobile phone numbers.

POST /rest/1.0/devices/9764e31d-65bf-4b2a-a3f1-8b0cdad6e8d6
   { "id":"@purpose/uk" }

>> 201 CREATED
   LOCATION: http://myhost.com/rest/1.0/devices/9764e31d-65bf-4b2a-a3f1-8b0cdad6e8d6/ribbit:445678932145 
   ] }

Retrieving a Purpose Number

A GET against a user's Device for will return all the purpose numbers configured for this User. Purpose Numbers are returned with a "ribbit:" before the phone number.  

<< GET /rest/1.0/devices/9764e31d-65bf-4b2a-a3f1-8b0cdad6e8d6/ribbit:14153760712                  

>> 200 OK
   {entry : [
    { "id":"ribbit:14153760712","name":"purpose number","carrier":"PSTN","verified":true}

Retrieving a Purpose Number List

A GET against a user's Device will return a list of purpose numbers configured for this User. The following code sample returns a list of two purpose numbers.

<< GET /devices/@purpose?filterBy=tag,id&filterOp=all,startsWith&filterValue=SMS,121&maxResults=2 

>> 200 OK
   {entry : [ {"id": "12112381321"}, {"id": "12125552368") ] }

Filtering a Purpose Number List

filterBy value
Supported filterOp value
Default filterOp value
idstartsWith, contains, equals, endsWith contains
tagany, all any
locationequals  equals
supplierequals  equals
  • filterValue is the value to be queried.
  • Tag values are free text and may include: country codes (UK, US, etc), SMS, FREEFONE, PREMIUM, etc. For tag filtering, multiple values can be provided separately by commas.
  • "filterOp" indicates whether all or any tags should be present. For instance, "filterBy=tag&filterOp=all&filterValue=sms,premium", returns a list of numbers that have both SMS and premium tags.
  • "maxResults" query parameter is optional and the default value is 10.
    • If multiple comma seperated field names are specified then the "filterOp" and "filterValue" should be similarly: "?filterBy=id,tag&filterOp=startsWith,equals&filterValue=tel:44,freephone", which should return all UK numbers that are freephone.

Your application can also retrieve purpose number counts. To retrieve multiple counts, separate filterValue with commas. For instance, the following code snippet returns two counts: one for numbers with SMS and premium tags, and another one for numbers with only the SMS tag.
<< GET /devices/@purpose/counts?filterValue=SMS%2BPREMIUM,SMS  

>> 200 OK
   {entry : [ {"filterValue": "SMS+PREMIUM", "count":1}, {"filterValue": "SMS", "count":2) ] }