Call Queues
A call queue is a special extension that can hold a group of user extensions (members). It provides a convenient way to have multiple people (a department) respond to incoming calls.
As an extension, a call queue has a name, an extension number and can be assigned with a direct phone number as well. When a call is directed to the call queue's extension, the call is connected with the members of group in several ways depending on the settings of the call queue:
- Rotating - Regularly change the order that you ring available members to evenly distribute calls.
- Simultaneous - Ring all available members at the same time. You can do this for up to 10 extensions.
- Sequential - Ring available members one at a time in the order you set.
Create a Call Queue
Typically, to create a call queue extension, an administrator would login to your RingCentral account at Online Account Portal, choose the "Phone System" tab then go under the Group(s) option. Click the "New Call Queue" button to start creating a new one.
However, you can create a call queue by using the extension
API:
- Make a POST request to the
/restapi/v1.0/account/~/extension
endpoint.
Required permission(s): EditAccounts
{
"extensionNumber": "307",
"type": "Department",
"contact": {
"firstName": "Marketing Q",
"email": "[email protected]" }
}
Note
Make sure you set the type
to "Department" to create a queue instead of an extension.
Sample Response
{
"uri": "https://platform.ringcentral.com/restapi/v1.0/account/11111111/extension/11112222",
"id": 11112222,
"extensionNumber": "307",
"contact": {
"firstName": "Marketing Q",
"email": "[email protected]",
"pronouncedName": {
"type": "Default",
"text": "Marketing Q"
}
},
"name": "Marketing Q",
"type": "Department",
"status": "NotActivated",
...
"hidden": false
}
Read Call Queue List
To read all call queue extensions from an account:
- Make a GET request to the
/restapi/v1.0/account/~/call-queues
endpoint.
Required permission(s): ReadAccounts
Sample Response
{
"uri":"https://platform.ringcentral.com/restapi/v1.0/account/809646000/call-queues?page=1&perPage=100",
"records":[
{
"uri":"https://platform.ringcentral.com/restapi/v1.0/account/809646000/extension/1081167016",
"id":"1081167016",
"extensionNumber":"11131",
"name":"Sale representative queue"
},{
"uri":"https://platform.ringcentral.com/restapi/v1.0/account/809646000/extension/61986637016",
"id":"61986637016",
"extensionNumber":"11132",
"name":"Product support queue"
},{
...
}
],
"paging":{...}
}
Alternatively, you can read all call queue extensions from an account using the extension
API together with the query filter /restapi/v1.0/account/~/extension?type=Department
Read Call Queue members
To read all members (user extensions) of a call queue:
- Make a GET request to the
/restapi/v1.0/account/{accountId}/call-queues/[groupId]/members
endpoint, wheregroupId
is the id of a call queue.
Hint
A valid groupId
can be retrieved using the previous API to read all call queue extensions.
Required permission(s): ReadAccounts
Sample Response
{
"uri" : "https://platform.ringcentral.com/restapi/v1.0/account/11111111/department/22223333/members?page=1&perPage=100",
"records" : [
{
"uri" : "https://platform.ringcentral.com/restapi/v1.0/account/11111111/extension/11112222",
"id" : 11112222,
"extensionNumber" : "101"
},
{
"uri" : "https://platform.ringcentral.com/restapi/v1.0/account/11111111/extension/11113333",
"id" : 11113333,
"extensionNumber" : "102"
}
],
...
}
Update Call Queue members
Members can be added to and removed from an existing call queue.
To add new member(s) to a call queue:
- Specify the
addedExtensionIds
array and add new member(s) with their extension id.
To remove existing member(s) from a call queue:
-
Specify the
removedExtensionIds
array and add existing member(s) with their extension id. -
Make a POST request to the
/restapi/v1.0/account/{accountId}/call-queues/[groupId]/bulk-assign
endpoint, where thegroupId
is the id of the call queue extension to be updated.
Notes
You can specify both addedExtensionIds
and removedExtensionIds
parameters to add new members to and to remove old members from a call queue in a single post request.
Required permission(s): EditExtensions
Sample code to update a call queue's members
The following code sample shows how to add 2 new members to a call queue named "Support Department". Presumed that the "Support Department" call queue exists and the new members' extension id is "888888888" and "999999999", respectively.
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, async function(response) {
get_call_queues()
});
async function get_call_queues() {
try {
var resp = await platform.get('/restapi/v1.0/account/~/call-queues')
var jsonObj = await resp.json()
for (var group of jsonObj.records) {
if (group.name == "Support Department") {
add_new_members(group.id)
break
}
}
} catch (e) {
console.log(e.message)
}
}
async function add_new_members(groupId) {
var params = {
addedExtensionIds: ["888888888", "999999999"]
}
try {
var resp = await platform.post('/restapi/v1.0/account/~/call-queues/' + groupId + '/bulk-assign', 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))
try:
resp = platform.get('/restapi/v1.0/account/~/call-queues')
for group in resp.json().records:
if group.name == 'Support Department':
resp = platform.post('/restapi/v1.0/account/~/call-queues/'+group.id+"/bulk-assign",{
'addedExtensionIds': ['888888888', '999999999']
})
print (resp.response())
break
except Exception as e:
sys.exit( f'Could not assign extensions to call queue: {e}' )
else:
sys.exit( 0 )
<?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'] ] );
$resp = $platform->get('/account/~/call-queues');
foreach ($resp->json()->records as $group){
if ($group->name == "Support Department"){
$params = array(
'addedExtensionIds' => array("888888888", "999999999")
);
$resp = $platform->post('/account/~/call-queues/'.$group->id.'/bulk-assign', $params);
print_r($resp->response());
break;
}
}
?>
using System;
using System.Threading.Tasks;
using RingCentral;
namespace Update_CallQueue_Members
{
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 add_callqueue_members();
}
static private async Task add_callqueue_members()
{
var resp = await restClient.Restapi().Account().CallQueues().Get();
foreach (var group in resp.records)
{
if (group.name == "Support Department")
{
var parameters = new CallQueueBulkAssignResource();
parameters.addedExtensionIds = new string[] { "888888888", "999999999" };
await restClient.Restapi().Account().CallQueues(group.id).BulkAssign().Post(parameters);
Console.WriteLine("Members added");
break;
}
}
}
}
}
package com.ringcentral;
import com.ringcentral.*;
import com.ringcentral.definitions.*;
import java.io.IOException;
public class UpdateCallQueueMembers {
static RestClient rc;
public static void main(String[] args) {
var obj = new UpdateCallQueueMembers();
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.add_callqueue_members();
} catch (RestException | IOException e) {
e.printStackTrace();
}
}
public void add_callqueue_members() throws RestException, IOException {
ListCallQueuesParameters cqParameters = new ListCallQueuesParameters();
CallQueues resp = rc.restapi().account().callQueues().list( cqParameters );
for (var group : resp.records) {
if (group.name.equals("Sales team")) {
var parameters = new CallQueueBulkAssignResource();
parameters.addedExtensionIds = new String[] {"888888888", "999999999"};
rc.restapi().account().callQueues(group.id).bulkAssign().post(parameters);
System.out.println("Members added.");
break;
}
}
}
}
#!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'])
response = $rc.get('/restapi/v1.0/account/~/call-queues')
for group in response.body['records'] do
if group['name'] == "Support Department"
params = {
addedExtensionIds: ["888888888", "999999999"]
}
response = $rc.post('/restapi/v1.0/account/~/call-queues/'+group['id']+'/bulk-assign',
payload: params)
puts response.status
break
end
end