Call Queue Member Status (Presence)

Last updated: 2021-01-12

Contributors

The Call Queue Presence (Status) APIs allow developers to develop a call queue management application, which can control call queues and members of a call queue to receive or by-pass incoming calls via a call queue dynamically.

The User Presence APIs can be used together with the Call Queue Presence APIs to build sophisticated call routing application.

List company call queues

To list all call queues of an account, make a GET request to the /restapi/v1.0/account/~/call-queues endpoint.

Required permission(s): ReadAccounts

Sample code to list all company call queues

HTTP

GET /restapi/v1.0/account/~/call-queues HTTP/1.1
Content-Type: application/json

JavaScript

const RC = require('@ringcentral/sdk').SDK
require('dotenv').config();

var rcsdk = new RC({
    'server':       process.env.RC_SERVER_URL,
    'clientId':     process.env.RC_CLIENT_ID,
    'clientSecret': process.env.RC_CLIENT_SECRET
});
var platform = rcsdk.platform();
platform.login({ 'jwt':  process.env.RC_JWT })

platform.on(platform.events.loginSuccess, async function(response) {
  try {
    var resp = await platform.get('/restapi/v1.0/account/~/call-queues')
    var jsonObj = await resp.json()
    console.log(jsonObj)
  } catch (e) {
    console.log(e.message)
  }
});

Python

#!/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_CLIENT_ID'),
             os.environ.get('RC_CLIENT_SECRET'),
             os.environ.get('RC_SERVER_URL') )
platform = rcsdk.platform()
try:
  platform.login( jwt=os.environ.get('RC_JWT') )
except Exception as e:
  sys.exit("Unable to authenticate to platform: " + str(e))

try:
    resp = platform.get('/restapi/v1.0/account/~/call-queues')
    records = resp.json().records
    if len(records) == 0:
        print( f'No call queues were found for the current account' )
    else:
        for r in records:
            print( f'Call queue: name = {r["name"]}, extension = {r["extension"]}' )

except ApiException as e:
    sys.exit( e )
else:
    sys.exit( 0 )

Sample response

{
  "uri": '...',
  "records": [
    {
      "uri": 'https://platform.ringcentral.com/restapi/v1.0/account/809646000/extension/1081167000',
      "id": '1081167000',
      "extensionNumber": '11131',
      "name": 'Sample call queue'
    },{
      "uri": 'https://platform.ringcentral.com/restapi/v1.0/account/809646000/extension/61986637000',
      "id": '61986637000',
      "extensionNumber": '11400',
      "name": 'Demo call queue'
    }
  ],
  "paging": { ... },
  "navigation": { ... }
}

Read a call queue's info

Each call queue has the boolean editableMemberStatus property to specify whether or not its members are allowed to change their queue status.

To check if members of call queue can change their status or not, make a GET request to the /restapi/v1.0/account/~/call-queues/[callQueueId] endpoint then check the editableMemberStatus.

Required permission(s): ReadAccounts

Sample code to read call queue member status editable property

HTTP

GET /restapi/v1.0/account/~/call-queues/1081167016 HTTP/1.1
Content-Type: application/json

JavaScript

const RC = require('@ringcentral/sdk').SDK
require('dotenv').config();

var rcsdk = new RC({
    'server':       process.env.RC_SERVER_URL,
    'clientId':     process.env.RC_CLIENT_ID,
    'clientSecret': process.env.RC_CLIENT_SECRET
});
var platform = rcsdk.platform();
platform.login({ 'jwt':  process.env.RC_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 record of jsonObj.records) {
      if (record.name == "Demo call queue")
        read_call_queue_info(record.id)
    }
  } catch (e) {
    console.log(e.message)
  }
}

async function read_call_queue_info(id){
  try {
    var resp = await platform.get(`/restapi/v1.0/account/~/call-queues/${id}`)
    var jsonObj = await resp.json()
    console.log(jsonObj)
  }catch(e){
    console.log(e.message)
  }
}

Python

#!/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_CLIENT_ID'),
             os.environ.get('RC_CLIENT_SECRET'),
             os.environ.get('RC_SERVER_URL') )
platform = rcsdk.platform()
try:
  platform.login( jwt=os.environ.get('RC_JWT') )
except Exception as e:
  sys.exit("Unable to authenticate to platform: " + str(e))

def get_account_call_queues():
    try:
        resp = platform.get('/restapi/v1.0/account/~/call-queues')
        for record in resp.json().records:
            if record.name == "Demo call queue":
                read_call_queue_info(record.id)
    except ApiException as e:
        print (e)

def read_call_queue_info(id):
    try:
        resp = platform.get('/restapi/v1.0/account/~/call-queues/' + id)
        print (resp.text())
    except ApiException as e:
            print (e)

get_account_call_queues()

Sample response

{
  "id": '1081167016',
  "name": 'Sample',
  "extensionNumber": '11131',
  "status": 'Enabled',
  "editableMemberStatus": false
}

Enable/disable call queue members to change their status

To enable or disable call queue members to change their status, make a PUT request to the /restapi/v1.0/account/~/call-queues/[callQueueId] endpoint with the editableMemberStatus property in request body set to true or false, respectively.

Required permission(s): EditExtensions

Request

HTTP

PUT /restapi/v1.0/account/~/call-queues/1081167016 HTTP/1.1
Content-Type: application/json   

{
   "editableMemberStatus": true
}

JavaScript

const RC = require('@ringcentral/sdk').SDK
require('dotenv').config();

var rcsdk = new RC({
    'server':       process.env.RC_SERVER_URL,
    'clientId':     process.env.RC_CLIENT_ID,
    'clientSecret': process.env.RC_CLIENT_SECRET
});
var platform = rcsdk.platform();
platform.login({ 'jwt':  process.env.RC_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) {
      get_call_queue_config(record.id)
    }
  } catch (e) {
    console.log(e.message)
  }
}

async function get_call_queue_config(id){
  try{
    var resp = await platform.get(`/restapi/v1.0/account/~/call-queues/${id}`)
    var jsonObj = await resp.json()
    if (jsonObj.editableMemberStatus == false)
      enable_call_queue_editable(jsonObj.id)
  }catch(e){
    console.log(e.message)
  }
}

async function enable_call_queue_editable(id){
  try{
    var params = {
      editableMemberStatus: true
    }
    var resp = await platform.put(`/restapi/v1.0/account/~/call-queues/${id}`, params)
    var jsonObj = await resp.json()
  }catch(e){
    console.log(e.message)
  }
}

Python

#!/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_CLIENT_ID'),
             os.environ.get('RC_CLIENT_SECRET'),
             os.environ.get('RC_SERVER_URL') )
platform = rcsdk.platform()
try:
  platform.login( jwt=os.environ.get('RC_JWT') )
except Exception as e:
  sys.exit("Unable to authenticate to platform: " + str(e))

def get_account_call_queues():
    try:
        resp = platform.get('/restapi/v1.0/account/~/call-queues')
        for record in resp.json().records:
            get_call_queue_config(record.id)
    except ApiException as e:
        print (e)

def get_call_queue_config(id):
    try:
        resp = platform.get('/restapi/v1.0/account/~/call-queues/' + id)
        jsonObj = resp.json()
        if jsonObj.editableMemberStatus == False:
            enable_call_queue_editable(jsonObj.id)
    except ApiException as e:
            print (e)

def enable_call_queue_editable(id):
    try:
        resp = platform.put('/restapi/v1.0/account/~/call-queues/' + id,
        {
            "editableMemberStatus": True
        })
        print (resp.text())
    except ApiException as e:
        print (e)

get_account_call_queues()

Read Call Queue Members Status

Each member of a call queue has 2 different call queue statuses:

The acceptQueueCalls status specifies if the member will receive or ignore incoming calls via any call queue it belongs to. This member queue status reflects the member's DnD presence status.
The acceptCurrentQueueCalls status specifies if the member will receive or ignore incoming calls via a single (the current) call queue it belongs to.

To read a call queue's members status, make a GET request to the endpoint /restapi/v1.0/account/~/call-queues/[callQueueId]/presence.

Required permission(s): ReadPresence

Sample code to read call queue member status

HTTP

GET /restapi/v1.0/account/~/call-queues/[callQueueId]/presence HTTP/1.1
Content-Type: application/json

JavaScript

const RC = require('@ringcentral/sdk').SDK
require('dotenv').config();

var rcsdk = new RC({
    'server':       process.env.RC_SERVER_URL,
    'clientId':     process.env.RC_CLIENT_ID,
    'clientSecret': process.env.RC_CLIENT_SECRET
});
var platform = rcsdk.platform();
platform.login({ 'jwt':  process.env.RC_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 record of jsonObj.records) {
      if (record.name == "Demo call queue")
        read_call_queue_member_status(record.id)
    }
  } catch (e) {
    console.log(e.message)
  }
}

async function read_call_queue_member_status(id){
  try {
    var resp = await platform.get(`/restapi/v1.0/account/~/call-queues/${id}/presence`)
    var jsonObj = await resp.json()
    console.log(jsonObj)
  }catch(e){
    console.log(e.message)
  }
}

Python

#!/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_CLIENT_ID'),
             os.environ.get('RC_CLIENT_SECRET'),
             os.environ.get('RC_SERVER_URL') )
platform = rcsdk.platform()
try:
  platform.login( jwt=os.environ.get('RC_JWT') )
except Exception as e:
  sys.exit("Unable to authenticate to platform: " + str(e))

def get_account_call_queues():
    resp = platform.get('/restapi/v1.0/account/~/call-queues')
    jsonObj = resp.json()
    return jsonObj.records

def print_call_queue_member_status( id ):
    resp = platform.get('/restapi/v1.0/account/~/call-queues/' + id + "/presence")
    for r in resp.json().records:
        for m in r.members:
            print( f'- {m.name}: {m.acceptCurrentQueueCalls}' )

try:
    queues = get_account_call_queues()
    for q in queues:
        print( f'Found call queue: {q.name}' )
        print_call_queue_member_status( q.id )
except ApiException as e:
    sys.exit(e)
else:
    sys.exit(0)

Sample response

{ "records" : [
  {
    "member":
    {
      "id": '979428000',
      "name": 'James Smith',
      "extensionNumber": '12104',
      "site": { "id": '62366997000', "name": 'Main Site' }
    },
    "acceptQueueCalls": true,
    "acceptCurrentQueueCalls": true
  },{
    "member": {...},
    "acceptQueueCalls": true,
    "acceptCurrentQueueCalls": false
  },{
    "member": {...},
    "acceptQueueCalls": true,
    "acceptCurrentQueueCalls": true }
  ]
}

Update Call Queue Member Status

Every member in a call queue can decide if it wants to receive incoming calls via the call queue or not.

To change a member or several members status of a call queue to receive or reject incoming calls via that call queue, make a PUT request to the /restapi/v1.0/account/~/call-queues/[callQueueId]/presence endpoint with the acceptCurrentQueueCalls property in request body set to true or false, respectively.

A great use case is, for example, a tech support team consists of 8 agents who take incoming calls via a "Support call queue", 4 agents will be on-duty from 8:00 to 12:00 and the other 4 agents will be on-duty from 12:00 to 16:00. You can use this API to change the status of all the agents according to their on-duty/off-duty schedule.

Required permission(s): EditPresence

Sample code to enable/disable a call queue's member status

HTTP

PUT /restapi/v1.0/account/~/call-queues/1081167016/presence HTTP/1.1
Content-Type: application/json   

{
   "records": [
    {
      "member": { "id" : "111111111" },
      "acceptCurrentQueueCalls": true
    },
    {
      "member": { "id" : "222222222" },
      "acceptCurrentQueueCalls": false
    },
   ]
}

JavaScript

const RC = require('@ringcentral/sdk').SDK
require('dotenv').config();

var rcsdk = new RC({
    'server':       process.env.RC_SERVER_URL,
    'clientId':     process.env.RC_CLIENT_ID,
    'clientSecret': process.env.RC_CLIENT_SECRET
});
var platform = rcsdk.platform();
platform.login({ 'jwt':  process.env.RC_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 record of jsonObj.records) {
        if (record.name == "Demo call queue"){
        await update_call_queue_member_status(record.id)
        }
    }
    } catch (e) {
    console.log(e.message)
    }
}

async function update_call_queue_member_status(id){
  try {
    var params = {
      records: [
        {
          member: { id : "111111111" },
          acceptCurrentQueueCalls: false
        },
        {
          member: { id : "222222222" },
          acceptCurrentQueueCalls: true
        },
        {
          member: { id : "333333333" },
          acceptCurrentQueueCalls: false
        }
       ]
    }
    var resp = await platform.put(`/restapi/v1.0/account/~/call-queues/${id}/presence`, params)
    var jsonObj = await resp.json()
    console.log(jsonObj)
  }catch(e){
    console.log(e.message)
  }
}

Python

#!/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_CLIENT_ID'),
             os.environ.get('RC_CLIENT_SECRET'),
             os.environ.get('RC_SERVER_URL') )
platform = rcsdk.platform()
try:
  platform.login( jwt=os.environ.get('RC_JWT') )
except Exception as e:
  sys.exit("Unable to authenticate to platform: " + str(e))

def get_account_call_queues():
    try:
        resp = platform.get('/restapi/v1.0/account/~/call-queues')
        for record in resp.json().records:
            if record.name == "Demo call queue":
              update_call_queue_member_status(record.id)
    except ApiException as e:
        print (e)


def update_call_queue_member_status(id):
    try:
        resp = platform.put('/restapi/v1.0/account/~/call-queues/' + id + '/presence',
        {
            "records": [
              {
                "member": { "id" : "111111111" },
                "acceptCurrentQueueCalls": False
              },
              {
                "member": { "id" : "222222222" },
                "acceptCurrentQueueCalls": True
              },
              {
                "member": { "id" : "333333333" },
                "acceptCurrentQueueCalls": False
              }
             ]
        })
        print (resp.text())
    except ApiException as e:
        print (e)

get_account_call_queues()

Note

The member id in the record object is the extension id of the member

Update Extension's Call Queues Status

To change the status of a member of a call queue or several call queues, in which the member belongs to, to receive or reject incoming calls via those call queues, make a PUT request to the /restapi/v1.0/account/~/extension/[extensionId]/call-queue-presence endpoint with the acceptCalls property in request body set to true or false, respectively.

A great use case is, for example, a receptionist who works for 2 different doctors in the same clinic. Monday to Wednesday she takes incoming calls from a call queue for doctor A. And Thursday to Friday she takes incoming calls from a call queue for doctor B. You can use this API to change the status of the receptionist to receive incoming calls from each call queue based on her schedule.

Required permission(s): EditPresence

Sample code to enable/disable extension call queue member status

HTTP

PUT /restapi/v1.0/account/~/extension/111111111/call-queue-presence HTTP/1.1
Content-Type: application/json   

{
   "records": [
    {
      "callqueue": { "id" : "1081167000" },
      "acceptCalls": true
    },
    {
      "callqueue": { "id" : "62284876000" },
      "acceptCalls": false
    }
   ]
}

JavaScript

const RC = require('@ringcentral/sdk').SDK
require('dotenv').config();

var rcsdk = new RC({
    'server':       process.env.RC_SERVER_URL,
    'clientId':     process.env.RC_CLIENT_ID,
    'clientSecret': process.env.RC_CLIENT_SECRET
});
var platform = rcsdk.platform();
platform.login({ 'jwt':  process.env.RC_JWT })

platform.on(platform.events.loginSuccess, async function(response) {
  update_extension_call_queue_status()
});

async function update_extension_call_queue_status(){
  try {
    var params = {
      records: [
        {
          callQueue: { id : "62376752000" },
          acceptCalls: true
        },
        {
          callQueue: { id : "62284876000" },
          acceptCalls: false
        }
       ]
    }
    var resp = await platform.put(`/restapi/v1.0/account/~/extension/~/call-queue-presence`, params)
    var jsonObj = await resp.json()
    console.log(jsonObj)
  }catch(e){
    console.log(e.message)
  }
}

Python

#!/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_CLIENT_ID'),
             os.environ.get('RC_CLIENT_SECRET'),
             os.environ.get('RC_SERVER_URL') )
platform = rcsdk.platform()
try:
  platform.login( jwt=os.environ.get('RC_JWT') )
except Exception as e:
  sys.exit("Unable to authenticate to platform: " + str(e))

try:
    resp = platform.put('/restapi/v1.0/account/~/extension/~/call-queue-presence',
    {
        "records": [
          {
            "callQueue": { "id" : "62376752000" },
            "acceptCalls": True
          },
          {
            "callQueue": { "id" : "62284876000" },
            "acceptCalls": False
          }
         ]
    })
    print (resp.text())
except ApiException as e:
    print (e)

Note

The call queue id in the record object is the extension id of the call queue extension
An extension can change its acceptCalls status to receive or reject incoming calls via that call queue only if the call queue editableMemberStatus property is set to true.

Enable/disable call queue member's `acceptQueueCalls` status

A call queue member can decide to receive or reject incoming calls via all call queues he/she belongs to. This feature is controlled by the acceptQueueCalls property of a member in a call queue. The value can be set using the member's DnD (Do not Disturb) presence status.

{
  "member":
  {
    "id": '979428000',
    "name": 'James Smith',
    "extensionNumber": '12104',
    "site": { "id": '62366997000', "name": 'Main Site' }
  },
  "acceptQueueCalls": true,
  "acceptCurrentQueueCalls": true
}

Note

If a call queue's member DnD status is set to DoNotAcceptAnyCalls, the acceptQueueCalls value if that member in all call queues he/she belongs to will be false and the member will not receive any incoming calls directly or via call queues.
If a call queue's member DnD status is set to DoNotAcceptDepartmentCalls, the acceptQueueCalls value if that member in all call queues he/she belongs to will be false and the member will not receive any incoming calls via call queues, whilst the member still can receive direct incoming calls to his/her own numbers.

To disable a call queue's member taking incoming calls via all call queues it belongs to, make a PUT request to the /restapi/v1.0/account/~/extension/[extensionId]/presence endpoint with the dndStatus property in request body set to DoNotAcceptDepartmentCalls.

To enable a call queue's member taking incoming calls via all call queues it belongs to, make a PUT request to the /restapi/v1.0/account/~/extension/[extensionId]/presence endpoint with the dndStatus property in request body set to TakeAllCalls.

Required permission(s): EditPresence

Sample code to enable/disable a call queue's member status

HTTP

PUT /restapi/v1.0/account/~/extension/111111111/presence HTTP/1.1
Content-Type: application/json   

{
   "dndStatus": "DoNotAcceptDepartmentCalls"
}

JavaScript

const RC = require('@ringcentral/sdk').SDK
require('dotenv').config();

var rcsdk = new RC({
    'server':       process.env.RC_SERVER_URL,
    'clientId':     process.env.RC_CLIENT_ID,
    'clientSecret': process.env.RC_CLIENT_SECRET
});
var platform = rcsdk.platform();
platform.login({ 'jwt':  process.env.RC_JWT })

platform.on(platform.events.loginSuccess, async function(response) {
  update_extension_dnd_status()
});

async function update_extension_dnd_status(){
  try {
    var params = {
      dndStatus: "DoNotAcceptDepartmentCalls"
    }
    var resp = await platform.put(`/restapi/v1.0/account/~/extension/~/presence`, params)
    var jsonObj = await resp.json()
    console.log(jsonObj)
  }catch(e){
    console.log(e.message)
  }
}

Python

#!/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_CLIENT_ID'),
             os.environ.get('RC_CLIENT_SECRET'),
             os.environ.get('RC_SERVER_URL') )
platform = rcsdk.platform()
try:
  platform.login( jwt=os.environ.get('RC_JWT') )
except Exception as e:
  sys.exit("Unable to authenticate to platform: " + str(e))

try:
    status = "DoNotAcceptDepartmentCalls"
    resp = platform.put('/restapi/v1.0/account/~/extension/~/presence',
                        { "dndStatus": status })
    print( f'Do not disturb status set to {status}' )
except ApiException as e:
    sys.exit(e)
else:
    sys.exit(0)

Important

Do not use the TakeDepartmentCallsOnly value to set a member's DnD status. It is existed for legacy purpose only and is not supported via API.

Call Queue Member Status (Presence)

List company call queues

Sample code to list all company call queues

Sample response

Read a call queue's info

Sample code to read call queue member status editable property

Sample response

Enable/disable call queue members to change their status

Request

Read Call Queue Members Status

Sample code to read call queue member status

Sample response

Update Call Queue Member Status

Sample code to enable/disable a call queue's member status

Update Extension's Call Queues Status

Sample code to enable/disable extension call queue member status

Enable/disable call queue member's acceptQueueCalls status

Sample code to enable/disable a call queue's member status

Enable/disable call queue member's `acceptQueueCalls` status