Managing Call Queues - Updating Member Status
Overview
RingCentral Call Queues are a common way to assign responsibility for answering calls to an extension to multiple users.
The RingCentral API can be used to automate the scheduling of which members are currently active and inactive on the call queue, a useful feature when managing on call users via an external application. This can be done by updating the status of a queue member's Do Not Disturb (DND) status via the user extension's presence dndStatus
property as described here.
Since this requires managing the extension presence on individual extensions, an administration extension authorization grant is necessary.
Synopsis
The following presents useful code for managing call queue member status given a call queue extension number with existing members. The Details section below discusses each of these steps in more detail and identifies the code being used in the SDK for reference.
# Instantiate client SDK and authorize as administrator
client = RingCentralSdk::REST::Client.new ...
client.authorize_password ... # can be ROPC grant or authorization code grant
# Retrieve a Call Queue Extension by Extension Number to Store in Your App
call_queue_extension_number = 201
extensions = RingCentralSdk::REST::Cache::Extensions.new client
extensions.retrieve_all
call_queue = extensions.get_extension_by_number call_queue_extension_number
# Retrieve Call Queue Members by Call Queue Id to Map to Your User Database
call_queue_members = extensions.get_department_members call_queue['id']
# Enable and Disable Call Queue Member Status
extension_id = call_queue_members[0]['id']
extension_presence = RingCentralSdk::ExtensionPresence.new client, extension_id
## Enable Call Queue calls
extension_presence.department_calls_enable true
## Disable Call Queue calls
extension_presence.department_calls_enable false
## Check Call Queue calls enabled
extension_presence.department_calls_enabled? # true or false
Details
Integration with a third-party scheduling service can involve the following steps:
- Create and Add Users to a Call Queue
- Configure the RingCentral Call Queue in the Scheduling Application
- Updating User Call Queue Status
These steps are described below including general steps as well as code using the Ruby SDK. To see how the general steps are implemented, refer to the classes referenced below in GitHub.
Step 1: Create and Add Users to a Call Queue
Using the RingCentral Online Account Portal, create a call queue and add user extensions to the queue as documented in RingCentral Office Admin Guide.
Step 2: Configure the RingCentral Call Queue in the Scheduling Application
Now that the extension is configured in RingCentral, build the application so an end-user can configure the call queue in the scheduling application. To this:
- Create a RingCentral call queue object
- Retrieve the call queue members
- Map queue members to your user objects
Step 2.1: Create a RingCentral call queue object
Create an object to represent a RingCentral call queue object in your application which will be mapped to a RingCentral call queue extension and member user extensions. This should include the call queue extension's id
and the extensionNumber
. The extension id
is a API level identifier for further API calls while the extensionNumber
is used in the RingCentral Online Account Portal and will be familiar to and known by end users.
The retieve the call queue extension information to store with your app.
# Retrieve a Call Queue Extension by Extension Number
call_queue_extension_number = 201
extensions = RingCentralSdk::Cache::Extensions.new client
extensions.retrieve_all
call_queue = extensions.get_extension_by_number call_queue_extension_number
The above is implemented in RingCentralSdk::Cache::Extensions
(lib/ringcentral_sdk/cache/extensions.rb).
Step 2.2. Retrieve the call queue members
In an end-user application, after retrieving the configured call queue extension information, use the SDK to retrieve the call queue member information as follows:
# Retrieve Call Queue Members by Call Queue Id
# Call extensions.retrieve_all first as shown above
call_queue_members = extensions.get_department_members call_queue['id']
The SDK performs this using the following steps:
- Locate the call queue extension id by retrieving an extension list from the API and performing a client-side filter on
extensionNumber
. At the API, this can either be full extension list or filtered ontype=Department
for call queue extensions. - Call the
department/members
API endpoint to retrieve a list of member extension ids and extension numbers - Call the extension API endpoint to retrieve the full information for each call queue member
The above is implemented in RingCentralSdk::Cache::Extensions
(lib/ringcentral_sdk/cache/extensions.rb).
Step 2.3: Map queue members to your user objects
Now that you have the call queue member extension info, store this with your user information so you can use the call queue member extension ids to enable and disable call queue members as appropriate. The call queue member extension information also includes information such as name, extension number, etc. that can be displayed in the application for improved UX.
Step 3: Updating User Call Queue Status
After the queue has been created and users have been entered, queue member participation is determined by the user's dndStatus
property, also known as Do Not Disturb (DND) status. The dndStatus
property can be set to one of four values:
dndStatus | Accept Department Calls | Accept Non-Department Calls |
---|---|---|
TakeAllCalls |
yes | yes |
DoNotAcceptAnyCalls |
no | no |
DoNotAcceptDepartmentCalls |
no | yes |
TakeDepartmentCallsOnly |
yes | no |
A Call Queue is known as a Department via the API so the DoNotAcceptDepartmentCalls
status disables the user from recieving Call Queue calls (but allowing receipt of other calls) and the TakeDepartmentCallsOnly
will enable the user to recieve only Call Queue calls. The other settings will affect call calls, including Call Queue calls.
Updating a user extension's dndStatus
is done via the presence
API endpoint described below. Performing this action in the RingCentral Online Account Portal is described in KB Article 3770.
Step 3.1: Enable a User Extension for Call Queue Calls
To enable a user for Call Queue calls, ensure that the extension's dndStatus
is accepting department calls per the table above. This can be done by disabling department calls as follows:
# Enable Call Queue calls
extension_id = 111111 # e.g. call_queue_members[0]['id']
extension_presence = RingCentralSdk::REST::ExtensionPresence.new client, extension_id
extension_presence.department_calls_enable true
The SDK performs this using the following steps:
- Retrieve the extension's current presence
dndStatus
using theextension/presence
endpoint - Check to see if the extension's
dndStatus
includes department (call queue) calls - If the presence does not include department calls, update the
extension/presence
endpoint with the appropriate new status
The above is implemented in RingCentralSdk::REST::ExtensionPresence
(lib/ringcentral_sdk/rest/extension_presence.rb).
Step 3.2: Disable a User Extension for Call Queue Calls
To disable a user for Call Queue calls, ensure that the extension's dndStatus
is not accepting department calls per the table above. This can be done by disabling department calls as follows:
# Disable Call Queue calls
extension_id = 111111 # e.g. call_queue_members[0]['id']
extension_presence = RingCentralSdk::REST::ExtensionPresence.new client, extension_id
extension_presence.department_calls_enable false
The SDK performs this using the following steps:
- Retrieve the extension's current presence
dndStatus
using theextension/presence
endpoint - Check to see if the extension's
dndStatus
excludes department (call queue) calls - If the presence includes department calls, update the
extension/presence
endpoint with the appropriate new status
The above is implemented in RingCentralSdk::REST::ExtensionPresence
(lib/ringcentral_sdk/rest/extension_presence.rb).