Updating RingCentral User Extension Greetings using the REST API and Ruby

RingCentral has a very useful ability to customize voicemail and custom greetings via the Online Account Portal (https://service.ringcentral.com). We are excited to bring more of the rich capabilities of the portal to developers which have included our caller ID API, forwarding number API, department API and presence APIs. In this article, we’ll discuss updating user extension greetings via the REST API.

Voicemail and Custom Greetings

User extension greetings are custom recordings that are played back to users when dialing a user extension. These recordings can be updated in the Online Account Portal and are covered in the following Knowledgebase articles for reference:

• Setting Up a Custom Voicemail Greeting on a User Extension
• Adding Custom Greetings to a User Extension

Updating the User Extension Greetings via API

Using the API, you can update both built-in answering rules and custom answering rules.

There are two steps to updating the user extension greetings via API:

1. Retrieving a list of Answering Rules
2. Uploading a recorded greeting media file to the desired Answering Rule

We’ll cover both of these using the RingCentral REST API as well as the community Ruby SDK. For these specific APIs, see the:

RingCentral API Reference: Answering Rules Section

Retrieving a List of Answering Rules

The RingCentral extension answering rule list endpoint is used to retrieve a list of answering rules with associated ids.

account/{accountId}/extension/{extensionId}/answering-rule

HTTP Request

When making an HTTP call, the OAuth 2.0 access token must be included either in the Authorization HTTP header or in the access_token query parameter with the URL above. Here is an example HTTP request using the Authorization header:

GET /restapi/v1.0/account/1455897004/extension/1455897004/answering-rule HTTP/1.1
Authorization: Bearer U0pDMDFQMDFQQVMwMXxBQURIZjAzWFFySGpMMGxPaEhMaFR0

Ruby SDK Request

Using the community Ruby SDK, you can retrieve this list with the following:

require 'ringcentral_sdk'
# Instantiate the client
client = RingCentralSdk::REST::Client do |config|
  # your config parameters
end
# Retrieve the answering rule list
req = client.http.get 'account/~/extension/~/answering-rule'

API Response

This will return a list of answering rules in similar to the following:

{
  "uri" : "https.../restapi/v1.0/account/12843281004/extension/12843281004/answering-rule?page=1&perPage=100",
  "records" : [ {
    "uri" : "https.../restapi/v1.0/account/12843281004/extension/12843281004/answering-rule/business-hours-rule",
    "id" : "business-hours-rule",
    "type" : "BusinessHours",
    "enabled" : true
  }, {
    "uri" : "https.../restapi/v1.0/account/12843281004/extension/12843281004/answering-rule/24494102004",
    "id" : "24494102004",
    "type" : "Custom",
    "name" : "My Rule # 1",
    "enabled" : true
  }, {
    "uri" : "https.../restapi/v1.0/account/12843281004/extension/12843281004/answering-rule/after-hours-rule",
    "id" : "after-hours-rule",
    "type" : "AfterHours",
    "enabled" : true
  } ],
  "paging" : {
    "page" : 1,
    "totalPages" : 1,
    "perPage" : 100,
    "totalElements" : 3,
    "pageStart" : 0,
    "pageEnd" : 2
  },
  "navigation" : {
    "firstPage" : {
      "uri" : "https.../restapi/v1.0/account/12843281004/extension/12843281004/answering-rule?page=1&perPage=100"
    },
    "lastPage" : {
      "uri" : "https.../restapi/v1.0/account/12843281004/extension/12843281004/answering-rule?page=1&perPage=100"
    }
  }
}

Uploading a Custom Greeting Media File to the Desired Answering Rule

Like all RingCentral media upload APIs, the Extension Greeting API supports the multipart/mixed Content Type, similar to fax and MMS. Because this is a common request type, the RingCentral community Ruby SDK includes a generic Multipart helper which supports adding JSON (typically used for the metadata) and files.

To upload a greeting, the POST /restapi/v1.0/account/~/extension/~/greeting API is used, however, you will need an Answering Rule Id to assign the greeting to which we discussed above. Once you have the appropriate answering rule id, you can make a post request to the Greeting endpoint to upload a new greeting.

HTTP Request

Here is the example request from the API Reference: Create Custom Greeting.

POST /restapi/v1.0/account/1455897004/extension/1455897004/greeting HTTP/1.1
Authorization: Bearer U0pDMDFQMDFQQVMwMXxBQURIZjAzWFFySGpMMGxPaEhMaFR0
Content-Type: multipart/mixed;boundary=0123456789
Content-Length: 376

--0123456789
Content-Type: application/json; charset=UTF-8
Content-Transfer-Encoding: binary

{
 "type": "Voicemail",
 "answeringRule": { "id": "2515566004" }
 }
--0123456789
filename="mygreeting.wav"
Content-Transfer-Encoding: binary
Content-Type: audio/wav

<...binary data...>

--0123456789--

Ruby SDK Request

After you have an extension’s answering rule id and your audio file, make a call to the RingCentral community Ruby SDK as follows:

require 'ringcentral_sdk'
# Instantiate the client
client = RingCentralSdk::REST::Client do |config|
  # your config parameters
end
# Create your request object
req = RingCentralSdk::REST::Request::Multipart.new(
  method: 'post',
  url: 'account/~/extension/~/greeting'
).
add_json({type: 'Voicemail', answeringRule: {id: '2515566004'}}).
add_file('mygreeting.mp3')
# Make the request
res = client.send_request req

Summary

RingCentral provides many ways to scale your unified communications system from the Online Account Portal to REST APIs. By using the REST APIs, you can quickly automate updating RingCentral user extension greetings using similar APIs and requests to other media update APIs.

To see how you can use unified communications automation to drive your business, sign up for the RingCentral Developer Program here: https://developer.ringcentral.com or chat with us on the RingCentral Developer Community: https://devcommunity.ringcentral.com.