> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/automation/runbooks/runbook-references/org/phone/add-or-remove-call-queue-agents.md).

# Add Or Remove Call Queue Agents

Add or remove agents of a Teams call queue

### Description

Adds the selected users as individually assigned agents of a Teams call queue or takes them off that list. Agents that come from a group, a team or a shifts schedule are not touched; the output says where they are managed instead. Users without Enterprise Voice are skipped with the reason. Details on the checks and limits are in the runbook documentation (docs.realmjoin.com).

### How it works

A call queue gets its agents in exactly one of three ways, and the way is chosen in the Teams admin center under "Call answering":

* **Users and groups** - agents are assigned individually, through groups, or both. This is the only mode the runbook changes. It adds the selected users to the list of individually assigned agents or takes them off it, and leaves the assigned groups exactly as they are.
* **A team and channel** - every member of that channel's team is an agent. The runbook prints the team and channel and stops without a change, because membership is managed in the team.
* **A shifts schedule** - agents come from a scheduling group in the Shifts app. The runbook prints the team behind the schedule and stops without a change.

Before anything is written, the runbook lists the current agents and checks every selected user. Users that cannot become an agent are skipped with the reason, and the remaining ones are still processed. Adding a user who is already an agent, or removing a user who is not one, is reported as "No action taken" and changes nothing.

Two situations stop the run before any change is made: the queue would end up with more than 20 individually assigned agents, or a removal would leave the queue with no agents and no groups at all. In the second case, keep one agent or assign a group or team to the queue in the Teams admin center first.

After the change the runbook reads the call queue back and compares the agent list with what was requested. A mismatch is reported as a warning so it can be checked in the Teams admin center.

### Requirements for agents

* An agent needs a Teams Phone license with Enterprise Voice enabled. Users without it are skipped with that reason; set up Teams Phone for them and run the runbook again.
* Agents who take calls in the Teams app must be in TeamsOnly upgrade mode. Another mode is reported as a warning, and the user is still added.
* Only regular user accounts can be agents. Resource accounts and guests are skipped.
* Microsoft allows 20 individually assigned agents per call queue, and up to 200 agents when they come through groups. Use a group for larger teams.
* License and policy changes need time to reach the Teams service. After a new Teams Phone license it can take about an hour before a user can be assigned as an agent.
* A user who becomes an agent through a group can take up to eight hours before the queue offers the first call.

### Notes and limitations

* The runbook never changes the membership of a group or a team. A queue that gets its agents from a group, a team channel or a shifts schedule is reported with the place where its members are managed.
* Queues that mix individually assigned users with groups are supported. Only the individual assignments are changed; the groups stay untouched and their members are still agents.
* The agent list of a call queue is the service's own expansion of users and group members, and it is cached. A user who was just added to one of the assigned groups can still be reported as not being an agent, and a user removed from a group can still be listed for a while.
* Clearing the agent list completely is not possible here on purpose. Removing the last agent of a queue without groups is refused, because a queue without agents cannot take calls. Do that in the Teams admin center if it is really intended.
* Group, team and channel names come from Microsoft Graph. Without the optional permissions for it, the runbook prints the object IDs instead and works exactly the same.

### Location

Organization → Phone → Add Or Remove Call Queue Agents

**Full Runbook name**

rjgit-org\_phone\_add-or-remove-call-queue-agents

### Details

| Property         | Value                                                                                                                 |
| ---------------- | --------------------------------------------------------------------------------------------------------------------- |
| Version          | 1.0.0                                                                                                                 |
| Required modules | <p>RealmJoin.RunbookHelper (>= 0.8.10)<br>MicrosoftTeams (>= 7.9.0)<br>Microsoft.Graph.Authentication (>= 2.41.2)</p> |
| Schedulable      | no                                                                                                                    |

### Permissions

#### Application permissions

* **Type**: Microsoft Graph
  * Organization.Read.All
    * *Required by the app-based Teams PowerShell sign-in (Connect-MicrosoftTeams -Identity) to read tenant info*
  * Channel.ReadBasic.All *(optional — feature: Group, team and channel names in the output)*
    * *Resolves the channel name of a call queue that is answered by a team channel*
  * GroupMember.Read.All *(optional — feature: Group, team and channel names in the output)*
    * *Resolves the display names of the groups and shifts teams assigned to the call queue*
  * Team.ReadBasic.All *(optional — feature: Group, team and channel names in the output)*
    * *Lists the teams of the channel owner to find the team behind the answering channel*

#### RBAC roles

* Teams Administrator
  * *Required to run Get-CsCallQueue, Set-CsCallQueue and Get-CsOnlineUser via app-based Teams PowerShell*

### Parameters

#### CallQueueName

Exact name of the call queue as shown in the Teams admin center. Upper and lower case do not matter, but the name has to match exactly one queue.

| Property            | Value           |
| ------------------- | --------------- |
| Required            | true            |
| Default Value       |                 |
| Type                | String          |
| Portal display name | Call queue name |

#### UserIds

Users to add or remove, several at a time. To work as an agent, a user needs a Teams Phone license with Enterprise Voice enabled.

| Property            | Value     |
| ------------------- | --------- |
| Required            | true      |
| Default Value       |           |
| Type                | String\[] |
| Portal display name | Users     |

#### Remove

Add users as agents puts them on the list of individually assigned agents. Remove users as agents takes them off it; agents that come from a group or team stay as they are.

| Property            | Value   |
| ------------------- | ------- |
| Required            | false   |
| Default Value       | False   |
| Type                | Boolean |
| Portal display name | Action  |

**Portal options**

| Portal option          | Value |
| ---------------------- | ----- |
| Add users as agents    | false |
| Remove users as agents | true  |

[Back to Runbook Reference overview](/automation/runbooks/runbook-references.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.realmjoin.com/automation/runbooks/runbook-references/org/phone/add-or-remove-call-queue-agents.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.