WHATS NEW IN REST 1.4

Developers may now manage and receive webhook notifications for many kinds of platform events including:

• New Calls
• Active Call Status Changes
• New Voicemail Messages
• New Voicemail Transcriptions
• New SMS Messages

The URL to which these notifications should be sent may be configured by a PUT against a new application resource.

For example:

 To GET Application Details:
  << GET/apps/myDomain:myAppName 

To Update the Notification URL: 
    << PUT/apps/mydomain:myappName
        {"notificationURL":<url>}

When Receiving an Event Notification:
  << POST <notificationURL>
     Json={ "type":"cc_call_vmpickup",
          "time":"2009-03-24T19:24:24Z",
          "resource":"http://rest.ribbit.com/rest/1.0/calls/67be2a0c-6c65-102c-a24a-00188b741119/1234",
           "params":{
              "callid":2608143,"guid":"cce3cd2d-190c-454a-a4a5-42f2ea3e28ab",
              "source":"tel:restQA031009-001@mailinator.com",  
              "dest":"tel:16503355954"}
       } }

All Applications and Users now exist within developer 'Domains' which define a unique user and application namespace for the developer such that all users in a Domain may access all applications in the same Domain.  By consequence all AppIDs now should be formatted as <domainID>:<appName>. Furthermore all <guid>s have now migrated to a new 16 digit hex format. For example the full record for a user may be retrieved by:

Get User from Login:
  << GET users?filterBy=login&filterValue=mylogin 

Get User from <guid>:
  << GET users/67be2a0c-6c65-102c-a24a-00188b741119

It is now possible to do 2-way SMS messaging via Rest (for UK SMS numbers only). New SMS numbers may requested via a POST to a Users Devices collection. Messages sent to this number will then be processed by the Ribbit platform and can generate appropriate notifications to other devices as configured for the User. SMS messages are also logged in the user's messages log and may be retrieved with a GET to their Message collection.
For example:

To request a new UK SMS number:
  << POST <path>/devices/<guid>
     { "id":"@SMS/GBR" }

Once Conditional Call Forwarding (CCF) has been enabled on a users mobile device, developers may verified everything has been configured correctly by a PUT against the corresponding device. This will trigger a call from Ribbit to this device, which in turn should forward the call to the users voicemail account. It is important that this call is not answered by the user.

If successful the device may be considered verified as belonging to this users. Refer to the following example for more details on how to configure Conditional Call Forwarding on mobiles:

To initiate a CCF test:
<< PUT devices/<guid>/tel:<number>
     { "verifyBy":"ccfTest" }

Message and Call Logs

Call and Message Logs may now be retrieved via REST using GET requests against the corresponding Message and Call collections.  In addition pagination is now supported on Call and Message log requests using the same conventions defined by OpenSearch. For message retrieval filtering on the response based on whether the messages are Read or Unread (new) is also supported.
For example:

To Get only new messages: 
  << GET  messages/<guid>?filterBy=read&filterValue=new

To Get only calls log entries between 20-30:  
  << GET  calls/<guid>?startIndex=20&count=10

Developers can request local purpose numbers for use in the UK as well as in the US.
For example:

Request UK Purpose Number:
  << POST devices/<guid>
     { "id":"@purpose/USA" } 

Request UK purpose Number
  << POST devices/<guid>
     { "id":"@purpose/GBR" }

Login:
  << POST /login
     oauth_consumer_key=<consumerKey>,
     x_auth_username=<login>,
     x_auth_password=<password>,
     oauth_nonce="nonce",
     oauth_signature_method="HMAC-SHA1",
     oauth_timestamp=<timestamp>,
     oauth_signature=<request signed with oauth consumer_secret>

BillingAccounts

The platform has been significantly upgraded to introduce a new billing system which is capable of a wide variety of subscription and pay as you go payment plans. Many activities that were provided free of charge now may incur charges if the appropriate billing plans are not enabled for a given user. These activities include

• Making calls
• Sending SMS messages
• Provisioning new Users
• Requesting purpose and SMS numbers.

Further details of the costs of these activities and instructions on how to configure accounts, view bills and claim a special offer of $25 free credit for new developers can be found on the developer portal.

NOTE: For the duration of the REST Beta trial we are offering VIP account plans to invited developers under which Ribbit will continue to waive all charges for use of the REST API, including those mentioned above. This will continue until further notices.   

To configure a user's account an appropriate billing account ID must be PUT or POSTed to the target user resource. This request will only be accepted if the billing account ID belongs to the authorized user making the request or else belongs to the developer that created the application being used to make this request. 

Assign Account ID:
<< PUT /users/<guid>
    { "accountId":12345 }

GET User details:
<< GET /users/<guid>
    { "id":<guid> "login":"mylogin", "createdOn":<date>, "createdWith":<appId>, "accountId":12345 }