openapi: 3.0.0 info: title: Webex Admin Address Book Agents API version: 1.0.0 description: The Webex Admin APIs provide comprehensive programmatic access to administrative functions for managing Webex organizations, users, licenses, and settings. These APIs enable automation of user provisioning, license assignment, compliance management, and audit event retrieval. Administrators can integrate with enterprise identity systems, enforce security policies, monitor usage, and streamline onboarding/offboarding processes. The APIs support granular control over organizational resources, making them ideal for large-scale deployments and custom admin tooling. tags: - name: Agents paths: /v1/agents/login: post: tags: - Agents summary: Login description: Allows the user to login to their desktop. It does not allow a duplicate login and sends an error message over websocket, if an active session already exists. Requires 'cjp:user' scope for authorization. For a list of possible response messages, see the [Call Control API Guide](/docs/contact-control-apis). operationId: loginRoute parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LogInResourceRequest' responses: '202': description: The login request was accepted for processing '400': description: Bad Request '401': description: Unauthorized, Token is Invalid '403': description: Forbidden Request '500': description: Internal Server Error '503': description: Service Unavailable /v1/agents/logout: put: tags: - Agents summary: Logout description: Allows the user to logout from their Desktop. This API needs to be called once the WSS session has been successfully established. Requires 'cjp:user','id_full_admin','id_readonly_admin','atlas-portal.partner.salesadmin','cjp.admin','cjp.supervisor','atlas-portal.partner.provision_admin' scope for authorization. For a list of possible response messages, see the [Call Control API Guide](/docs/contact-control-apis). operationId: logoutRoute parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LogOutResourceRequest' responses: '202': description: The logout request was accepted for processing '400': description: Bad Request '401': description: Unauthorized, Token is Invalid '403': description: Forbidden Request '500': description: Internal Server Error '503': description: Service Unavailable /v1/agents/session/state: put: tags: - Agents summary: State Change description: Allows the user to toggle between the Idle and Available states. An Administrator within the organization having an Agent license can perform a self state change when they have an active agent session. Supervisors can perform a self state change as well as state changes for agents and admin users within their authorized teams when 'Change Agent States' module is enabled. Requires 'cjp:user' scope for authorization.For a list of possible response messages, see the [Call Control API Guide](/docs/contact-control-apis). operationId: stateRoute parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StateResourceRequest' responses: '202': description: The state change request was accepted for processing '400': description: Bad Request '401': description: Unauthorized, Token is Invalid '403': description: Forbidden Request '500': description: Internal Server Error '503': description: Service Unavailable /v1/agents/reload: post: tags: - Agents summary: Reload description: Allows the user to receive all the contact assigned to particular agent and state. Requires 'cjp:user' scope for authorization. operationId: reloadRoute parameters: [] responses: '202': description: The reload request was accepted for processing '401': description: Unauthorized, Token is Invalid '403': description: Forbidden Request '500': description: Internal Server Error '503': description: Service Unavailable /v1/agents/buddyList: post: tags: - Agents summary: Buddy Agents List description: Returns the list of agents in the given state and media according to agent profile settings. Requires 'cjp:user' scope for authorization. operationId: buddyAgentsRoute parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BuddyAgentRequest' responses: '202': description: The buddy agents request was accepted for processing '400': description: Bad Request '401': description: Unauthorized, Token is Invalid '403': description: Forbidden Request '500': description: Internal Server Error '503': description: Service Unavailable /v1/agents/activities: get: tags: - Agents summary: Get Agent Activities description: "Retrieve agent activities. Sorted by start time ascending.\nMaximum number of records that can be fetched for the given from and to is 10,000. \nFor this API, response compression using gzip can be enabled by including 'Accept-Encoding' header in the request with its value as 'gzip'. \nThe response will be compressed only if its size exceeds 1 MB.\nIf the header is not present in the request or if gzip is not listed as one of the encodings in the header's value (comma separated encodings), then API response will not be compressed and this can impact the latency as observed from clients." operationId: getAgentActivities parameters: - name: agentIds in: query description: Filter agent activities by agent ids separated with commas if more than one value (max 100). By default, there is no agent filtering. required: false schema: maxItems: 100 minItems: 0 type: array items: type: string example: - 89cf3b93-f020-42c6-84dc-87db6a92eae7 - 89cf3b93-f020-42c6-84dc-87db6a92fae7 - 89cf3b93-f020-42c6-84dc-87db4a92eae7 - name: teamIds in: query description: Filter agent activities by team ids separated with commas if more than one value (max 100). By default, there is no team filtering. required: false schema: maxItems: 100 minItems: 0 type: array items: type: string example: - 89cf3b93-f020-42c6-84dc-87db6a92eae7 - 89cf3b93-f020-42c6-84dc-87db6a92fae7 - 89cf3b93-f020-42c6-84dc-87db4a92eae7 - name: channelTypes in: query description: Channel type(s) permitted in response. Separate values with commas. Must be lowercase. By default, there is no channelType filtering. required: false example: - email - chat - telephony schema: type: array items: type: string enum: - email - chat - telephony - social - name: from in: query description: Filter agent activities created after given epoch timestamp in UTC (in milliseconds). required: true schema: type: integer format: int64 example: 1591702170000 - name: to in: query description: "Filter agent activities created before given epoch timestamp in UTC (in milliseconds). If unspecified, queries up to the present.\n The difference between to and from timestamps must be less than 24 hours (86400000 milli seconds)" required: false schema: type: integer format: int64 example: 1591802180000 - name: pageSize in: query description: Maximum page size in response. Maximum allowed value is 1000. Defaults to 100 items per page. required: false schema: maximum: 1000 minimum: 1 type: integer format: int32 default: 100 example: 100 - name: page in: query description: Page number to be passed. Maximum number of records that can be fetched for the given from and to is 10,000. So maximum page number allowed is based on it. Defaults to 0. required: false schema: minimum: 0 type: integer format: int32 default: 0 example: 1 - name: orgId in: query description: Organization ID to use for this operation. If unspecified, inferred from token. Token must have permission to interact with this organization. required: false schema: type: string example: 97cdbf45-ebe2-4687-8341-44d5c7abf101 - name: TrackingId in: header description: 'Tracking ID to use for this operation, for traceability, debugging, and error reporting purposes. ' required: false schema: type: string example: INTEGRATION-9bcdc696-57fa-4e91-b5aa-57a66a347c23 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AgentActivitiesApiResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '401': description: Unauthorized Operation content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '403': description: Forbidden content: '*/*': schema: $ref: '#/components/schemas/ApiErrorResponse' '413': description: Content Too Large content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '422': description: Unprocessable Entity content: application/json: {} '500': description: An Unexpected Error Occurred content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '503': description: The service is currently unavailable to serve the requests content: application/json: {} /v1/agents/statistics: get: tags: - Agents summary: Get Agent Statistics description: "Retrieve Agent statistics information for specified time duration and interval.\nFor this API, response compression using gzip can be enabled by including 'Accept-Encoding' header in the request with its value as 'gzip'. \nThe response will be compressed only if its size exceeds 1 MB.\nIf the header is not present in the request or if gzip is not listed as one of the encodings in the header's value (comma separated encodings), then API response will not be compressed and this can impact the latency as observed from clients." operationId: getDocumentByQueryParam parameters: - name: from in: query description: Start time for the query (in epoch milliseconds). Any epoch time can be passed in the input, from date will be rounded down to nearest 15 minute window. For example, epoch time of 12:05 will be rounded down to 12:00. required: true schema: type: integer format: int64 example: 1651395600000 - name: to in: query description: "End time for the query (in epoch milliseconds). Any epoch time can be passed in the input, from date will be rounded down to nearest 15 minute window. For example, epoch time of 12:55 will be rounded down to 12:45.\n The difference between to and from time must be less than 24 hours (86400000 milliseconds)." required: true schema: type: integer format: int64 example: 1651438800000 - name: interval in: query description: Time interval (in minutes) to chunk statistics by i.e. break up the entire from-to timeframe by this interval amount so that statistics can be viewed incrementally. Supported values are 15, 30, or 60. required: false schema: type: integer format: int32 example: 15 - name: agentIds in: query description: Comma-separated list of agent IDs. A maximum of 100 values is permitted. If values are not provided, all agents of an organization are returned. required: false schema: maxItems: 100 minItems: 0 type: array items: type: string example: - 89cf3b93-f020-42c6-84dc-87db6a92eae7 - 89cf3b93-f020-42c6-84dc-87db6a92fae7 - 89cf3b93-f020-42c6-84dc-87db4a92eae7 - name: orgId in: query description: Organization ID to use for this operation. If unspecified, inferred from token. Token must have permission to interact with this organization. required: false schema: type: string example: 97cdbf45-ebe2-4687-8341-44d5c7abf101 - name: TrackingId in: header description: 'Tracking ID to use for this operation, for traceability, debugging, and error reporting purposes. ' required: false schema: type: string example: INTEGRATION-9bcdc696-57fa-4e91-b5aa-57a66a347c23 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AgentApiResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '401': description: Unauthorized Operation content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '403': description: Forbidden content: '*/*': schema: $ref: '#/components/schemas/ApiErrorResponse' '422': description: Unprocessable Entity content: application/json: {} '500': description: An Unexpected Error Occurred content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '503': description: The service is currently unavailable to serve the requests content: application/json: {} components: schemas: AgentActivitiesApiResponse: required: - data - meta type: object properties: meta: description: Response metadata. $ref: '#/components/schemas/Meta' data: type: array description: List of agent activities retrieved according to query parameters. items: $ref: '#/components/schemas/AgentActivity' description: Response wrapper for agent activities. AgentActivity: required: - active - agentDn - agentId - agentLogin - agentName - agentSessionId - channelId - channelType - currentState - endTime - idleCode - idleCodeName - isLogin - mmProfileType - queueId - queueName - reason - siteId - siteName - startTime - subChannelType - taskId - teamId - teamName - wrapupCodeName type: object properties: active: type: boolean description: Active indicates whether the activity is completed (false) or in progress (true). example: true agentId: type: string description: Unique identifier of an agent. example: AWn8XmdC-MmYjwcdYK2i agentDn: type: string description: Dialed number for the agent. example: '5555555' agentLogin: type: string description: Login username of the agent. example: agent@mailinator.com agentSessionId: type: string description: Agent Session Id example: 72a79e8b-6d2e-4423-869a-01bfebc081e6 agentName: type: string description: The name of the agent. example: John Smith currentState: type: string description: The activity state (e.g. idle, available, connected, etc.). example: idle siteId: type: string description: Unique identifier for a site. example: AWn8XmdC-MmYjwcdYK2i siteName: type: string description: The name of the site. example: Austin teamId: type: string description: Unique identifier for a team. example: AWn8XmdC-MmYjwcdYK2i teamName: type: string description: The name of the team. example: email isLogin: type: integer description: Indicates whether the activity was the login event (1) or not (0). format: int32 example: 1 taskId: type: string description: Unique identifier for a task. example: 35d88b03-6c43-45e4-9fba-99b728ad4750 channelId: type: string description: Unique identifier for the channel. example: 35d88b03-6c43-45e4-9fba-99b728ad4750 channelType: type: string description: Channel type for the activity (e.g. email, telephony, chat, etc.). example: email subChannelType: type: string description: SubChannel type for the activity. example: email idleCodeName: type: string description: In case of an idle activity, it will have an idle code attached with it (e.g. Break, Meeting, Lunch, etc.). example: Break idleCode: type: string description: Unique identifier for the idle code. example: AWn8XmdC-MmYjwcdYK2i queueId: type: string description: Unique identifier for the queue. example: AWn8XmdC-MmYjwcdYK2i queueName: type: string description: The name of the Queue. example: Support Queue wrapupCodeName: type: string description: Selected wrapup code upon finished task. example: Sale reason: type: string description: Reason example: reason startTime: type: integer description: Epoch timestamp in milliseconds of the start of the activity. format: int64 example: 1605169648658 endTime: type: integer description: Epoch timestamp in milliseconds of the end of the activity. If active, it will be -1. format: int64 example: 1605169648658 mmProfileType: type: string description: Multimedia profile type example: blended description: List of agent activities retrieved according to query parameters. ApiErrorResponse: description: Response body for an API error. type: object properties: trackingId: type: string description: "An opaque identifier for mapping protocol failures to service internal codes. \n\nWhen specified in a request, it can be used for co-relating events across services" example: c1a4fcef-aee2-4dea-8977-29f594760552 error: description: An object containing details about the error. $ref: '#/components/schemas/ErrorDetails' AgentApiResponse: required: - data - meta type: object properties: meta: description: Response metadata. $ref: '#/components/schemas/Meta' data: type: array description: List of Agent Statistics records retrieved according to query parameters. items: $ref: '#/components/schemas/OutAgentStatistics' description: Response wrapper for agent statistics. BuddyAgentRequest: properties: agentProfileId: description: The profile ID of a particular agent. Can be obtained from [Users API](/docs/users), maximum length 36 characters. type: string example: 315fbb91-2288-427c-9588-ec764cd46ea4 mediaType: description: The media type for the request. The supported values are ```telephony```, ```chat```, ```social```, ```email``` and ```workItem```. type: string example: telephony state: description: It represents the current state of the returned agents which can be either ```Available``` or ```Idle```. If state is omitted from the payload, the API will return a list of both available and idle agents. This is useful for consult scenarios, since consulting an idle agent is also supported. type: string example: Available required: - agentProfileId - mediaType type: object description: Request payload to retrieve buddy agents. ErrorDetails: description: Details of an error. type: object properties: key: type: string description: An application defined error code. example: '401' message: type: array description: A message providing details about the error. items: $ref: '#/components/schemas/OperationError' ChannelResponse: type: object properties: channelType: type: string description: Channel Type example: chat totalAssignedTasks: type: integer description: Number of tasks assigned within the channel during the agent session. format: int32 example: 3 totalOfferedTasks: type: integer description: Number of offered tasks within this channel during the agent's session. format: int32 example: 3 totalAcceptedTasks: type: integer description: Number of assigned tasks that were accepted by the agent. format: int32 example: 3 totalRejectedTasks: type: integer description: Number of assigned tasks that were rejected by the agent. format: int32 example: 3 totalTransferredTasks: type: integer description: Number of tasks that the agent transferred to another agent. format: int32 example: 2 totalEngagedDuration: type: integer description: 'The amount of time the agent was engaged with a customer (in milliseconds). Note :- - Does not include wrap-up time and consult duration - Includes conferencing duration since the customer is involved' format: int32 example: 40302 totalHoldDuration: type: integer description: The amount of time for which the customer(s) was put on hold (in milliseconds). format: int64 example: 10198 totalWrapUpDuration: type: integer description: 'The amount of time spent by the agent wrapping up customer interactions (in milliseconds). i.e Sum of all wrap-up time metric for a given agent' format: int64 example: 3552 totalAvailableTime: type: integer description: Duration of time(in milliseconds) outside of the idle time when an agent was available and handling contacts after logging in. format: int64 example: 234947 totalUnAvailableTime: type: integer description: Amount of time the agent was unavailable (in milliseconds). format: int64 example: 22300 averageHandledTime: type: number description: 'This is the average of the total handle time by an agent (in milliseconds) i.e avg(engagedDuration(connected state) + hold-duration + wrap-up time)' format: double example: 22300 description: Statistics for a specific channel. LogOutResourceRequest: properties: logoutReason: description: The reason for performing logout operation, maximum length 128 characters. type: string example: Logout initiated by user abcd@xyz.com agentId: description: Unique ID of the user who is being logged out, maximum length 36 characters. type: string example: faedfcc8-035a-41e3-ad53-ee9fad4ca286 required: - logoutReason type: object StateResourceRequest: properties: state: description: It represents the current state of the user. Can be set to ```Available``` or ```Idle```. type: string example: Available auxCodeId: description: 'Auxiliary Codes are status codes which an agent can select in Webex Contact Center Agent Desktop. They are of two types: ```Idle``` and ```Wrap-Up``` codes, and every agent profile must have one of each for the agent to use. Idle codes are used to explain an agent''s unavailability to take customer contacts, such as during a lunch break or a meeting. Wrap-up codes indicate the result of customer contacts, such as successful resolution or escalation of the contact. Creating and managing auxiliary codes requires an administrator role and the appropriate cjp:config_write or cjp:config_read scopes, maximum length 36 characters.' type: string example: AXUH3oN12eV-WekpnDpl lastStateChangeReason: description: It represents the reason of the last state change request, maximum length 128 characters. type: string example: Lunch agentId: description: User for which state change is initiated, maximum length 36 characters. type: string example: 1a80ba23-194b-49af-9b93-074b3ecc852a required: - state - auxCodeId type: object description: Request payload to update an agent state. OperationError: description: An error message providing details about the operation failure. type: object properties: description: type: string description: A human readable explanation for the occurrence of an error. example: Incorrect Credentials. Meta: type: object properties: orgId: type: string description: Organization ID to which resources belong. example: 3dae8fdd-06e2-411a-9035-51f3719f5b65 description: Response metadata. LogInResourceRequest: properties: dialNumber: description: A dialNumber field contains the number to dial such as a route point or extension, maximum length 43 characters. type: string example: '5678956899' teamId: description: The unique ID representing a team of users. Leaving this field blank is valid for supervisor role but invalid for agent role, maximum length 36 characters. type: string example: 5c8e24ff-a31a-422d-b7a7-b56c6739081d isExtension: description: It indicates if the dialNumber field is full number or extension. It is set to false by default. type: boolean example: 'false' roles: description: It represents the current role of the user. The user can either be an ```agent``` or a ```supervisor```. type: array items: type: string example: - agent - supervisor deviceType: description: It represents the way to differentiate type of login request (```AGENT_DN```, ```EXTENSION```, ```BROWSER```). Leaving this field is valid for supervisor role but invalid for agent role. type: string example: AGENT_DN deviceId: description: It is equal to dialNumber for AGENT_DN & EXTENSION deviceType and for BROWSER it is populated as webrtc-AgentUUID, maximum length 43 characters. type: string example: '5678956899' required: - dialNumber - roles type: object OutAgentStatistics: required: - channels type: object properties: intervalStartTime: type: integer description: Time in GMT format: int64 example: 1591702200000 agentId: type: string description: The ID of the agent. example: 06ce7234-dd3e-49e2-8763-d93766739d agentName: type: string description: The name of the agent example: Daniel Garrett teamId: type: string description: The ID of the team. example: fbf80248-b328-4c37-9ea5-4c2ec8b4d52c teamName: type: string description: Name of the team to which agent belongs. example: Collaboration channels: type: array description: Channel-level statistics for the agent. items: $ref: '#/components/schemas/ChannelResponse' description: List of Agent Statistics records retrieved according to query parameters. securitySchemes: oauth2: flows: authorizationCode: authorizationUrl: / scopes: {} tokenUrl: / type: oauth2 bearer-key: type: http description: e.g. Bearer YOUR_AUTHORIZATION_TOKEN scheme: bearer bearerFormat: JWT bearerAuth: type: oauth2 description: OAuth 2.0 Bearer token authentication flows: authorizationCode: authorizationUrl: https://webexapis.com/v1/authorize tokenUrl: https://webexapis.com/v1/access_token scopes: spark:applications_token: Create access tokens for Service Apps