openapi: 3.2.0
info:
title: Webex Agents API
version: 1.0.0
description: 'Operations tagged Agents across 2 of this provider''s published API definitions: webex-agents-api-openapi.yml,
webex-contact-center-openapi.json. Each path carries the servers of the definition it was published in.'
x-provenance:
method: harvested
authored_by: Cisco Webex
harvested_by: API Evangelist
harvested_on: '2026-08-19'
first_party: true
note: Published by Cisco. Retrieved unmodified except for this x-provenance block.
provider_published: true
derived_view: Per-tag view of webex-contact-center-openapi.json, the provider's source document. Operations and schemas
are the provider's, unmodified; only the partition is ours.
derived_from: webex-contact-center-openapi.json
operation_coverage: 11/11
x-evidence:
- type: source
url: https://github.com/webex/webex-openapi-specs/blob/main/public-spec/webex-contact-center.json
- type: raw
url: https://raw.githubusercontent.com/webex/webex-openapi-specs/main/public-spec/webex-contact-center.json
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: {}
/v2/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](/documentation/guides/contact-control-apis).
operationId: LoginRoute
parameters:
- name: Authorization
in: header
description: The bearer token would be sent to validate the active users.
required: true
schema:
type: string
example: Bearer <AuthToken>
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
/v2/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](/documentation/guides/contact-control-apis).
operationId: LogoutRoute
parameters:
- name: Authorization
in: header
description: The bearer token would be sent to validate the active users.
required: true
schema:
type: string
example: Bearer <AuthToken>
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
/v2/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](/documentation/guides/contact-control-apis).
operationId: StateRoute
parameters:
- name: Authorization
in: header
description: The bearer token would be sent to validate the active users.
required: true
schema:
type: string
example: Bearer <AuthToken>
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgentChannelStateChangeResourceRequest'
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
/v2/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:
- name: Authorization
in: header
description: The bearer token would be sent to validate the active users.
required: true
schema:
type: string
example: Bearer <AuthToken>
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
components:
schemas:
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.
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.
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
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.
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.
Meta:
type: object
properties:
orgId:
type: string
description: Organization ID to which resources belong.
example: 3dae8fdd-06e2-411a-9035-51f3719f5b65
description: Response metadata.
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.
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'
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
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'
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.
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
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/webex/refs/heads/main/openapi/webex-agents-api-openapi.yml