User Answering Rules (Legacy)
Important
-
This developer guide explains how to use the User Answering Rule API for RingCentral accounts that have not yet been upgraded to the Enhanced User Call Handling features.
-
If your RingCentral account has been upgraded to support enhanced user call handling, click here to learn about the new User Call Handling APIs.
-
If you have already implemented user answering rules using the legacy API and your account has since been upgraded, please refer to the migration guide to update your code accordingly.
If you are not sure about if your account has been upgraded or not, call the following API to detect.
GET `/restapi/v1.0/account/~/extension/~/features?featureId=NewCallHandlingAndForwarding`
HTTP 200 OK
Response from an upgraded account
{
"records": [
{
"id": "NewCallHandlingAndForwarding",
"available": true,
"params": [
{
"name": "isNewBackendAvailable",
"value": "true"
}
]
}
]
}
Response from a legacy account
{
"records": [
{
"id": "NewCallHandlingAndForwarding",
"available": true,
"params": [
{
"name": "isNewBackendAvailable",
"value": "false"
}
]
}
]
}
User Answering Rules can be used to create and manage the logic for routing incoming calls to a particular user/extension. If you are unfamiliar with answering rules, we recommend you read our Answering Rules Overview.
Create a User Custom Answering Rule
Be mindful of the following when constructing a request to create a user custom answering rule:
- Provide a meaningful name for the rule using the
name
parameter. - Set the
type
parameter as "Custom." - Set the
enabled
parameter to True if the rule needs to be in effect immediately. Otherwise, set it to False. - Specify one or more conditions (see below).
- Specify the action to take using the
callHandlingAction
field (see table below). - Specify required parameters for
callHandlingAction
option accordingly. More details
Finally, make a POST request to the following endpoint:
/restapi/v1.0/account/{accountId}/extension/{extensionId}/answering-rule
Call Handling Conditions
The following parameters are used for specifying call handling conditions.
callers
: a list of callers' phone numbers or contact namescallerId
:name
:
calledNumbers
: a list of recipients' phone numbersphoneNumber
: a phone number belonging to the user/extension
schedule
: week day and time or time ranges or business hours and after hours parametersweeklyRanges
: week day and time rangesranges
: date and time rangesref
: "BusinessHours" or "AfterHours". Business hours can be set using the Business Hours API Reference
Call Handling Actions
Action | Description |
---|---|
ForwardCalls |
Re-route an incoming call to multiple phone numbers in a specific order with greeting settings apply. |
UnconditionalForwarding |
Forward an incoming call immediately to a specified number. |
TakeMessagesOnly |
Play back a voicemail greeting then forward an incoming call to a voice mailbox. |
PlayAnnouncementOnly |
Play back a pre-recorded announcement then hang up. |
TransferToExtension |
Forward an incoming call to a specific extension. |
AgentQueue |
Forward an incoming call (dialed to a Call Queue extension) to one or more specified agents. |
Required Fields
If ForwardCalls
is specified for callHandlingAction
, the forwarding
parameter object is required. You can use the call forwarding APIs to create or retrieve call forwarding information then use the the uri
, id
to specify the forwardingNumbers
parameter under the rules
object.
If "TransferToExtension" is specified for callHandlingAction
, the transfer
parameter object is required.
If "AgentQueue" is specified for callHandlingAction
, the queue
parameter object is required.
Required permission(s): EditExtensions
Sample Code
Create Answering Rule
The following code sample shows how to create a user custom answering rule that will re-route all incoming calls to a voice mailbox during a user's weekly meeting times on Monday and Friday.
const RC = require('@ringcentral/sdk').SDK
require('dotenv').config();
var rcsdk = new RC({
'server': process.env.RC_SERVER_URL,
'clientId': process.env.RC_APP_CLIENT_ID,
'clientSecret': process.env.RC_APP_CLIENT_SECRET
});
var platform = rcsdk.platform();
platform.login({ 'jwt': process.env.RC_USER_JWT })
platform.on(platform.events.loginSuccess, () => {
create_user_custom_rule()
});
async function create_user_custom_rule() {
var params = {
enabled: true,
type: "Custom",
name: "My weekly meetings",
schedule: {
weeklyRanges: {
monday: [{ from: "09:00", to: "10:00" }],
friday: [{ from: "10:00", to: "15:00" }]
}
},
callHandlingAction: "TakeMessagesOnly"
}
try {
var resp = await platform.post('/restapi/v1.0/account/~/extension/~/answering-rule', params)
var jsonObj = await resp.json()
console.log(jsonObj)
} catch (e) {
console.log(e.message)
}
}
#!/usr/bin/python
# You get the environment parameters from your
# application dashbord in your developer account
# https://developers.ringcentral.com
import os
import sys
from dotenv import load_dotenv
from ringcentral import SDK
load_dotenv()
rcsdk = SDK( os.environ.get('RC_APP_CLIENT_ID'),
os.environ.get('RC_APP_CLIENT_SECRET'),
os.environ.get('RC_SERVER_URL') )
platform = rcsdk.platform()
try:
platform.login( jwt=os.environ.get('RC_USER_JWT') )
except Exception as e:
sys.exit("Unable to authenticate to platform: " + str(e))
params = {
'enabled': True,
'type': 'Custom',
'name': "My weekly meetings",
'schedule' : {
'weeklyRanges': {
'monday': [{ 'from': "09:00",'to': "10:00" }],
'friday': [{ 'from': "10:00", 'to': "15:00" }]
}
},
'callHandlingAction': "TakeMessagesOnly"
}
resp = platform.post('/restapi/v1.0/account/~/extension/~/answering-rule', params)
print(resp.text())
<?php
// Remember to modify the path ./../ pointing to the location where the RingCentral SDK was installed and the .env file was saved!
require('./../vendor/autoload.php');
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__ . './../');
$dotenv->load();
$rcsdk = new RingCentral\SDK\SDK( $_ENV['RC_APP_CLIENT_ID'],
$_ENV['RC_APP_CLIENT_SECRET'],
$_ENV['RC_SERVER_URL'] );
$platform = $rcsdk->platform();
$platform->login( [ "jwt" => $_ENV['RC_USER_JWT'] ] );
$params = array (
'enabled' => true,
'type' => "Custom",
'name' => "My weekly meetings",
'schedule' => array (
'weeklyRanges' => array (
'monday' => array ( array ('from' => "09:00", 'to' => "10:00")),
'friday' => array ( array ('from' => "10:00", 'to' => "15:00"))
)
),
'callHandlingAction' => "TakeMessagesOnly"
);
$resp = $platform->post('/account/~/extension/~/answering-rule', $params);
print_r ($resp->text());
?>
using System;
using System.Threading.Tasks;
using RingCentral;
namespace UserCustomAnsweringRule
{
class Program {
static RestClient restClient;
static async Task Main(string[] args)
{
restClient = new RestClient(
Environment.GetEnvironmentVariable("RC_APP_CLIENT_ID"),
Environment.GetEnvironmentVariable("RC_APP_CLIENT_SECRET"),
Environment.GetEnvironmentVariable("RC_SERVER_URL"));
await restClient.Authorize(Environment.GetEnvironmentVariable("RC_USER_JWT"));
await create_user_custom_answering_rule();
}
static private async Task create_user_custom_answering_rule()
{
var parameters = new CreateAnsweringRuleRequest();
parameters.enabled = true;
parameters.type = "Custom";
parameters.name = "My weekly meetings";
var schedule = new ScheduleInfo();
var weeklyRanges = new WeeklyScheduleInfo();
TimeInterval meetingTime = new TimeInterval();
meetingTime.from = "09:00";
meetingTime.to = "10:00";
weeklyRanges.monday = new TimeInterval[] { meetingTime };
meetingTime = new TimeInterval();
meetingTime.from = "10:00";
meetingTime.to = "15:00";
weeklyRanges.friday = new TimeInterval[] { meetingTime };
schedule.weeklyRanges = weeklyRanges;
parameters.schedule = schedule;
parameters.callHandlingAction = "TakeMessagesOnly";
var response = await restClient.Restapi().Account().Extension().AnsweringRule().Post(parameters);
var jsonStr = JsonConvert.SerializeObject(response);
Console.WriteLine(jsonStr);
}
}
}
package com.ringcentral;
import com.ringcentral.*;
import com.ringcentral.definitions.*;
import java.io.IOException;
public class CreateCustomUserAnsweringRule {
static RestClient rc;
public static void main(String[] args) {
var obj = new CreateCustomUserAnsweringRule();
rc = new RestClient( System.getenv("RC_APP_CLIENT_ID"),
System.getenv("RC_APP_CLIENT_SECRET"),
System.getenv("RC_SERVER_URL") );
try {
rc.authorize( System.getenv("RC_USER_JWT") );
obj.create_user_custom_answering_rule();
} catch (RestException | IOException e) {
e.printStackTrace();
}
}
public void create_user_custom_answering_rule() throws RestException, IOException {
var schedule = new ScheduleInfo();
var weeklyRanges = new WeeklyScheduleInfo();
TimeInterval meetingTime = new TimeInterval();
meetingTime.from = "09:00";
meetingTime.to = "10:00";
weeklyRanges.monday = new TimeInterval[] { meetingTime };
meetingTime = new TimeInterval();
meetingTime.from = "10:00";
meetingTime.to = "15:00";
weeklyRanges.friday = new TimeInterval[] { meetingTime };
schedule.weeklyRanges = weeklyRanges;
var parameters = new CreateAnsweringRuleRequest();
parameters.enabled = true;
parameters.type = "Custom";
parameters.name = "My weekly meetings";
parameters.schedule = schedule;
parameters.callHandlingAction = "TakeMessagesOnly";
CustomAnsweringRuleInfo response = rc.restapi().account().extension().answeringRule().post(parameters);
System.out.println("Rule created: " + response.id);
}
}
#!usr/bin/ruby
# You get the environment parameters from your
# application dashbord in your developer account
# https://developers.ringcentral.com
require 'ringcentral'
require 'dotenv/load'
$rc = RingCentral.new(ENV['RC_APP_CLIENT_ID'],
ENV['RC_APP_CLIENT_SECRET'],
ENV['RC_SERVER_URL'])
$rc.authorize(jwt: ENV['RC_USER_JWT'])
params = {
enabled: true,
type: 'Custom',
name: 'My weekly meetings',
schedule: {
weeklyRanges: {
monday: [{ from: "09:00", to: "10:00" }],
friday: [{ from: "10:00", to: "15:00" }]
}
},
callHandlingAction: "TakeMessagesOnly",
}
resp = $rc.post('/restapi/v1.0/account/~/extension/~/answering-rule', payload: params)
puts resp.body
Upon successful API call completion, the response contains the id (ruleId
) and other information of the newly created rule.
{
"uri": "https://platform.ringcentral.com/restapi/v1.0/account/178002314/extension/178009114/answering-rule/227207004",
"id": "227207004",
"type": "Custom",
"name": "My weekly meetings",
// ...etc...
}
List User Answering Rules
To get a list of all user answering rules for an extension, make a GET request to the following endpoint:
/restapi/v1.0/account/{accountId}/extension/{extensionId}/answering-rule
Required permission(s): ReadExtensions
Upon successful API call completion, the response contains a list of all existing user answering rules (including the default rules).
{
"uri": "https://platform.ringcentral.com/restapi/v1.0/account/11111111/extension/22222222/answering-rule?page=1&perPage=100",
"records": [
{
"uri": "https://platform.ringcentral.com/restapi/v1.0/account/11111111/extension/22222222/answering-rule/33333333",
"id": "33333333",
"type": "Custom",
"name": "My Custom Rule 1",
"enabled": true
},
{
"uri": "https://platform.ringcentral.com/restapi/v1.0/account/11111111/extension/22222222/answering-rule/business-hours-rule",
"id": "business-hours-rule",
"type": "BusinessHours",
"enabled": true
}
],
"paging": {...},
"navigation": {...}
}
Fetch a Single User Answering Rule
To fetch the details associated with an individual user answering rule, make a GET request to the following endpoint, where [ruleId]
is the ID of an existing rule:
/restapi/v1.0/account/{accountId}/extension/{extensionId}/answering-rule/[ruleId]
Notes
A valid ruleId
can be retrieved using the previous API to read all user answering rules.
The ruleId
of the default Business Hours and After Hours rule is business-hours-rule
and after-hours-rule
, respectively.
Required permission(s): ReadExtensions
Upon successful API call completion, the response contains detailed information of a rule.
{
"uri": "http://platform.ringcentral.com/restapi/v1.0/account/11111111/extension/22222222/answering-rule/business-hours-rule",
"id": "business-hours-rule",
"type": "BusinessHours",
"enabled": true,
"schedule": {
"ref": "BusinessHours"
},
"callHandlingAction": "ForwardCalls",
"forwarding": {
"notifyMySoftPhones": true,
"notifyAdminSoftPhones": false,
"softPhonesRingCount": 1,
"ringingMode": "Sequentially",
"rules": [
{
"index": 1,
"ringCount": 4,
"forwardingNumbers": [
{
"uri": "http://platform.ringcentral.com/restapi/v1.0/account/11111111/extension/22222222/forwarding-number/33333333",
"id": "33333333",
"phoneNumber": "+16505551212",
"label": "My Cisco SPA-303 Desk Phone"
}
]
},
{
"index": 2,
"ringCount": 8,
"forwardingNumbers": [
{
"uri": "http://platform.ringcentral.com/restapi/v1.0/account/11111111/extension/22222222/forwarding-number/44444444",
"id": "44444444",
"phoneNumber": "+4155551212",
"label": "Home"
}
]
},
{
"index": 3,
"ringCount": 12,
"forwardingNumbers": [
{
"uri": "http://platform.ringcentral.com/restapi/v1.0/account/11111111/extension/22222222/forwarding-number/55555555",
"id": "55555555",
"phoneNumber": "+12125551212",
"label": "Mobile"
}
]
}
]
},
"greetings": [
{
"type": "Voicemail",
"prompt": {
"id": "0",
"type": "message",
"name": "No One Available"
}
},
{
"type": "Introductory"
},
{
"type": "AudioWhileConnecting",
"prompt": {
"id": "6",
"type": "music",
"name": "Acoustic"
}
},
{
"type": "ConnectingMessage",
"prompt": {
"id": "3",
"type": "message",
"name": "Forward hold 1"
}
}
],
"screening": "Never",
"voicemail": {
"enabled": true,
"recipient": {
"uri": "http://platform.ringcentral.com/restapi/v1.0/account/11111111/extension/22222222",
"id": 22222222
}
}
}
Update a User Answering Rule
To update a user answering rule specify only the parameter values which need to be updated. Then make a PUT request to the following endpoint, where [ruleId]
is the ID of an existing rule:
/restapi/v1.0/account/{accountId}/extension/{extensionId}/answering-rule/[ruleId]
Notes
A valid ruleId
can be retrieved using the API to read all user answering rules.
The ruleId
of the default Business Hours and After Hours rule is business-hours-rule
and after-hours-rule
, respectively.
Required permission(s): EditExtensions
Delete a User Answering Rule
To delete a user answering rule, make a DELETE request to the following endpoint, where the ruleId
is the id of an existing rule.
/restapi/v1.0/account/{accountId}/extension/{extensionId}/answering-rule/[ruleId]
Required permission(s): EditExtensions
Sample Response
{
"callHandlingAction":"TakeMessagesOnly",
"enabled":true,
"forwarding":{
"mobileTimeout":false,
"notifyAdminSoftPhones":false,
"notifyMySoftPhones":true,
"ringingMode":"Sequentially",
"softPhonesRingCount":1
},
"greetings":[
{
"preset":
{
"id":"65792",
"name":"Default",
"uri":"https://platform.ringcentral.com/restapi/v1.0/dictionary/greeting/65792"
},
"type":"Voicemail"
},{
"preset":
{
"id":"66301",
"name":"None",
"uri":"https://platform.ringcentral.com/restapi/v1.0/dictionary/greeting/66301"
},
"type":"Introductory"
},{
"preset":
{
"id":"66310",
"name":"Acoustic",
"uri":"https://platform.ringcentral.com/restapi/v1.0/dictionary/greeting/66310"
},
"type":"ConnectingAudio"
},{
"preset":
{
"id":"66560",
"name":"Default",
"uri":"https://platform.ringcentral.com/restapi/v1.0/dictionary/greeting/66560"
},
"type":"Announcement"
},{
"preset":
{
"id":"66816",
"name":"Default",
"uri":"https://platform.ringcentral.com/restapi/v1.0/dictionary/greeting/66816"
},
"type":"Unavailable"
},{
"preset":
{
"id":"68867",
"name":"Default",
"uri":"https://platform.ringcentral.com/restapi/v1.0/dictionary/greeting/68867"
},
"type":"ConnectingMessage"
}],
"id":"227258004",
"name":"My weekly meetings",
"schedule":
{
"weeklyRanges":
{
"friday":[{"from":"10:00","to":"15:00"}],
"monday":[{"from":"09:00","to":"10:00"}]
}
},
"screening":"Off",
"type":"Custom",
"uri":"https://platform.ringcentral.com/restapi/v1.0/account/178009004/extension/178009004/answering-rule/227258004",
"voicemail":
{
"enabled":true,
"recipient":
{
"id":"178009004",
"uri":"https://platform.ringcentral.com/restapi/v1.0/account/178009004/extension/178009004"
}
}
}