Agent Groups

Last updated: 2026-07-28

Contributors

Agent groups organize agents into administrative groups. An agent must belong to an agent group before you can create or manage that agent through the Agents API.

Manage Agent Groups

Operation	Method and path
List agent groups	`GET https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/agentGroups`
Get agent group	`GET https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/agentGroups/{agentGroupId}`
Create agent group	`POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/agentGroups`
Update agent group	`PUT https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/agentGroups/{agentGroupId}`
Delete agent group	`DELETE https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/agentGroups/{agentGroupId}`

SDK Setup

SDK examples in this article use JWT authentication and load credentials from environment variables.

JavaScript

npm install ringcentral-engage-voice-client dotenv

Python

pip3 install ringcentral_engage_voice python-dotenv

Create a .env file in the directory where you run the sample:

RC_CLIENT_ID=<clientId>
RC_CLIENT_SECRET=<clientSecret>
RC_JWT=<jwt>

The SDK wrapper reads these values, signs in with RingCentral, and exchanges the RingCentral access token for a RingCX access token before calling RingCX APIs.

Create an Agent Group

Only groupName is required when creating an agent group.

HTTP

POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/agentGroups
Authorization: Bearer <ringcxAccessToken>
Content-Type: application/json

{
  "groupName": "Support Agents"
}

Python

import requests

account_id = "<accountId>"
access_token = "<ringcxAccessToken>"

response = requests.post(
    f"https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{account_id}/agentGroups",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
    },
    json={"groupName": "Support Agents"},
)
response.raise_for_status()
print(response.json())

JavaScript

const accountId = "<accountId>";
const accessToken = "<ringcxAccessToken>";

const response = await fetch(
  `https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/${accountId}/agentGroups`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ groupName: "Support Agents" })
  }
);

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

JavaScript SDK

const EngageVoice = require("ringcentral-engage-voice-client").default;
require("dotenv").config();

async function main() {
  const ev = new EngageVoice({
    clientId: process.env.RC_CLIENT_ID,
    clientSecret: process.env.RC_CLIENT_SECRET
  });

  await ev.authorize({ jwt: process.env.RC_JWT });

  const response = await ev.post(
    "/api/v1/admin/accounts/{accountId}/agentGroups",
    { groupName: "Support Agents" }
  );
  console.log(response.data);
}

main().catch(console.error);

Python SDK

import os
from dotenv import load_dotenv
from ringcentral_engage_voice import RingCentralEngageVoice

load_dotenv()

ev = RingCentralEngageVoice(
    os.environ["RC_CLIENT_ID"],
    os.environ["RC_CLIENT_SECRET"],
)
ev.authorize(jwt=os.environ["RC_JWT"])

response = ev.post(
    "/api/v1/admin/accounts/{accountId}/agentGroups",
    {"groupName": "Support Agents"},
).json()
print(response)

Response example

{
  "agentGroupId": 1950,
  "groupName": "Support Agents",
  "isDefault": false
}

Common Fields

Field	Required	Description
`groupName`	Yes	Display name for the agent group.
`agentGroupId`	No	Agent group ID. If omitted during create, RingCX assigns an ID.
`isDefault`	No	Whether the group is the default agent group.

Retrieve Agent Groups

HTTP

GET https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/agentGroups
Authorization: Bearer <ringcxAccessToken>
Accept: application/json

Python

import requests

account_id = "<accountId>"
access_token = "<ringcxAccessToken>"

response = requests.get(
    f"https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{account_id}/agentGroups",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Accept": "application/json",
    },
)
response.raise_for_status()
print(response.json())

JavaScript

const accountId = "<accountId>";
const accessToken = "<ringcxAccessToken>";

const response = await fetch(
  `https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/${accountId}/agentGroups`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      Accept: "application/json"
    }
  }
);

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

JavaScript SDK

const EngageVoice = require("ringcentral-engage-voice-client").default;
require("dotenv").config();

async function main() {
  const ev = new EngageVoice({
    clientId: process.env.RC_CLIENT_ID,
    clientSecret: process.env.RC_CLIENT_SECRET
  });

  await ev.authorize({ jwt: process.env.RC_JWT });

  const response = await ev.get("/api/v1/admin/accounts/{accountId}/agentGroups");
  console.log(response.data);
}

main().catch(console.error);

Python SDK

import os
from dotenv import load_dotenv
from ringcentral_engage_voice import RingCentralEngageVoice

load_dotenv()

ev = RingCentralEngageVoice(
    os.environ["RC_CLIENT_ID"],
    os.environ["RC_CLIENT_SECRET"],
)
ev.authorize(jwt=os.environ["RC_JWT"])

response = ev.get("/api/v1/admin/accounts/{accountId}/agentGroups").json()
print(response)

Use the returned agentGroupId when creating agents.

Response example

[
  {
    "agentGroupId": 1950,
    "groupName": "Support Agents",
    "isDefault": false
  },
  {
    "agentGroupId": 1951,
    "groupName": "Supervisors",
    "isDefault": false
  }
]

Update an Agent Group

Retrieve the agent group first, update the fields you need to change, and submit the updated object with PUT.

HTTP

PUT https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/agentGroups/{agentGroupId}
Authorization: Bearer <ringcxAccessToken>
Content-Type: application/json

{
  "agentGroupId": 1950,
  "groupName": "Support Agents - Updated",
  "isDefault": false
}

Python

import requests

account_id = "<accountId>"
agent_group_id = "<agentGroupId>"
access_token = "<ringcxAccessToken>"
payload = {
    "agentGroupId": 1950,
    "groupName": "Support Agents - Updated",
    "isDefault": False,
}

response = requests.put(
    f"https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{account_id}/agentGroups/{agent_group_id}",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
    },
    json=payload,
)
response.raise_for_status()
print(response.json())

JavaScript

const accountId = "<accountId>";
const agentGroupId = "<agentGroupId>";
const accessToken = "<ringcxAccessToken>";
const payload = {
  agentGroupId: 1950,
  groupName: "Support Agents - Updated",
  isDefault: false
};

const response = await fetch(
  `https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/${accountId}/agentGroups/${agentGroupId}`,
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  }
);

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

JavaScript SDK

const EngageVoice = require("ringcentral-engage-voice-client").default;
require("dotenv").config();

async function main() {
  const ev = new EngageVoice({
    clientId: process.env.RC_CLIENT_ID,
    clientSecret: process.env.RC_CLIENT_SECRET
  });

  await ev.authorize({ jwt: process.env.RC_JWT });

  const payload = {
    agentGroupId: 1950,
    groupName: "Support Agents - Updated",
    isDefault: false
  };

  const response = await ev.put(
    "/api/v1/admin/accounts/{accountId}/agentGroups/{agentGroupId}",
    payload
  );
  console.log(response.data);
}

main().catch(console.error);

Python SDK

import os
from dotenv import load_dotenv
from ringcentral_engage_voice import RingCentralEngageVoice

load_dotenv()

ev = RingCentralEngageVoice(
    os.environ["RC_CLIENT_ID"],
    os.environ["RC_CLIENT_SECRET"],
)
ev.authorize(jwt=os.environ["RC_JWT"])

payload = {
    "agentGroupId": 1950,
    "groupName": "Support Agents - Updated",
    "isDefault": False,
}

response = ev.put(
    "/api/v1/admin/accounts/{accountId}/agentGroups/{agentGroupId}",
    payload,
).json()
print(response)

Response example

{
  "agentGroupId": 1950,
  "groupName": "Support Agents - Updated",
  "isDefault": false
}

Delete an Agent Group

HTTP

DELETE https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/agentGroups/{agentGroupId}
Authorization: Bearer <ringcxAccessToken>

Python

import requests

account_id = "<accountId>"
agent_group_id = "<agentGroupId>"
access_token = "<ringcxAccessToken>"

response = requests.delete(
    f"https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{account_id}/agentGroups/{agent_group_id}",
    headers={"Authorization": f"Bearer {access_token}"},
)
response.raise_for_status()

JavaScript

const accountId = "<accountId>";
const agentGroupId = "<agentGroupId>";
const accessToken = "<ringcxAccessToken>";

const response = await fetch(
  `https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/${accountId}/agentGroups/${agentGroupId}`,
  {
    method: "DELETE",
    headers: { Authorization: `Bearer ${accessToken}` }
  }
);

if (!response.ok) throw new Error(await response.text());

JavaScript SDK

const EngageVoice = require("ringcentral-engage-voice-client").default;
require("dotenv").config();

async function main() {
  const ev = new EngageVoice({
    clientId: process.env.RC_CLIENT_ID,
    clientSecret: process.env.RC_CLIENT_SECRET
  });

  await ev.authorize({ jwt: process.env.RC_JWT });

  await ev.delete(
    "/api/v1/admin/accounts/{accountId}/agentGroups/{agentGroupId}"
  );
}

main().catch(console.error);

Python SDK

import os
from dotenv import load_dotenv
from ringcentral_engage_voice import RingCentralEngageVoice

load_dotenv()

ev = RingCentralEngageVoice(
    os.environ["RC_CLIENT_ID"],
    os.environ["RC_CLIENT_SECRET"],
)
ev.authorize(jwt=os.environ["RC_JWT"])

ev.delete(
    "/api/v1/admin/accounts/{accountId}/agentGroups/{agentGroupId}"
)

Delete an agent group only after moving or deleting the agents that belong to it.