diff --git a/docs/analytics/reports/realtime-supervisor-view.md b/docs/analytics/reports/realtime-supervisor-view.md index e519e38..309645c 100644 --- a/docs/analytics/reports/realtime-supervisor-view.md +++ b/docs/analytics/reports/realtime-supervisor-view.md @@ -65,6 +65,8 @@ Returns a live snapshot of every agent currently logged in to the account — th Returns an array of `AgentStats` objects — one per logged-in agent session. Key fields include the agent's current `agentState` (e.g., `AVAILABLE`, `ON_CALL`, `AWAY`, `WRAP_UP`), `stateTime` in seconds, live call identifiers (`callUii`, `callAni`, `callDnis`), and session counters (`callsHandled`, `totalTalkTime`) that reset on logout. +Use `agentId`, `agentGroupId`, and `loginTime` when building supervisor automations that monitor agent session duration. After confirming an agent is not handling an active interaction, use the [Log Out Agent](../../users/agents/agents.md#log-out-an-agent) endpoint to end the session. + ??? info "View Full AgentStats Schema" **Identity & Assignment** diff --git a/docs/users/agents/agents.md b/docs/users/agents/agents.md index cff4fc3..65e84d5 100644 --- a/docs/users/agents/agents.md +++ b/docs/users/agents/agents.md @@ -11,6 +11,7 @@ Agents are RingCX users who can log in to handle inbound queues, outbound campai | Create agent | `POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/agentGroups/{agentGroupId}/agents` | | Update agents in an agent group | `PUT https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/agentGroups/{agentGroupId}/agents` | | Update one agent | `PUT https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/agentGroups/{agentGroupId}/agents/{agentId}` | +| Log out an agent | `POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/agentGroups/{agentGroupId}/agents/{agentId}/logout` | | Delete agent | `DELETE https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/agentGroups/{agentGroupId}/agents/{agentId}` | ## SDK Setup @@ -705,6 +706,108 @@ Use these endpoints to find IDs referenced by agent configuration. | Queue groups and queues | `GET https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/gateGroups/withChildren` | | Agent access to a queue | `GET https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/agentGroups/{agentGroupId}/gateGroups/{gateGroupId}/gates/{gateId}` | +## Log Out an Agent + +Use this endpoint to log out a currently logged-in agent. Supervisor and workforce automations can use it after identifying stale or overlong sessions. + +Before logging out an agent, confirm that the agent is not handling an active interaction. The [Real-Time Supervisor View API](../../analytics/reports/realtime-supervisor-view.md#agent-states) returns each logged-in agent's current state, `loginTime`, `agentGroupId`, and `agentId`. + +=== "HTTP" + + ```http + POST https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{accountId}/agentGroups/{agentGroupId}/agents/{agentId}/logout + Authorization: Bearer + ``` + +=== "Python" + + ```python + import requests + + account_id = "" + agent_group_id = "" + agent_id = "" + access_token = "" + + response = requests.post( + f"https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{account_id}/agentGroups/{agent_group_id}/agents/{agent_id}/logout", + headers={"Authorization": f"Bearer {access_token}"}, + ) + response.raise_for_status() + print(response.json()) + ``` + +=== "JavaScript" + + ```javascript + const accountId = ""; + const agentGroupId = ""; + const agentId = ""; + const accessToken = ""; + + const response = await fetch( + `https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/${accountId}/agentGroups/${agentGroupId}/agents/${agentId}/logout`, + { + method: "POST", + headers: { Authorization: `Bearer ${accessToken}` } + } + ); + + if (!response.ok) throw new Error(await response.text()); + console.log(await response.json()); + ``` + +=== "JavaScript SDK" + + ```javascript + 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 result = await ev.post( + "/api/v1/admin/accounts/{accountId}/agentGroups/{agentGroupId}/agents/{agentId}/logout" + ); + + console.log(result.data); + } + + main().catch(console.error); + ``` + +=== "Python SDK" + + ```python + 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/{agentGroupId}/agents/{agentId}/logout" + ) + print(response.json()) + ``` + +??? example "Response example" + + ```json + true + ``` + ## Delete an Agent === "HTTP" diff --git a/specs/engage-voice_openapi3.json b/specs/engage-voice_openapi3.json index 374258c..e5fb746 100644 --- a/specs/engage-voice_openapi3.json +++ b/specs/engage-voice_openapi3.json @@ -11866,6 +11866,73 @@ "x-codegen-request-body-name": "updateRequest" } }, + "/voice/api/v1/admin/accounts/{accountId}/agentGroups/{agentGroupId}/agents/{agentId}/logout": { + "post": { + "description": "Logs out a single agent from the specified agent group. Permissions: UPDATE on Agent (Permission Override)", + "operationId": "logoutAgent", + "parameters": [ + { + "description": "RingCX sub-account ID", + "in": "path", + "name": "accountId", + "required": true, + "schema": { + "type": "string" + } + }, + { + "description": "Agent group ID", + "in": "path", + "name": "agentGroupId", + "required": true, + "schema": { + "format": "int32", + "type": "integer" + } + }, + { + "description": "Agent ID", + "in": "path", + "name": "agentId", + "required": true, + "schema": { + "format": "int32", + "type": "integer" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "boolean" + } + } + }, + "description": "OK" + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "security": [ + { + "BearerAuth": [] + } + ], + "summary": "Logs out an agent", + "tags": [ + "Agents" + ] + } + }, "/voice/api/v1/admin/accounts/{accountId}/agentGroups/{agentGroupId}/gateGroups/{gateGroupId}/gates/{gateId}": { "get": { "description": "Permissions: READ on Account, READ on requested Gate",