Call Queues

Last updated: 2024-08-15Contributors
Edit this page

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, where groupId 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 the groupId 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