User Answering Rules
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 (dialed to a Call Queue extension) 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"
}
}
}