User Call Handling APIs Migration Guidance

The enhancement of user call handling features in RingCentral RingEX has led to significant changes in the corresponding APIs. As part of this upgrade, we have introduced a new set of user extension call handling APIs (referred to as V2) to replace the legacy version (v1.0). This marks a major transition aimed at providing more robust and flexible call management capabilities.

Who will get impacted and what will be broken?

Eventually, all RingEX customer accounts will be upgraded to support the new user call handling features. As a result, any RingCentral account which is upgraded to the new user call handling capabilities, will not be able to read, create or change their user call handling rules by using the v1.0 extension call handling API set.

Thus, if your company built applications which call the v1.0 extension call handling APIs, such applications will stop working if your RingCentral account is upgraded to support the new user call handling features.

To detect programmatically if an account is upgraded with the new user call handling features or not, you can call the following API to read the account features and parse the response to check the highlighted feature below:

GET ‘/restapi/v1.0/account/~/extension/~/features?featureId=NewCallHandlingAndForwarding’

Response from an old account

{
  "id": "NewCallHandlingAndForwarding",
  "available": true,
  "params": [
    {
      "name": "isNewBackendAvailable",
      "value": "false"
    }
   ]
}

Response from an upgraded account

{
  "id": "NewCallHandlingAndForwarding",
  "available": true,
  "params": [
    {
      "name": "isNewBackendAvailable",
      "value": "true"
    }
   ]
}

What are the new features and new APIs?

The new user call handling rules are grouped into 2 different sets of rules, the “state-based” rules, and the “interaction” rules which are also known as the custom rules.

There are 5 call handling states and they are explained below:

How to manage user call handling states via API?

The extension call handling states can be read by calling the new API

GET /restapi/v2/accounts/~/extensions/[extensionId]/comm-handling/states

The API returns a list of call handling states with detailed call handling settings of each state.

The extension call handling state-based rules can be updated by calling the new API

PATCH /restapi/v2/accounts/~/extensions/[extensionId]/comm-handling/states

There is no equivalent v1.0 API as there is no call handling state service in the old call handling service!

How to manage user call handling state-based rules via API?

The user extension call handling state-based rules can be read by calling the new API

GET /restapi/v2/accounts/~/extensions/[extensionId]/comm-handling/voice/state-rules

The API returns a list of the user's call handling states with detailed call handling settings for each state rule.

It replaces the v1.0 API below

GET /restapi/v1.0/account/~/extension/[extensionId]/answering-rule

In comparison to the v1.0 endpoint, the v2 endpoint returns 3 new call handling rules, the “Do not disturb” rule, the “Agent” rule and the“Forward all calls” rule. But it does not return the custom rules (if any) in the response.

To read or update a particular state-based rule, call this API with the state Id in the API path

GET/PATCH /restapi/v2/accounts/~/extensions/[extId]/comm-handling/voice/state-rules/[stateId]

Note that there is no public v1.0 API to read and update the extension “forward-all-calls” rule. If you have access to the internal v1.0 /forward-all-calls API, replace it with the v2 API as shown in the table below:

* internal API

How to manage user call handling interaction rules via API?

Extension call handling interaction rules are the new terms of extension custom answering rules. To list user extension's custom call handling rules, call the new API below:

GET /restapi/v2/accounts/~/extensions/[extId]/comm-handling/voice/interaction-rules

This is equivalent to the v1.0 API GET /answering-rule?type=Custom

To read a particular custom rule, call the API below with the custom rule Id in the path

GET /restapi/v2/accounts/~/extensions/[extId]/comm-handling/voice/interaction-rules/[ruleId]

Forward All Calls Rule

Both old and new extension call handling supports the “ForwardAllCalls” rule and both has the same call handling actions:

• Send to voicemail
• Forward the call
• Forward to a phone number/personal contact
• Forward to an extension/call queue
• Play announcement

There is no public API to read and update the ForwardAllCalls rule for v1.0 API.

The call handling V2 API allows you to read and update the extension Forward-All-Calls rule. Below are the highlighted API response fields that define the selected call handling actions:

Do Not Disturb Rule

Only new extension call handling supports the “DnD” rule. The DnD rule has the same call handling actions as the ForwardAllCalls actions:

• Send to voicemail
• Forward the call
  • Forward to a phone number/personal contact
  • Forward to an extension/call queue
• Play announcement

Note: The old call handling does not have a dedicated rule for DnD, the system uses the setting value of the user presence ‘dndStatus’.

The call handling V2 API allows you to read and update the extension DnD rule. Below are the highlighted API response fields that define the selected call handling actions:

Work Hours Rule

Both old and new extension call handling supports the “WorkHours” rule and both have the same call handling actions.

Work Hours actions:

• Ring in order
• Ring all together
• If no one answers
  • Send to voicemail
  • Forward the call
    • Forward to a phone number/personal contact
    • Forward to an extension/call queue
  • Play announcement

After Hours Rule

Both old and new extension call handling supports the “AfterHours” rule and both have the same call handling actions.

After Hours actions:

• Ring devices
  • Ring in order
  • Ring all together
  • If no one answers
    • Send to voicemail
    • Forward the call
      • Forward to a phone number/personal contact
      • Forward to an extension/call queue
    • Play announcement
• Terminating action
  • Send to voicemail
  • Forward the call
    • Forward to a phone number/personal contact
    • Forward to an extension/call queue
  • Play announcement

Ringing actions V1.0 vs. V2:

Terminating action V1.0 vs. V2

Welcome greetings V1.0 vs. V2

Create custom user greetings

There is no V2 API for managing custom greetings for extensions. However, to create a custom greeting in migrated accounts, the V1.0 greeting API can be used with slightly different body params. The “type” value and the “binary” field are unchanged.

You can create a user custom greeting without the associated answering rule and set the apply=false in the API path, then keep the greeting ID and update the state rule or the interaction rule using the new update state rule or the new update interaction rule API.

Examples

Create and assign a custom greeting directly using the /greeting endpoint

async function createExtensionCustomGreeting(){
    /* One of these types
        "Introductory"
        "Announcement"
        "ConnectingMessage"
        "ConnectingAudio"
        "Voicemail"
        "Unavailable"
        "HoldMusic"
        "TemplateGreeting"
    */
    let bodyParams = {
            type: "Announcement"
            stateId: 5 // OR
            //"peopleNumberRuleId": "12345"
     }

    var FormData = require('form-data');
    formData = new FormData();

    formData.append('json', new Buffer.from(JSON.stringify(bodyParams)),
       {
         filename: 'request.json',
         contentType: 'application/json'
        });
    formData.append('binary', require('fs').createReadStream('greeting.mp3'));
    var endpoint = '/restapi/v1.0/account/~/extension/~/greeting?apply=true'
    var resp = await platform.post(endpoint, formData)
    var jsonObj = await resp.json()
}

Create an unassociated custom greeting using the /greeting endpoint, and call the update state rule endpoint to set the greeting to the 'work-hours' rule

async function createExtensionCustomGreeting(){
    /* One of these types
        "Introductory"
        "Announcement"
        "ConnectingMessage"
        "ConnectingAudio"
        "Voicemail"
        "Unavailable"
        "HoldMusic"
        "TemplateGreeting"
    */
    let bodyParams = {
            type: "Announcement"
          }

    var FormData = require('form-data');
    formData = new FormData();

    formData.append('json', new Buffer.from(JSON.stringify(bodyParams)),
       {
         filename: 'request.json',
         contentType: 'application/json'
        });

    formData.append('binary', require('fs').createReadStream('greeting.mp3'));
     var endpoint = '/restapi/v1.0/account/~/extension/~/greeting?apply=false'
    var resp = await platform.post(endpoint, formData)
    var jsonObj = await resp.json()
    updateWorkHourStateRule(jsonObj.id)
}

async function updateWorkHourStateRule(greetingId){
  // The best way is to read the ‘work-hours’ state rule, then change (or add if it does not exist) the ‘PlayWelcomePromptAction’ ‘custom’ value!!!
  let bodyParams = {
      dispatching: {
        actions: [
          {
            type: "PlayWelcomePromptAction",
            greeting: {
                effectiveGreetingType: "Custom",
                preset: {
                  id: "66048"
                },
                custom: {
                  id: greetingId
                }
            },
            enabled: true
          },
            …
        ]
      }
    var endpoint = '/restapi/v2/accounts/~/extensions/~/comm-handling/voice/state-rules/work-hours'

    const resp = await platform.patch(endpoint, bodyParams)
    var jsonObj = await resp.json()
    …
}

How to manage user flipping numbers and forwarding numbers settings

In the new call handling and forwarding environment, flipping numbers and forwarding numbers are handled by separated new APIs. The old forwarding number handling API will be deprecated.

Flipping numbers

There are 2 new APIs to read and update user flipping numbers. To list all user flipping numbers, call the following API:

GET /restapi/v2/accounts/~/extensions/~/call-flip-numbers

To add, update or delete a flipping number, call the following API with appropriate body params:

PUT /restapi/v2/accounts/~/extensions/~/call-flip-numbers

Forwarding numbers

Forwarding numbers can be read or removed by using the following APIs: