Call Queue Call Handling

Call queue call handling is a set of configurations that determine how incoming calls to a call queue are routed and managed. These configurations can be tailored for different scenarios to ensure efficient call distribution and a consistent caller experience.

Call queue call handling rules can be defined separately based on the following conditions:

• Business Hours rule – Defines how calls are managed during the preset operating hours.
• After Hours rule – Applies when the business is closed (if business hours are not set to 24/7).
• Custom Schedules and Conditions rule – Allows for special rules based on specific criteria, such as caller ID, called number, or custom time schedules (e.g., holidays or special events).

If a call queue has a custom rule that is configured and enabled, any incoming call to the queue will first be evaluated against the conditions defined in that rule. If all the conditions are met, the call will be routed according to the dispatching settings specified in the rule.

When multiple custom rules are active, the system will evaluate each rule in order. The first rule whose conditions match will determine how the call is handled. If none of the active custom rules match the incoming call, the system will fall back to evaluating the call against the Business Hours or After Hours rule, depending on the current date and time.

Call queue call handling configurations are set differently for different types of rules.

Business Hours rule

The Business Hours rule defines how incoming calls are handled during the organization's regular working hours. This rule ensures calls are routed to the available members (agents) when they are expected to be on duty. This rule typically aligns with the operating hours of the company or a specific branch office, helping to maintain a consistent and responsive customer experience.

A call queue business hours schedule can be read by using the following API:

GET /restapi/v1.0/account/~/extension/[CallQueueExtensionId]/business-hours

By default, the business hours schedule is set to 24/7. To change the business hours schedule, call the following API with appropriate schedule params.

PUT /restapi/v1.0/account/~/extension/[CallQueueExtensionId]/business-hours

The Business Hours call handling configurations are complex. They include a set of configurations for greeting a caller, ringing its members and other call queue features such as the waiting time, agent time out and the forwarding actions when the incoming call is not answered.

To read the call queue business hours rule, call the following API:

GET /restapi/v1.0/account/~/extension/[CallQueueExtensionId]/answering-rule/business-hours-rule

To set the call queue business hours rule, call the following API with appropriate parameters:

PUT /restapi/v1.0/account/~/extension/[CallQueueExtensionId]/answering-rule/business-hours-rule

Greeting configurations

Greeting configurations define how a caller is greeted and informed while they are calling and waiting in a queue.

You can set a standard greeting or a custom greeting message for the following types:

For example if you want to set a custom welcome greeting, specify the body params as shown below (assumed that you have created a custom greeting and have the greeting id "XXXXXXXXX"):

  let bodyParam = {
    "greetings":[
        {
          "type": "Introductory",
          "custom": {
            "id": "XXXXXXXXX"
          }
        }
      ]
  }

Ringing configurations

Ringing configurations define how a call queue distributes incoming calls to its members. There are three available call distribution modes:

• Simultaneous
• Fixed Order
• Longest Idle

These settings can be set via the following API parameters:

If the transfer mode is set to "FixedOrder", the following parameters must be specified

Waiting configurations

Waiting configurations refer to the settings that define how a call queue handles incoming calls while callers are waiting. These parameters help manage call flow and ensure a smooth caller experience. Key settings include:

• Maximum number of callers allowed in the queue - Limits how many callers can wait in the queue at the same time.
• Maximum wait time in queue - Specifies how long a caller can remain in the queue before being redirected (e.g., to voicemail or another extension).
• Number of rings before trying the next member - Determines how many rings occur before the system attempts to connect the call to another available member, each ring equals to 5 seconds and maximum is 60 rings.
• Wrap-up time - Sets a brief period after each call during which the agent is unavailable, allowing time for post-call tasks before taking another call.

Business Hours Forwarding configurations

Forwarding configurations define the actions after a call was ringing but cannot be answered. There are 3 conditions where a call queue can be set to forward an unanswered call.

1. When the queue is full

   • Send to Voicemail - Can be the call queue's own voicemail or another extension's voicemail
   • Play Announcement - Play a prerecorded message
   • Forward to extension - Any type of extension (IVR menu, call queue, user etc.)
   • Forward to external number (Unconditional Forwarding) - Any phone number

2. When the maximum wait time is reached

   • Send to Voicemail - Can be the call queue's own voicemail or another extension's voicemail
   • Forward to extension - Any type of extension (IVR menu, call queue, user etc.)
   • Forward to external number (Unconditional Forwarding) - Any phone number

3. When no one answers

   • WaitPrimaryMembers - Keep waiting for the queue's members to answer the incoming call.
   • WaitPrimaryAndOverflowMembers - Rings members from the overflow group (other call queue) if overflow group was selected.
   • Send to Voicemail - Can be the call queue's own voicemail or another extension's voicemail.
   • Forward to extension - Any type of extension (IVR menu, call queue, user etc.).
   • Forward to external number (Unconditional Forwarding) - Any phone number.

Each of the actions above is set separately to forward the call to a designated destination if one of the conditions is met.

To set the target for the "TransferToExtension" destination, specify the parameters of the queue.transfer object as show in the example below:

  let bodyParams = {
      "queue": {
        "transfer" : [
          {
            "extension" : { "id" : "EXTENSION-ID" },
            "action" : "MaxCallers"
          },{
            "extension" : { "id" : "EXTENSION-ID" },
            "action" : "HoldTimeExpiration"
          }
        ]
      }
  }

To set the target for the "UnconditionalForwarding" destination, specify the parameters of the queue.unconditionalForwarding object as shown in the example below:

  let bodyParams = {
      "queue": {
        "unconditionalForwarding": [
          {
            "phoneNumber" : "PHONE-NUMBER",
            "action" : "MaxCallers"
          }, {
            "phoneNumber" : "PHONE-NUMBER",
            "action" : "HoldTimeExpiration"
          }
        ]
      }
  }

To set the target for the "Voicemail" destination, specify the parameters of the voicemail object as shown in the example below:

  let bodyParams = {
        "voicemail" : {
          "enabled" : true,
          "recipient" : {
            "id" : "EXTENSION-ID" // Identifier of the extension that receive the voicemail. Defaulted to the call queue extension!
          }
        }
  }

To set the target for the "PlayAnnouncement" destination for the maxCallersAction action, specify the parameters of the greetings object as shown in the example below:

let bodyParam = {
  "greetings":[
      {
        "type": "Unavailable",
        "custom": {
          "id": "XXXXXXXXX"
        }
      }
    ]
}

The callHandlingAction parameter of the Business Hours rule is always set to "AgentQueue"

After Hours rule

If business hours are set for a call queue, the system will automatically create an after-hours schedule, which is the inverse of the defined business hours.

The After Hours rule manages call behavior outside of regular business hours. When the office is closed, this rule reroutes calls to voicemail, plays a recorded message, or forwards them to an alternate destination such as another call queue, an extension or a mobile number. It ensures that callers are still acknowledged and provided with relevant information or next steps.

To read the call queue after hours rule, call the following API:

GET /restapi/v1.0/account/~/extension/[CallQueueExtensionId]/answering-rule/after-hours-rule

To set the call queue after hours rule, call the following API with appropriate parameters:

PUT /restapi/v1.0/account/~/extension/[CallQueueExtensionId]/answering-rule/after-hours-rule

After Hours Greeting configurations

After hours greeting configurations define how a caller is informed while they are sent to a voicemail or to be terminated.

You can set a standard greeting or a custom greeting message for the following types:

To set the voicemail greeting message, set the the parameters of the greetings object as shown in the example below (assumed that you have created a custom greeting and have the greeting id "XXXXXXXXX"):

  let bodyParams = {
        "greetings" : [ {
            "type" : "Voicemail",
            "custom" : {
              "id" : "XXXXXXXXX"
            }
        }
  }

To set the announcement message, set the the parameters of the greetings object as shown in the example below (assumed that you have created a custom greeting and have the greeting id "XXXXXXXXX"):

  let bodyParams = {
        "greetings" : [ {
            "type" : "Announcement",
            "custom" : {
              "id" : "XXXXXXXXX"
            }
        }
  }

After Hours Forwarding Configurations

The After Hours rule can be configured to forward incoming calls to the following destinations:

• Send to Voicemail - Can be the call queue's own voicemail or another extension's voicemail
• Play Announcement - Play a prerecorded message
• Forward to extension - Any type of extension (IVR menu, call queue, user)
• Forward to external number (Unconditional Forwarding) - Any phone number

The callHandlingAction parameter of the after hours rule can be set to one of the following values:

To set the target for the "Voicemail" destination, specify the parameters of the voicemail object as shown in the example below:

let bodyParams = {
      callHandlingAction: "TakeMessageOnly",
      voicemail : {
        enabled: true,
        recipient: {
          id : "EXTENSION-ID" // Identifier of the extension that receive the voicemail. Defaulted to the call queue extension!
        }
      }
    }

To customize the announcement message for the "PlayAnnouncementOnly" destination, set the the parameters of the greetings object as shown in the example below (assumed that you have created a custom greeting and have the greeting id "XXXXXXXXX"):

let bodyParam = {
  "greetings":[
      {
        "type": "Unavailable",
        "custom": {
          "id": "XXXXXXXXX"
        }
      }
    ]
}

To set the target for the "TransferToExtension" destination, specify the parameters of the transfer object as show in the example below:

let bodyParams = {
      callHandlingAction: "TransferToExtension",
      transfer : {
          extension : { id : "EXTENSION-ID" }
      }
    }

To set the target for the "UnconditionalForwarding" destination, specify the parameters of the unconditionalForwarding object as shown in the example below:

let bodyParams = {
      callHandlingAction: "UnconditionalForwarding",
      unconditionalForwarding: { phoneNumber : "PHONE-NUMBER" }
    }

Custom rule

Custom rules allow for flexible and tailored call handling based on specific criteria, such as caller ID, called number, or custom time schedules (e.g., holidays or special events). These rules can override both business and after-hours rules to support unique scheduling or routing needs.

Each custom rule can have its own configurations to manage incoming calls. This includes the trigger conditions, greeting messages, ringing and forwarding configurations.

To create a call queue custom rule, call the following API with appropriate parameters:

POST /restapi/v1.0/account/~/extension/[CallQueueExtensionId]/answering-rule

let bodyParam = {
  name: "Custom rule 1",
  type: "Custom",
  ...
}

Trigger configurations

A custom rule can be set with one or more trigger conditions below:

• callers: A list of callers' phone numbers or contact names.
  • callerId: Caller's phone number
  • name: Caller's contact names
• calledNumbers: A list of recipients' phone numbers. It is not typically applied to call queues unless the queue has multiple direct numbers.
  • phoneNumber: A phone number belonging to the call queue.
• schedule: Specified time based schedules.
  • weeklyRanges: Repeatedly for certain week day and time ranges. For example every weekdays during lunch time.
  • ranges: A period of time specified by date and time range. For example a public holiday.
  • ref: Match the "BusinessHours" or "AfterHours".

The following example sets a custom rule to be triggered by the caller numbers "14132223333" and "15093334444" during business hours:

let bodyParams = {
      callers: [
        { callerId: "14132223333" }, { callerId: "15093334444" }, { name: "John Smith" }
      ],
      schedule: { ref: "BusinessHours" }
  }

A custom rule can have one of the following actions. The action is specified by the callHandlingAction parameter:

If the callHandlingAction is set to "AgentQueue", the following configurations can be specified to define how a call queue distributes incoming calls to its members.

Ringing configurations See ringing setting instructions for Business Hours

Waiting configurations See waiting setting instructions for Business Hours

Forwarding configurations See forwarding setting instructions for Business Hours

If the callHandlingAction is set to other actions, the configurations can be specified the same way as for the After Hours rule.

Greeting configurations See greeting setting instructions for After Hours

Forwarding configurations See forwarding setting instructions for After Hours

Creating a Call queue Custom Call Handling Rule

Be mindful of the following when constructing a request to create a custom call handling 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 trigger conditions.
• Specify the action to take using the callHandlingAction parameter.
• Customize the greetings messages with appropriate context.

Finally, make a POST request to the following endpoint:

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

Example use case of a call queue call handling custom rule

Use Case: Prioritized Call Handling for VIP Customers

Let’s assume the call queue Business Hours rule is configured with the following settings:

• Ring members in a fixed order.
• The maximum caller wait time is set to 2 minutes.
• If the queue is full or the wait time limit is reached, calls are routed to voicemail.

This setup works well for general callers. However, we require enhanced call handling for VIP customers who contact us through this call queue number. Specifically, we want VIP calls to receive faster attention and avoid being sent to voicemail.

To address this, we aim to implement a custom rule that identifies VIP callers (e.g., based on their phone numbers) and modifies the default behavior as follows:

• Route their calls to available members immediately, possibly using simultaneous ringing instead of fixed order or the longest idle member.
• The maximum caller wait time is set to 20 seconds.
• If the queue is full or the wait time limit is reached, forward the VIP call to a supervisor rather than sending it to voicemail.

This ensures that VIP customers receive prioritized service, reduced wait times, and a more personalized support experience.

The following example demonstrates how to implement a call queue's custom rule for the above use case.

Assume that we have exported a list of 5 VIP customers from our 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"
        }
    ]

Assume that the call queue extension id and the supervisor extension id are known so we don't need to implement extra code to get the required values. Otherwise, you can call these APIs to get a call queue's extension id and the supervisor's extension id.

• List call queues
• List extensions

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, () => {
    // Provide your call queue extension id and the supervisor extension id!
    create_callqueue_custom_answering_rule("Callqueue-ExtId", "Supervisor-ExtId")
})

platform.on(platform.events.loginError, function(e){
    console.log("Unable to authenticate to platform. Check credentials.", e.message)
    process.exit(1)
});

/*
* Create a call queue custom answering rule
*/
async function create_callqueue_custom_answering_rule(callqueueExtId, supervisorExtId) {
  try {
    let vipCustomerContacts = [
            {
                callerId: "+16501111111",
          name: "Kristina Grant"
            },{
                callerId: "+16502222222",
          name: "Sandra Bell"
            },{
                callerId: "+16503333333",
          name: "David Peterson"
            },{
                callerId: "+16504444444",
          name: "Lena Shanon"
            },{
                callerId: "+16505555555",
          name: "Christine Lee"
            }
        ]
    let bodyParams = {
      enabled: true,
      type: "Custom",
      name: "VIP Support Rule",
      callers: vipCustomerContacts,
      schedule: { ref: "BusinessHours" },
      callHandlingAction: "AgentQueue",
      queue: {
        transferMode: "Simultaneous",
        maxCallers: 10,
        holdTime: 20,
        maxCallersAction: "TransferToExtension",
        holdTimeExpirationAction: "TransferToExtension",
        transfer: [
          {
            extension : { id : supervisorExtId },
            action : "MaxCallers"
          },{
            extension : { id : supervisorExtId },
            action : "HoldTimeExpiration"
          }
        ]
      }
    }

    let endpoint = `/restapi/v1.0/account/~/extension/${callqueueExtId}/answering-rule`
    var resp = await platform.post(endpoint, bodyParams)
    var jsonObj = await resp.text()
    console.log(jsonObj)
  } catch (e) {
    console.log("Unable to create a call queue custom answering rule. ", e.message);
  }
}

from ringcentral import SDK
import json

#
# Create a call queue custom answering rule
#
def create_callqueue_custom_answering_rule(callqueueExtId, supervisorExtId):
    try:
        vip_customer_contacts = [
            {
                "callerId": "+16501111111",
                "name": "Kristina Grant"
            },{
                "callerId": "+16502222222",
                "name": "Sandra Bell"
            },{
                "callerId": "+16503333333",
                "name": "David Peterson"
            },{
                "callerId": "+16504444444",
                "name": "Lena Shanon"
            },{
                "callerId": "+16505555555",
                "name": "Christine Lee"
            }
        ]

        body_params = {
            "enabled": True,
            "type": "Custom",
            "name": "VIP Support Rule",
            "callers": vip_customer_contacts,
            "schedule": {
                "ref": "BusinessHours"
            },
            "callHandlingAction": "AgentQueue",
            "queue": {
                "transferMode": "Simultaneous",
                "maxCallers": 10,
                "holdTime": 20,
                "maxCallersAction": "TransferToExtension",
                "holdTimeExpirationAction": "TransferToExtension",
                "transfer": [
                    {
                        "extension": {
                            "id": supervisorExtId
                        },
                        "action": "MaxCallers"
                    },
                    {
                        "extension": {
                            "id": supervisorExtId
                        },
                        "action": "HoldTimeExpiration"
                    }
                ]
            }
        }
        endpoint = f'/restapi/v1.0/account/~/extension/{callqueueExtId}/answering-rule'
        resp = platform.post(endpoint, body_params)
        jsonObj = resp.json_dict()
        print(json.dumps(jsonObj, indent=2, sort_keys=True))
    except Exception as e:
      print ("Unable to create a call queue custom answering rule. " + str(e))


# Authenticate a user using a personal JWT token
def login():
  try:
      platform.login( jwt= "RC_USER_JWT" )
      # Provide your call queue extension id and the supervisor extension id!
      create_callqueue_custom_answering_rule("Callqueue-ExtId", "Supervisor-ExtId")
  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()

<?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']);
// Provide your call queue extension id and the supervisor extension id!
create_callqueue_custom_answering_rule("Callqueue-ExtId", "Supervisor-ExtId");

/*
* Create a call queue custom answering rule
*/
function create_callqueue_custom_answering_rule($callqueueExtId, $supervisorExtId) {
  global $platform;
  try {
    $vipCustomerContacts = [
          [
            "callerId" => "+16501111111",
            "name" => "Kristina Grant"
          ],
          [
            "callerId" => "+16502222222",
            "name" => "Sandra Bell"
          ],
          [
            "callerId" => "+16503333333",
            "name" => "David Peterson"
          ],
          [
            "callerId" => "+16504444444",
            "name" => "Lena Shanon"
          ],
          [
            "callerId" => "+16505555555",
            "name" => "Christine Lee"
          ]
      ];

      $bodyParams = [
          'enabled' => true,
          'type' => 'Custom',
          'name' => 'VIP Support Rule',
          'callers' => $vipCustomerContacts,
          'schedule' => [
              'ref' => 'BusinessHours'
          ],
          'callHandlingAction' => 'AgentQueue',
          'queue' => [
              'transferMode' => 'Simultaneous',
              'maxCallers' => 10,
              'holdTime' => 20,
              'maxCallersAction' => 'TransferToExtension',
              'holdTimeExpirationAction' => 'TransferToExtension',
              'transfer' => [
                  [
                      'extension' => [
                          'id' => $supervisorExtId
                      ],
                      'action' => 'MaxCallers'
                  ],
                  [
                      'extension' => [
                          'id' => $supervisorExtId
                      ],
                      'action' => 'HoldTimeExpiration'
                  ]
              ]
          ]
      ];
    $endpoint = "/restapi/v1.0/account/~/extension/".$callqueueExtId."/answering-rule";
    $resp = $platform->post($endpoint, $bodyParams);
    print_r ($resp->json());
  }catch (\RingCentral\SDK\Http\ApiException $e) {
    // Getting error messages using PHP native interface
    print 'Unable to create a call queue custom answering rule: ' . $e->getMessage() . PHP_EOL;
  }
}
?>

require 'ringcentral'

#
# Create a call queue custom answering rule
#
def create_callqueue_custom_answering_rule(callqueueExtId, supervisorExtId)
  begin
    vip_customer_contacts = [
        {
            callerId: "+16501111111",
          name: "Kristina Grant"
        },{
            callerId: "+16502222222",
          name: "Sandra Bell"
        },{
            callerId: "+16503333333",
          name: "David Peterson"
        },{
            callerId: "+16504444444",
          name: "Lena Shanon"
        },{
            callerId: "+16505555555",
          name: "Christine Lee"
        }
      ]

    body_params = {
      enabled: true,
      type: "Custom",
      name: "VIP Support Rule",
      callers: vip_customer_contacts,
      schedule: {
        ref: "BusinessHours"
      },
      callHandlingAction: "AgentQueue",
      queue: {
        transferMode: "Simultaneous",
        maxCallers: 10,
        holdTime: 20,
        maxCallersAction: "TransferToExtension",
        holdTimeExpirationAction: "TransferToExtension",
        transfer: [
          {
            extension: {
              id: supervisorExtId
            },
            action: "MaxCallers"
          },
          {
            extension: {
              id: supervisorExtId
            },
            action: "HoldTimeExpiration"
          }
        ]
      }
    }
    endpoint = "/restapi/v1.0/account/~/extension/" + callqueueExtId + "/answering-rule"
    resp = $platform.post(endpoint, payload: body_params)
    puts(resp.body)
  rescue StandardError => e
    puts ("Unable to create a call queue custom answering rule. " + e.to_s)
  end
end

# Authenticate a user using a personal JWT token
def login()
  begin
    $platform.authorize( jwt: "RC_USER_JWT" )
    # Provide your call queue extension id and the supervisor extension id!
      create_callqueue_custom_answering_rule("Callqueue-ExtId", "Supervisor-ExtId")
  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()

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/...",
  "id" : "9421686016",
  "type" : "Custom",
  "name" : "VIP Support Rule",
  "enabled" : true,
  "schedule" : {
    "ref" : "BusinessHours"
  },
  "callers" : [ {
    "callerId" : "16501111111",
    "name" : "Kristina Grant"
  }, {
    "callerId" : "16502222222",
    "name" : "Sandra Bell"
  }, {
    "callerId" : "16503333333",
    "name" : "David Peterson"
  }, {
    "callerId" : "16504444444",
    "name" : "Lena Shanon"
  }, {
    "callerId" : "16505555555",
    "name" : "Christine Lee"
  } ],
  ...
  "callHandlingAction" : "AgentQueue",
  "queue" : {
    "transferMode" : "Simultaneous",
    ...
    "holdAudioInterruptionMode" : "Never",
    "agentTimeout" : 20,
    "wrapUpTime" : 15,
    "holdTime" : 20,
    "maxCallers" : 10,
    "maxCallersAction" : "TransferToExtension",
    "holdTimeExpirationAction" : "TransferToExtension",
    "transfer" : [ {
      "extension" : {
        "id" : "62576913016",
        "extensionNumber" : "22907",
        "name" : "Tom Brown"
      },
      "action" : "HoldTimeExpiration"
    }, {
      "extension" : {
        "id" : "62576913016",
        "extensionNumber" : "22907",
        "name" : "Tom Brown"
      },
      "action" : "MaxCallers"
    } ]
  },
  ...
}