Call Handling: Call Queues

Call queues are a poplar way to have multiple people respond to incoming calls.

Create a Call Queue

Creating a call queue is performed in the Online Account Portal under groups.

Read Call Queue List

The List Extensions endpoint can be used to retrieve a list of call queues, known as departments via the API.

Method Endpoint Description
GET v1.0/account/{accountId}/extension?type=Department Read a list of call queues, aka departments

Sample Response

{
  "uri" : "https://platform.devtest.ringcentral.com/restapi/v1.0/account/11111111/extension?type=Department&page=1&perPage=100",
  "records" : [
    {
      "uri" : "https://platform.devtest.ringcentral.com/restapi/v1.0/account/11111111/extension/22223333",
      "id" : 22223333,
      "extensionNumber" : "201",
      "contact" : {
        "firstName" : "Sales Queue",
        "email" : "john.doe@example.com"
      },
      "name" : "Sales Queue",
      "type" : "Department",
      "status" : "Enabled",
      "permissions" : {
        "admin" : {
          "enabled" : false
        },
        "internationalCalling" : {
          "enabled" : false
        }
      },
      "profileImage" : {
        "uri" : "https://platform.devtest.ringcentral.com/restapi/v1.0/account/11111111/extension/22223333/profile-image"
      }
    }
  ],
  "paging" : {...}
}

Read Queue Agent List

To get the agent members of a queue, call the department members endpoint.

Method Endpoint Description
GET v1.0/account/{accountId}/department/{departmentId}/members Read department members

Sample Response

{
  "uri" : "https://platform.devtest.ringcentral.com/restapi/v1.0/account/11111111/department/22223333/members?page=1&perPage=100",
  "records" : [
    {
      "uri" : "https://platform.devtest.ringcentral.com/restapi/v1.0/account/11111111/extension/11112222",
      "id" : 11112222,
      "extensionNumber" : "101"
    },
    {
      "uri" : "https://platform.devtest.ringcentral.com/restapi/v1.0/account/11111111/extension/11113333",
      "id" : 11113333,
      "extensionNumber" : "102"
    }
  ],
  "paging" : {...}
  "navigatin" : {...}
}

Update Queue Agent List

Users can be added and removed as queue agents using the account/{accountId}/department/bulk-assign endpoint and the extension ids of interest.

Method Endpoint Description
POST v1.0/account/{accountId}/department/bulk-assign Add and remove multiple users from one or more departments
{
  "items" : [
    {
      "departmentId" : "22223333",   
      "addedExtensionIds" : [
        "11112222", "11113333"
      ],
      "removedExtensionIds" : [
        "11114444", "11115555"
      ]
    },
    {
      "departmentId" : "22224444",   
      "addedExtensionIds" : [
        "11112222", "11113333"
      ]
    }
  ]
}

Sample Response

HTTP/1.1 204 No Content
Content-Type: application/json
Content-Language: en-US

Read User Queue Agent Presence

A user extension's actual presence status is determined by aggregating a number of different presence statuses including dndStatus, telephonyStatus and userStatus. These and the aggregate presence, presenceStatus are available in the presence endpoint.

A user extension's queue agent status is set by the extension presence dndStatus property. This can be set to one of four values:

  1. TakeAllCalls
  2. DoNotAcceptAnyCalls
  3. DoNotAcceptDepartmentCalls
  4. TakeDepartmentCallsOnly
Method Endpoint Description
GET v1.0/account/{accountId}/extension/{extensionId}/presence Read extension presence

Sample Response

{
  "uri" : "https.../restapi/v1.0/account/11111111/extension/11112222/presence",
  "extension" : {
    "uri" : "https.../restapi/v1.0/account/11111111/extension/11112222",
    "id" : 11112222,
    "extensionNumber" : "101"
  },
  "presenceStatus" : "Available",
  "telephonyStatus" : "NoCall",
  "userStatus" : "Available",
  "dndStatus" : "TakeAllCalls",
  "message" : "Hello, World",
  "allowSeeMyPresence" : true,
  "ringOnMonitoredCall" : false,
  "pickUpCallsOnHold" : false
}

Update User Queue Agent Presence

To enable or disable an user extension's queue agent presence, update the extension's presence dndStatus property.

Method Endpoint Description
PUT v1.0/account/{accountId}/extension/{extensionId}/presence Update extension presence
{
  "dndStatus": "DoNotAcceptDepartmentCalls"
}

Subscribe for Presence Notification Events

You can receive events about presence changes to an extension by subscribing to extension specific presence information using an event filter. To learn more, consult our documentation relating to our Presence API.