User Interaction Call Handling Rules
Last updated: 2025-06-23Contributors
Edit this page
Interaction user call handling rules are custom rules that allow users to define how incoming calls should be managed under specific conditions or scenarios. These rules offer flexibility beyond the state rules, enabling users to tailor call behavior to meet unique needs.
For example, a user might want to create a custom rule to handle calls during annual public holidays. Instead of following the default call handling flow, the rule could automatically route incoming calls to voicemail, play a holiday-specific greeting, or forward calls to an alternate number. This ensures that callers receive appropriate handling and information, even when the user is unavailable due to special circumstances.
If a user has a custom rule, incoming calls to the user will be routed using the following logic:
User call handling hierarchy with custom rule(s)
A user interaction rule can be triggered by the following conditions:
- Caller Ids: An array of phone numbers that incoming calls are dialed from
- Called Numbers: An array of phone numbers that an incoming call is dialed to
- Schedule:
- Range: A period of time specified by date and time range
- Weekly: Repeatedly for certain week day
- State
- Work-Hours: Match the work-hours schedule
- After-Hours: Match the after-hours schedule
A custom rule is executed only in case all its conditions match the incoming call. This means that the condition evaluation is an AND operator.
Note
When using the State trigger to match the work-hours or after-hours schedule, you must also include either a Caller ID or a Called Number condition, or both conditions to ensure proper rule evaluation.
If a user has multiple interaction rules, the interaction rules priority will be calculated based on the following logics:
| Schedule Condition | Caller ID Condition | Called Number Condition | Priority |
|---|---|---|---|
| Set up | Set up | Set up | 10 |
| Not Set | Set up | Set up | 9 |
| Set up | Set up | Not Set | 8 |
| Set up | Not Set | Set up | 7 |
| Not Set | Set up | Not Set | 6 |
| Not Set | Not Set | Set up | 5 |
| Set up | Not Set | Not Set | 4 |
An interaction rule can also be applied to incoming calls received through a call queue, provided the feature is enabled on the account and the queueCallsIncluded flag is set to true. In this case, calls received via the call queue are evaluated against the custom rule conditions. If none of the conditions are met, the call is routed to the "Agent" state.
Example use case
The following example demonstrates how to implement an interaction rule to handle incoming calls from VIP customers during after-hours. Alex works in customer support. His regular working hours are weekdays from 8:00 AM to 4:00 PM. He has an After-Hours rule configured to route all incoming calls to his voicemail outside of those hours. However, Alex is eligible for a performance bonus if he supports VIP customers during his off-hours. To take advantage of this, he decides to receive calls from VIP customers on his personal mobile number: +1 (408) 232-4343. Let’s help Alex create a custom interaction rule to meet this requirement.
Assume that Alex has exported a list of 5 VIP customers from his company’s CRM into the following contact list:
let vipCustomerContacts = [
{
phoneNumber: "+16501111111",
name: "Kristina Grant"
},{
phoneNumber: "+16502222222",
name: "Sandra Bell"
},{
phoneNumber: "+16503333333",
name: "David Peterson"
},{
phoneNumber: "+16504444444",
name: "Lena Shanon"
},{
phoneNumber: "+16505555555",
name: "Christine Lee"
}
]
Now we specify the parameters for the custom rule as shown below:
let bodyParams = {
conditions: [
{
type: "Interaction",
from: vipCustomerContacts, // Assigned with the list of VIP customer contacts
to: []
},
{
type: "State",
state: { id: "after-hours" } // Match the after-hours schedule
}
],
dispatching: {
actions: [
{
type: "RingGroupAction",
enabled: true,
targets: [
{
type: "AllMobileRingTarget",
name: "My mobile apps"
}
],
duration: 40
},
{
type: "RingGroupAction",
enabled: true,
targets: [
{
type: "AllDesktopRingTarget",
name: "My desktop"
}
],
duration: 50
},
{
type: "TerminatingAction",
targets: [
{
type: "VoiceMailTerminatingTarget",
name: "Voicemail",
prompt: {
greeting: {
effectiveGreetingType: "Preset",
preset: {
id: "590080"
}
}
}
},
{
type: "PlayAnnouncementTerminatingTarget",
name: "PlayAnnouncement",
prompt: {
greeting: {
effectiveGreetingType: "Preset",
preset: {
id: "66816"
}
}
},
dispatchingType: "Ringing"
},
{
type: "PhoneNumberTerminatingTarget",
destination: {
phoneNumber: "+14082324343" // Incoming calls are routed to Alex's personal phone number
},
dispatchingType: "Terminating"
}
],
ringingTargetType: "PlayAnnouncementTerminatingTarget",
terminatingTargetType: "PhoneNumberTerminatingTarget" // Indicating that incoming calls are terminated and forwarded to a phone number.
}
],
type: "Terminate"
},
enabled: true,
displayName: "VIP Calls After-Hours"
}
With the bodyParams above, we can call the API to create a new custom rule for Alex
Running the code
If you have tried the RingOut quick start, you can just copy all the functions below and add them to the quick start project then call the create_user_interation_rule() function. Otherwise, edit the variables in ALL CAPS with your app and user credentials before running the code.
const RC = require('@ringcentral/sdk').SDK
// Instantiate the SDK and get the platform instance
var rcsdk = new RC({
server: 'https://platform.ringcentral.com',
clientId: 'RC_APP_CLIENT_ID',
clientSecret: 'RC_APP_CLIENT_SECRET'
});
var platform = rcsdk.platform();
/* Authenticate a user using a personal JWT token */
platform.login({ jwt: 'RC_USER_JWT' })
platform.on(platform.events.loginSuccess, () => {
create_user_interaction_rule()
})
platform.on(platform.events.loginError, function(e){
console.log("Unable to authenticate to platform. Check credentials.", e.message)
process.exit(1)
});
/*
* Create a user interaction rule
*/
async function create_user_interaction_rule() {
try {
let vipCustomerContacts = [
{
phoneNumber: "+16501111111",
name: "Kristina Grant"
},{
phoneNumber: "+16502222222",
name: "Sandra Bell"
},{
phoneNumber: "+16503333333",
name: "David Peterson"
},{
phoneNumber: "+16504444444",
name: "Lena Shanon"
},{
phoneNumber: "+16505555555",
name: "Christine Lee"
}
]
let bodyParams = {
conditions: [
{
type: "Interaction",
from: vipCustomerContacts, // Assigned with the list of VIP customer contacts
to: []
},
{
type: "State",
state: { id: "after-hours" } // Match the after-hours schedule
}
],
dispatching: {
actions: [
{
type: "RingGroupAction",
enabled: true,
targets: [
{
type: "AllMobileRingTarget",
name: "My mobile apps"
}
],
duration: 40
},
{
type: "RingGroupAction",
enabled: true,
targets: [
{
type: "AllDesktopRingTarget",
name: "My desktop"
}
],
duration: 50
},
{
type: "TerminatingAction",
targets: [
{
type: "VoiceMailTerminatingTarget",
name: "Voicemail",
prompt: {
greeting: {
effectiveGreetingType: "Preset",
preset: {
id: "590080"
}
}
}
},
{
type: "PlayAnnouncementTerminatingTarget",
name: "PlayAnnouncement",
prompt: {
greeting: {
effectiveGreetingType: "Preset",
preset: {
id: "66816"
}
}
},
dispatchingType: "Ringing"
},
{
type: "PhoneNumberTerminatingTarget",
destination: {
phoneNumber: "+14082324343" // Incoming calls are routed to Alex's personal phone number
},
dispatchingType: "Terminating"
}
],
ringingTargetType: "PlayAnnouncementTerminatingTarget",
terminatingTargetType: "PhoneNumberTerminatingTarget"
}
],
type: "Terminate"
},
enabled: true,
displayName: "VIP Calls After-Hours"
}
let endpoint = '/restapi/v2/accounts/~/extensions/~/comm-handling/voice/interaction-rules'
let resp = await platform.post(endpoint, bodyParams)
let jsonObj = await resp.json()
console.log(JSON.stringify(jsonObj, null, 4))
} catch (e) {
console.log("Unable to create a custom rule. ", e.message);
}
}
<?php
require('vendor/autoload.php');
// Instantiate the SDK and get the platform instance
$rcsdk = new RingCentral\SDK\SDK( 'RC_APP_CLIENT_ID', 'RC_APP_CLIENT_SECRET', 'https://platform.ringcentral.com' );
$platform = $rcsdk->platform();
/* Authenticate a user using a personal JWT token */
$platform->login(["jwt" => 'RC_USER_JWT']);
create_user_interaction_rule();
/*
* Create a user interaction rule
*/
function create_user_interaction_rule(){
global $platform;
try {
$vipCustomerContacts = [
[
"phoneNumber" => "+16501111111",
"name" => "Kristina Grant"
],
[
"phoneNumber" => "+16502222222",
"name" => "Sandra Bell"
],
[
"phoneNumber" => "+16503333333",
"name" => "David Peterson"
],
[
"phoneNumber" => "+16504444444",
"name" => "Lena Shanon"
],
[
"phoneNumber" => "+16505555555",
"name" => "Christine Lee"
]
];
$bodyParams = [
"conditions" => [
[
"type" => "Interaction",
"from" => $vipCustomerContacts, // Assigned with the list of VIP customer contacts
"to" => []
],
[
"type" => "State",
"state" => [ "id" => "after-hours" ] // Match the after-hours schedule
]
],
"dispatching" => [
"actions" => [
[
"type" => "RingGroupAction",
"enabled" => true,
"targets" => [
[
"type" => "AllMobileRingTarget",
"name" => "My mobile apps"
]
],
"duration" => 40
],
[
"type" => "RingGroupAction",
"enabled" => true,
"targets" => [
[
"type" => "AllDesktopRingTarget",
"name" => "My desktop"
]
],
"duration" => 50
],
[
"type" => "TerminatingAction",
"targets" => [
[
"type" => "VoiceMailTerminatingTarget",
"name" => "Voicemail",
"prompt" => [
"greeting" => [
"effectiveGreetingType" => "Preset",
"preset" => [
"id" => "590080"
]
]
]
],
[
"type" => "PlayAnnouncementTerminatingTarget",
"name" => "PlayAnnouncement",
"prompt" => [
"greeting" => [
"effectiveGreetingType" => "Preset",
"preset" => [
"id" => "66816"
]
]
],
"dispatchingType" => "Ringing"
],
[
"type" => "PhoneNumberTerminatingTarget",
"destination" => [
"phoneNumber" => "+14082324343" // Incoming calls are routed to Alex's personal phone number
],
"dispatchingType" => "Terminating"
]
],
"ringingTargetType" => "PlayAnnouncementTerminatingTarget",
"terminatingTargetType" => "PhoneNumberTerminatingTarget"
]
],
"type" => "Terminate"
],
"enabled" => true,
"displayName" => "VIP Calls After-Hours"
];
$endpoint = "/restapi/v2/accounts/~/extensions/~/comm-handling/voice/interaction-rules";
$resp = $platform->post($endpoint, $bodyParams);
print_r ($resp->json());
}catch (\RingCentral\SDK\Http\ApiException $e) {
// Getting error messages using PHP native interface
print 'HTTP Error: ' . $e->getMessage() . PHP_EOL;
// Another way to get message, but keep in mind, that there could be no response if request has failed completely
print "Unable to create a custom rule. " . $e->apiResponse->response()->error() . PHP_EOL;
}
}
?>
from ringcentral import SDK
import json
#
# Create a user interaction rule
#
def create_user_interaction_rule():
try:
vipCustomerContacts = [
{
"phoneNumber": "+16501111111",
"name": "Kristina Grant"
},{
"phoneNumber": "+16502222222",
"name": "Sandra Bell"
},{
"phoneNumber": "+16503333333",
"name": "David Peterson"
},{
"phoneNumber": "+16504444444",
"name": "Lena Shanon"
},{
"phoneNumber": "+16505555555",
"name": "Christine Lee"
}
]
bodyParams = {
"conditions": [
{
"type": "Interaction",
"from": vipCustomerContacts, # Assigned with the list of VIP customer contacts
"to": []
},
{
"type": "State",
"state": {
"id": "after-hours" # Match the after-hours schedule
}
}
],
"dispatching": {
"actions": [
{
"type": "RingGroupAction",
"enabled": True,
"targets": [
{
"type": "AllMobileRingTarget",
"name": "My mobile apps"
}
],
"duration": 40
},
{
"type": "RingGroupAction",
"enabled": True,
"targets": [
{
"type": "AllDesktopRingTarget",
"name": "My desktop"
}
],
"duration": 50
},
{
"type": "TerminatingAction",
"targets": [
{
"type": "VoiceMailTerminatingTarget",
"name": "Voicemail",
"prompt": {
"greeting": {
"effectiveGreetingType": "Preset",
"preset": {
"id": "590080"
}
}
}
},
{
"type": "PlayAnnouncementTerminatingTarget",
"name": "PlayAnnouncement",
"prompt": {
"greeting": {
"effectiveGreetingType": "Preset",
"preset": {
"id": "66816"
}
}
},
"dispatchingType": "Ringing"
},
{
"type": "PhoneNumberTerminatingTarget",
"destination": {
"phoneNumber": "+14082324343" # Incoming calls are routed to Alex's personal phone number
},
"dispatchingType": "Terminating"
}
],
"ringingTargetType": "PlayAnnouncementTerminatingTarget",
"terminatingTargetType": "PhoneNumberTerminatingTarget"
}
],
"type": "Terminate"
},
"enabled": True,
"displayName": "VIP Calls After-Hours"
}
endpoint = '/restapi/v2/accounts/~/extensions/~/comm-handling/voice/interaction-rules'
resp = platform.post(endpoint, bodyParams)
jsonObj = resp.json_dict()
print(json.dumps(jsonObj, indent=2, sort_keys=True))
except Exception as e:
print ("Unable to create a custom rule. " + str(e))
# Authenticate a user using a personal JWT token
def login():
try:
platform.login( jwt= "RC_USER_JWT" )
create_user_interaction_rule()
except Exception as e:
print ("Unable to authenticate to platform. Check credentials. " + str(e))
# Instantiate the SDK and get the platform instance
rcsdk = SDK("RC_APP_CLIENT_ID", "RC_APP_CLIENT_SECRET", "https://platform.ringcentral.com")
platform = rcsdk.platform()
login()
require 'ringcentral'
#
# Create a user interaction rule
#
def create_user_interaction_rule()
begin
vipCustomerContacts = [
{
phoneNumber: "+16501111111",
name: "Kristina Grant"
},{
phoneNumber: "+16502222222",
name: "Sandra Bell"
},{
phoneNumber: "+16503333333",
name: "David Peterson"
},{
phoneNumber: "+16504444444",
name: "Lena Shanon"
},{
phoneNumber: "+16505555555",
name: "Christine Lee"
}
]
bodyParams = {
conditions: [
{
type: "Interaction",
from: vipCustomerContacts, # Assigned with the list of VIP customer contacts
to: []
},
{
type: "State",
state: {
id: "after-hours" # Match the after-hours schedule
}
}
],
dispatching: {
actions: [
{
type: "RingGroupAction",
enabled: true,
targets: [
{
type: "AllMobileRingTarget",
name: "My mobile apps"
}
],
duration: 40
},
{
type: "RingGroupAction",
enabled: true,
targets: [
{
type: "AllDesktopRingTarget",
name: "My desktop"
}
],
duration: 50
},
{
type: "TerminatingAction",
targets: [
{
type: "VoiceMailTerminatingTarget",
name: "Voicemail",
prompt: {
greeting: {
effectiveGreetingType: "Preset",
preset: {
id: "590080"
}
}
}
},
{
type: "PlayAnnouncementTerminatingTarget",
name: "PlayAnnouncement",
prompt: {
greeting: {
effectiveGreetingType: "Preset",
preset: {
id: "66816"
}
}
},
dispatchingType: "Ringing"
},
{
type: "PhoneNumberTerminatingTarget",
destination: {
phoneNumber: "+14082324343" # Incoming calls are routed to Alex's personal phone number
},
dispatchingType: "Terminating"
}
],
ringingTargetType: "PlayAnnouncementTerminatingTarget",
terminatingTargetType: "PhoneNumberTerminatingTarget"
}
],
type: "Terminate"
},
enabled: true,
displayName: "VIP Calls After-Hours"
}
endpoint = '/restapi/v2/accounts/~/extensions/~/comm-handling/voice/interaction-rules'
resp = $platform.post(endpoint, payload: bodyParams)
puts(resp.body)
rescue StandardError => e
puts ("Unable to create a custom rule. " + e.to_s)
end
end
# Authenticate a user using a personal JWT token
def login()
begin
$platform.authorize( jwt: "RC_USER_JWT" )
create_user_interaction_rule()
rescue StandardError => e
puts ("Unable to authenticate to platform. Check credentials. " + e.to_s)
end
end
# Instantiate the SDK and get the platform instance
$platform = RingCentral.new( "RC_APP_CLIENT_ID", "RC_APP_CLIENT_SECRET", "https://platform.ringcentral.com" )
login()