4.X Clarity Connect Web API Version 2

Connect Web API Root URL

The Connect Web API root URL is always located off of the Load Balanced Web Services FQDN at:

loadBalancedWebServicesFQDN/webapi/api

To discover which API and Clarity Connect versions are running, refer to the Info endpoint.

Authentication

The v2 Connect API supports Integrated Windows authentication. After an API consumer is authenticated by the Identity Provider as a valid Clarity Connect agent, the Identity Provider returns a JSON Web Token (JWT) access token that contains a claim asserting the API consumer’s Agent ID.

JSON Web Tokens (JWT)

JSON Web Token (JWT) is an open standard that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed.

Format

JWTs follows the format specified in the RFC, which is a Base64Url encoded string composed of three “.” delimited sections:

Header.Payload.Signature

The header defines the type of the token, the payload has the claims, i.e. the security authorizations on behalf of the user, and the signature is a cryptographic fail safe to ensure that the payload has not been altered in transmission and that the token is from the claimed issuer.

For example (in base 64):

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmludGVybmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQjFBMC1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzI4NDIyNzgsIm5iZiI6MTQ3Mjg0MTk3OH0.YiLosagjS-002SWXX7ZzeEhvW6zDpJFb3qx-qrtTxIM

Decoded:

Header

            {
  "typ": "JWT",
  "alg": "HS256"
}

        

Payload

            {
  "connect_agent_id": "5",
  "iss": "https://40.ccdev2015.internal/webauth/token",
  "aud": "0444C392-3845-4AC0-B1A0-D63706180BA9",
  "exp": 1472842278,
  "nbf": 1472841978
}

        

Claims

The payload of the JWT contains the “connect_agent_id” claim which tells the Connect API which Connect Agent is making this API request. The Connect API can then authorize this request against the MBU permission structure.

Integrated Windows Authentication

Integrated Windows Authentication gets a token from the Connect Authentication Service for the logged in domain user via Integrated Windows Authentication in the browser.

Finding the Authentication Service

To get a token, the API consumer must POST to the Connect Authentication Service’s /token endpoint. To find this endpoint, the API consumer should first do a GET or POST against the Connect API without including any token in the Authorization header.

The 401 Unauthorized response from the Connect API includes the address of the Connect Authentication Service in the WWW-Authenticate header.

For example, the WWW-Authenticate response header could look like:

https://41.ccdev2015.internal/webauth/token,grant_type="urn:connect.auth:windows"

The first part of the header is the address of the Connect Authentication Service.

Creating a Token Request

With this address, an API consumer can compose a POST to kick off authentication. The POST body must contain the following fields to identify the API client and what type of authentication the API consumer wants to do:

Field Name	Description	Sample Value
grant_type	What style of authentication to use	urn:connect.auth:windows This is the only valid value
client_id	Unique GUID assigned to this API consuming application. GUIDs can be found and created in the admin site under API Management	0224C392-3845-4AC0-B1A0-D63706181BA7

The POST must also contain headers to indicate that the API consumer expects to get JSON content back and that the POST body is w-xxx-form-urlencoded.

Header Name	Description	Sample Value
Accept	What format of response the API consumer expects back	application/json This is the only valid value
Content-Type	What format the POST body is in. Important for character escaping.	application/x-www-form-urlencoded This is the only valid value

A sample request therefore would look like:

POST /webauth/token HTTP/1.1
Host: 41.ccdev2015.internal
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

grant_type=urn%3Aconnect.auth%3Awindows&client_id=0224C392-3845-4AC0-B1A0-D63706181BA7

Token Responses

SUCCESS

On successful Integrated Windows Authentication, a JWT is returned in the body of the response:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiMTUiLCJpc3MiOiJodHRwczovLzQxLmNjZGV2MjAxNS5pbnRlcm5hbC93ZWJhdXRoL3Rva2VuIiwiYXVkIjoiQTA4NTcwQjQtNEFBMS00NjBELUExNTAtOTA0NDU5OTU1QkU0IiwiZXhwIjoxNDcyODgyMTc4LCJuYmYiOjE0NzI4NDYxNzh9.ktC8DGR1B38xSh8dDfasLXE0Quz_HoTFsqLiOs1090U",
    "token_type": "bearer",
    "expires_in": 35999
}

The response body contains the following fields:

Field Name	Description	Sample Value
access_token	The requested JWT	see above
token_type	What type of JWT this is	bearer This is the only valid value
expires_in	How many seconds from issue time until the token expires	3599

FAILURE

If Integrated Windows Authentication fails, i.e., the API consumer cannot provide valid credentials, a 401 Unauthorized response is returned.

If Integrated Windows Authentication succeeds but the client id is invalid, a 400 response is returned with a body of:

{
  "error":"invalid_clientId",
  "error_description":"client_id is not valid"
}

Token Expiration

When a token expires, the Connect API will return a 401 – Unauthorized on the next API request. As described above, that 401 response contains a WWW-Authenticate challenge header with sufficient information for a client to start or redo authentication and get another token.

Token Security

Inherent in the JWT spec are several security features.

1. Token expiration: tokens expire after X hours, after which a new token must be acquired. This is a mitigation against attacks using compromised tokens; at a minimum, the token will stop working at some point

2. Token signing: tokens are signed by the Authentication Service and that signature is verified by the API using a shared signing key. The signature is essentially a complicated hash of the payload. Validating the signature ensures the payload of the token, i.e., the asserted claims (agent id), has not been tampered with by a third party trying to assert greater or ungranted rights

These features do not mitigate the need to use HTTPS (as we do in the API) to prevent valid JWTs from being intercepted by malicious users or programs.

Mapping a Windows Identity to a Connect Agent

When an API consumer enters correct credentials for their domain account via Integrated Windows Authentication, the Connect Authentication Service then tries to map that domain account to a Connect Agent. The Authentication Service compares the Windows user name against the login name of the Connect Agent. If there is an exact match, then this is the Connect Agent the Authentication Service will return a token for. To account for customers’ preferences on whether to include the “domain\” in the Agent’s login name or when the API consumer provides credentials in the browser, the Authentication Service will also accept a match of just the portion of the login name after the “domain\” to the authenticated Windows user name.

Authorization

Every call to the Connect API must include an Authorization header with “Bearer” and then a valid JWT. The Connect API inspects this token and based on the identity of the agent (the agent id), authorizes the request. This authorization is based on the Business Unit structure configured in the Connect Admin Site.

Default Authorization

By default, every agent is authorized to get information about themselves, such as information about the Sessions they are participating in and their own profile information and settings (called “me” information).

Business Unit, Group, Team, and Role-Based Authorization

Based on the business unit, team, and groups and role an agent is assigned to (supervisor, etc.), that agent can see information about other agents' sessions and profiles. For example, a Team Lead can see information about all the agents on their team, as well as their sessions.

Endpoints

This section specifies the features of the Connect API endpoints, including valid request formats and response entity definitions. Endpoints can contain many methods, for example, the Agent Status endpoint contains both the Agent Status by Agent method and the Update Agent Status method.

This specification includes a sample JSON request, including headers, query string arguments, and POST body for each method. It also includes one or more sample JSON responses for each method, notes on non-200 OK responses, authorization, and some implementation notes for developers upgrading an application from v1.0 to v2. Finally, there is a link at the end of each method specification to the Request & Response Dictionary for a formal definition of methods’ responses and requests as needed.

Request Headers

Every Request must include Authorization, Accept, and Accept-Encoding headers. POST requests must also include a Content-Type header. We specify these headers in detail here so that we don’t have to repeat that detail for every method.

Header Name	Description	Sample Value
Authorization	A valid JWT for the logged in agent	Bearer eyJ0eXAiO...
Accept	What format of response the API consumer expects back	application/json This is the only valid value
Accept-Encoding	Encoding of the response that the API consumer can handle	gzip This is the only valid value
Content-Type	Encoding of the POST body	application/json This is the only valid value

Response Format

Unless specified otherwise, every API method responds with a JSON payload.

Authorization and 401s

Every API method will return a 401 – Unauthorized response if invoked without a JWT in the Authorization Header or with an invalid or expired JWT.

Info

The Connect Web API can run multiple versions of the API at once for backwards compatibility. The Info endpoint provides information on what version of Connect and the API(s) are running and the available SignalR transports.

Base Info

• The base Info method returns information on what version of Connect is running and what versions of the API are running.

• The base Info method is accessible off the Connect Web API Root URL at: /webapi/api/info

• This method was added in Connect versions 4.0.9 and 4.1.1.

Request - HTTP GET

Requires Authorization, Accept, and Accept-Encoding headers.

GET /webapi/api/info HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eEEiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmludGVybmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQj1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQyOTQxMzcsIm5iZiI6MTQ3NDI5MzUzN30.gy48Uf5xNRWKUt74qrSXuFCDreaWhyfnCWa4xiaI
Accept: application/json
Accept-Encoding: gzip

Response - 200 OK

The running Connect version and an array of the running API versions and their relative URL’s off the root API URL

{
  "connectVersion": "4.0.1.0",
  "apiVersions": [
    {
      "version": "1.0",
      "relativeUrl": "/v1.0"
    },
    {
      "version": "2",
      "relativeUrl": "/v2"
    }
  ],
  "signalRTransports": [
    "webSockets",
    "serverSentEvents",
    "longPolling"
  ]
}

The base Info response is specified in detail at: Base Info Response

Failed Responses

If there is an error on the API server while getting a response, the Info endpoint should return a 500 – internal server error response.

Profile

The Profile endpoint exposes contact center settings for the logged in Agent.

Who is the Logged in Agent?

When we say “the logged in Agent” we mean the Agent with the Agent Id asserted in the JWT access token. So, if the JWT in the Authorization header has a claim of connect_agent_id = 10, that means the logged in Agent is the Agent with Agent Id of 10.

Base Profile

• The base Profile method returns the contact center settings for the logged in agent.

• The base Profile method is accessible off the Connect Web API Root URL at: /webapi/api/v2/profile

• This method was added in Connect versions 4.0.9 and 4.1.1.

Request - HTTP GET

Requires Authorization, Accept, and Accept-Encoding headers.

GET /webapi/api/v2/profile HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eEEiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmludGVybmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQj1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQyOTQxMzcsIm5iZiI6MTQ3NDI5MzUzN30.gy48Uf5xNRWKUt74qrSXuFCDreaWhyfnCWa4xiaI
Accept: */*
Accept-Encoding: gzip

Response - 200 OK

The logged in agent’s Connect settings and profile.

{
  "type": "agent",
  "id": 15,
  "teamId": 1,
  "name": "Peter Miller",
  "emailAddress": "pmiller@ccdev2015.com",
  "localeKey": "en-us",
  "enabledModalities": [
    "audio",
    "instantMessage",
    "message"
  ],
  "isDirectProxyEnabled": false,
  "isFederatedDeployment": false,
  "canMarkSelfAsSuspended": true,
  "useSilverlightAgentConsole": false,
  "hideRecordButton": false,
  "attendantSipUri": "sip:Connect.41.Attendant@ccdev2015.internal",
  "domain": "ccdev2015.internal",
  "hideRecordingButton": false,
  "discoveryXFrameUrlOverride": "",
  "discoveryUserUrlOverride": "false",
  "agentGRUU": "1234-ABCD-5678-EFGH"
  "proxyDirectCalls": "false",
  "hiddenQueues": {
    "items": [
      {
        "queueId": "-1",
        "queueName": "Direct Inbound"
      },
      …
    ],
    "count": "2"
  },
}

The base Profile response is specified in detail at: Base Profile Response

Failed Responses

1. If there is an error on the API server while getting a response, return a 500 – internal server error response

2. If the logged in agent has no profile, i.e., the agent Id is not valid, return a 404 – Not found response

Get MBU Structure

• The Get MBU Structure method returns the MBU Structure for the logged in agent.

• The Get MBU Structure method is accessible off the Connect Web API Root URL at: /webapi/api/v2/profile/mbu

Request – HTTP GET

• Requires Authorization, Accept and Accept-Encoding and Content-Type headers.

• There are no URL parameters.

GET /webapi/api/v2/profile/mbu HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eEEiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmludGVybmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQj1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQyOTQxMzcsIm5iZiI6MTQ3NDI5MzUzN30.gy48Uf5xNRWKUt74qrSXuFCDreaWhyfnCWa4xiaI
Accept: */*
Accept-Encoding: gzip

Response – 200 OK

The logged in agent’s Connect MBU Structure.

{
  "agents”: [
    {
      “type”: “Agent”,
      “id”: 1234,
      “name”: “Test”,
      “teamId”: 1234,
      “canSilentJoin”: true,
      “canWhisperJoin”: false,
      “canRecord”: true
    },
    …
  ],
  “queues”: [
    {
      “type”: “Queue”,
      “id”: 1234,
      “name”: “Test”,
      “businessUnitId”: 1234,
      “teamIds”: [1, 2, 3]
    },
    …
  ],
  “teams”: [
    {
      “type”: “Team”,
      “id”: 1234,
      “name”: “Test”,
      “businessUnitId”: 1234,
      “groupIds”: [1, 2, 3],
      “agentIds”: [1, 2, 3],
      “queueIds”: [1, 2, 3]
    },
    …
  ],
  “groups”: [
    {
      “type”: “Group”,
      “id”: 1234,
      “name”: “Test”,
      “teamIds”: [1, 2, 3]
    },
    …
  ],
  “businessUnits: [
    {
      “type”: “Business Unti”,
      “id”: 1234,
      “name”: “Test”,
      “teamIds”: [1, 2, 3],
      “queueIds”: [1, 2, 3]
    },
    …
  ]
}

The Get MBU Structure response is specified in detail at: Get MBU Structure Response

Failed Responses

1. If there is an error on the API server while getting a response, return a 500 – internal server error response

2. If the logged in agent has no MBU structure, i.e., the agent Id is not valid, return a 404 – Not found response

Get Dashboard Settings

• The Get Dashboard Settings method returns the Dashboard Settings for the logged in Agent.

• The Get Dashboard Settings method is accessible off the Connect Web API Root URL at: /webapi/api/v2/profile/dashboardsettings

Request – HTTP GET

• Requires Authorization, Accept and Accept-Encoding and Content-Type headers.

• Url parameters:

o None

GET /webapi/api/v2/profile/dashboardsettings HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eEEiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmludGVybmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQj1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQyOTQxMzcsIm5iZiI6MTQ3NDI5MzUzN30.gy48Uf5xNRWKUt74qrSXuFCDreaWhyfnCWa4xiaI
Accept: */*
Accept-Encoding: gzip

RESPONSE – 200 OK

• The logged in Agent’s Connect Dashboard Settings.

{
  “templateId”: 1,
  “templateRevision: “1”,
  “definition: {
  …
  },
  “agentConsoleTemplateId”: 0,
  “agentConsoleTemplateRevision”: 0,
  “agentConsoleDefinition: {
    …
  },
  “attendantEndpoint”: “…”
}

• The Get Dashboard Settings response is specified in detail at: Get Dashboard Settings Response

Failed Responses

1. If there is an error on the API server while getting a response, return a 500 – internal server error response

2. If the logged in Agent has no Dashboard Settings, i.e., the agent Id is not valid, return a 404 – Not found response

UNREGISTER

• The Unregister method attempts to clean up the matching sip and gruu and end any active calls for the supplied session Ids..

• The Unregister method is accessible off the Connect Web API Root URL at: /webapi/api/v2/profile/unregister

Request – HTTP POST

• Requires Authorization, Accept, and Accept-Encoding and Content-Type headers.

• Url parameters:

• sip - SIP of the agent to unregister
• gruu - GRUU of the agent to unregister
• sids - session ids to clean up

POST /webapi/api/v2/profile/unregister?sip=test.user@domain.com&gruu=1234&sids=1,2,3 HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eEEiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmludGVybmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQj1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQyOTQxMzcsIm5iZiI6MTQ3NDI5MzUzN30.gy48Uf5xNRWKUt74qrSXuFCDreaWhyfnCWa4xiaI
Accept: */*
Accept-Encoding: gzip

Response – 200 OK

Failed Responses

If there is an error on the API server while getting a response, return a 500 – internal server error response

Sessions

The Sessions endpoint allows API consumers to query for active sessions by agent.

Sessions by Agent

• The Sessions by Agent method returns basic details on active Sessions for the given primary Agent

• The Sessions by Agent method is accessible off the Connect Web API Root URL at: /webapi/api/v2/sessions?agentId={agentId}&activeOnly=true

• This method was added in Connect versions 4.0.9 and 4.1.1.

Request – HTTP GET

• Requires Authorization, Accept and Accept-Encoding headers.

• Query string parameters:

o agentId - the agent ID of the primary agent

o activeOnly - only include active sessions. Always true.

GET /webapi/api/v2/sessions?agentId=5&activeOnly=true HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eEEiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmludGVybmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQj1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQyOTQxMzcsIm5iZiI6MTQ3NDI5MzUzN30.gy48Uf5xNRWKUt74qrSXuFCDreaWhyfnCWa4xiaI
Accept: */*
Accept-Encoding: gzip

Response – 200 OK

A response with an array of items, the sessions an agent is currently the Primary Agent on, and a count of those items

{
  "items": [
  {
  "queueName": "Jonah Queue",
  "agentName": "Jonah",
  "customerPhone": "sip:dg@claritycon.com",
  "modality": "InstantMessage",
  "sessionId": 66033,
  "sessionType": "Queued",
  "queueId": 3,
  "customerName": "DG",
  "agentId": 16,
  "isRecording": true,
  "canBeRecorded": true,
  "isSilentJoined": false,
  "isWhisperJoined": false,
  "sessionStatus": "Active",
  "queuedMs": 0,
  "activeMs": 0,
  "canBeSilentJoined": true,
  "canBeWhisperJoined": true,
  "modalityId": 1,
  "isOnHold": false,
  "recordingStartTime": "2016-08-31T17:41:16.967Z",
  "answeredTimeStamp": "2016-08-31T17:40:45.9Z",
  "sessionHasEnded": false,
  "startTimeStamp": "2016-08-31T17:40:38.51Z",
  "callFlowName": "Intro Call Flow"
  },
  {
  "queueName": "Dan Queue",
  "agentName": "Jonah",
  "customerPhone": "sip:dq@claritycon.com",
  "modality": "InstantMessage",
  "sessionId": 66045,
  "sessionType": "Queued",
  "queueId": 2,
  "customerName": "Jonah Ruffer",
  "agentId": 16,
  "isRecording": true,
  "canBeRecorded": true,
  "isSilentJoined": false,
  "isWhisperJoined": false,
  "sessionStatus": "After Call",
  "queuedMs": 0,
  "activeMs": 0,
  "canBeSilentJoined": true,
  "canBeWhisperJoined": true,
  "modalityId": 1,
  "isOnHold": false,
  "recordingStartTime": "2016-08-31T17:41:16.967Z",
  "answeredTimeStamp": "2016-08-31T17:40:45.9Z",
  "sessionHasEnded": false,
  "startTimeStamp": "2016-08-31T17:40:38.51Z",
  "callFlowName": "Intro Call Flow"
  }
  ],
 "count": 2
}

The sessions by agent response is specified in detail at: Sessions by Agent Response

Failed Responses

1. If there is an error on the API server while getting a response, return a 500 – internal server error response

2. If no active sessions are found for this agent, return a 200 – OK with an empty array as the response

3. If the activeOnly flag is false, return a 400 – Bad Request

Additional Authorization

If the API consumer does not have MBU permissions to see the requested Agent’s Sessions, return a 401 – Unauthorized

This is NOT implemented in CU 4.0.9 or 4.1.1

Get IM Transcript History

• The Get IM Transcript History method returns current or historical IM transcript for a session

• The Get IM Transcript History method is accessible off the Connect Web API Root URL at: /webapi/api/v2/sessions/{sessionId}/transcript

Request – HTTP GET

• Requires Authorization, Accept and Accept-Encoding headers.

• Query string parameters:

o startTimsetamp - start time to query

o endTimestamp - end time to query

o size - number of transcripts to return

GET /webapi/api/v2/sessions/18/transcript HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eEEiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmludGVybmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQj1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQyOTQxMzcsIm5iZiI6MTQ3NDI5MzUzN30.gy48Uf5xNRWKUt74qrSXuFCDreaWhyfnCWa4xiaI
Accept: */*
Accept-Encoding: gzip

Response – 200 OK

A response with an array of items, and a count of those items:

 {
  "items": [
    {
      "timeStamp": "2015-07-20T20:28:09.893Z",
      "to": "Commander William T. Riker",
      "from": "Commander William T. Riker",
      "message": "1",
      "fromAgent": false,
      "type": "imMessage",
      "id": 23
    },
    …
  ],
  "count": 5
}

The Get IM Transcript History response is specified in detail at: Get IM Transcript History Response

Failed Responses

1. If there is an error on the API server while getting a response, return a 500 – internal server error response

2. If all query parameters are provided (startTimestamp, endTimestamp, and size), return a 400 – Bad Request

3. If only the size query parameter is provided, return a 400 – Bad Request

Session by ID

• The Sessions by Id method returns basic details on Sessions for the given Session Id

• The Sessions by Id method is accessible off the Connect Web API Root URL at: /webapi/api/v2/sessions/{sessionId}

• This method was added in Connect versions 4.0.10 and 4.1.2.

Request – HTTP GET

• Requires Authorization, Accept, and Accept-Encoding headers.

• Query string parameters are below. These parameters are optional and default to false if not specified:

o includeCustomerHistory - flag determines if customer session history should be included in the response

o customerHistoryLimit - number of customer session history records to be included. By default, three historical records are gathered if the consumer does not specify a limit. API can get a maximum amount of 50 customer session history records. The parameter, includeCustomerHistory, must be true. Otherwise, the parameter is ignored.

o includeImPrompts - flag determines if IM Prompts should be included in the response.

o includeIvrData - flag determines if IVR Data should be included in the response.

o includeDispositions - flag determines if Dispositions should be included in the response. This includes the SubDispositions as well.

o includeCurrentTranscript - flag determines if Current Transcript (instant messages) should be included in the response.

o includeExtraItems - flag determines if Extra Items should be included in the response.

o includeSessionEventHistory - flag determines if Session Event History should be included in the response.

o includeAftercallOptions - flag determines if Aftercall Options should be included in the response. This includes whether the agent can set indefinite after call time by going to a busy presence during the call as well as the default amount of time an agent has for after call.

o includeHoldTimerThreshold - flag determines if Hold Timer Threshold should be included in the response. The Hold Timer Threshold is how long the agent console will wait during hold before notifying agent that customer is still on hold.

For example, here is a request to get information on session Id 78520 with just one customer historical record and all the query string parameters enabled.

GET /webapi/api/v2/sessions/78520?includeCustomerHistory=true&customerHistoryLimit=1&includeImPrompts=true&includeIvrData=true&includeDispositions=true&includeCurrentTranscript=true&includeExtraItems=true&includeSessionEventHistory=true&includeAftercallOptions=true&includeHoldTimerThreshold=true 
HTTP/1.1
Host: 41.claritycustomer.com:80
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI
Accept: */*Accept-Encoding: gzip, deflate, sdch

Response – 200 OK

Session By Id Response has Session information and customer history (optional) as a List Response of Session Base objects.

{ 
  "customerHistory": {
    "items": [
      {
        "agentId": 16,
        "agentName": "Jonah",
        "callFlowId": 1,
        "callFlowName": "Starter Quick Ivr",
        "customerId": "Jonah Ruffer",
        "customerName": "Jonah Ruffer",
        "customerPhone": "sip:jruffer@claritycon.com",
        "modality": "InstantMessage",
        "modalityId": 1,
        "sessionId": 78580,
        "sessionType": "Queued",
        "queueId": 3,
        "queueName": "Jonah Queue",
        "startTimeStamp": "2016-12-20T21:59:26.107Z"
      }
    ],
    "count": 1
  },
  "aftercallOptions": {
    "isManualAfterCallEnabled": true,
    "afterCalltimeSeconds": 10,
    "id": 0
  },
  "holdTimerThreshold": 10,
  "imPrompts": {
    "items": [
      {
        "promptName": "CustomerName",
        "promptValue": "Welcome Jonah Ruffer to the Call Center!",
        "type": "imPrompt",
        "id": 8
      }
    ],
    "count": 1
  },
  "ivrData": {
    "items": [
      {
        "callFlowName": "Starter Quick Ivr",
        "ivrNodes": {
          "items": [
            {
              "nodeName": "Jonah Empty Queue",
              "nodeNote": "Set Queue to Jonah Queue.",
              "duration": 0,
              "type": "ivrNode",
              "id": 80033
            }
          ],
          "count": 1
        },
        "type": "ivrData",
        "id": 78301
      }
    ],
    "count": 1
  },
  "callDispositions": {
    "items": [
      {
        "dispositionId": 4,
        "disposition": "Accounts",
        "businessUnitId": 1,
        "subDispositions": {
          "items": [
            {
              "subDispositionId": 8,
              "subDisposition": "Pasword Change",
              "id": 8
            }
          ],
          "count": 1
        },
        "type": "callDisposition",
        "id": 4
      }
    ],
    "count": 1
  },
  "transcript": {
    "items": [],
    "count": 0
  },
  "extraItems": {
    "items": [
      {
        "extraItemId": -1,
        "key": "CallerPhoneNumber",
        "value": "13128633465;EXT=3465",
        "type": "extraItem",
        "id": 137957,
    	 "isSearchable": false
      },
      {
        "extraItemId": -1,
        "key": "IsCallAfterHours",
        "value": "False",
        "type": "extraItem",
        "id": 137958,
   "isSearchable": false
      },      
    ],
    "count": 2
  },
  "sessionEventHistory": {
    "items": [
      {
        "eventText": "Session created.",
        "lastUpdated": "2016-12-19T19:06:03.817Z",
        "updatedBy": "APP-01",
        "id": 186068
      },
      {
        "eventText": "Session status changed to New.",
        "lastUpdated": "2016-12-19T19:06:03.833Z",
        "updatedBy": "APP-01",
        "id": 186069
      },
      {
        "eventText": "Session entered attendant (IVR).",
        "lastUpdated": "2016-12-19T19:06:05.31Z",
        "updatedBy": "APP-01",
        "id": 186070
      },
      {
        "eventText": "Session has been assigned to queue: Jonah Queue",
        "lastUpdated": "2016-12-19T19:06:15.013Z",
        "updatedBy": "APP-01",
        "id": 186071
      },
      {
        "eventText": "Session status changed to Queued.",
        "lastUpdated": "2016-12-19T19:06:15.113Z",
        "updatedBy": "APP-01",
        "id": 186072
      },
      {
        "eventText": "No agents immediately available, queueing.",
        "lastUpdated": "2016-12-19T19:06:15.243Z",
        "updatedBy": "APP-02",
        "id": 186073
      },
      {
        "eventText": "Customer hung up.",
        "lastUpdated": "2016-12-19T19:06:24.883Z",
        "updatedBy": "APP-01",
        "id": 186074
      },
      {
        "eventText": "Session status changed to Abandoned.",
        "lastUpdated": "2016-12-19T19:06:25.243Z",
        "updatedBy": "APP-01",
        "id": 186075
      },
      {
        "eventText": "Session terminating.",
        "lastUpdated": "2016-12-19T19:06:25.743Z",
        "updatedBy": "APP-01",
        "id": 186076
      }
    ],
    "count": 9
  },
  "sessionMessages": {
    "items": [],
    "count": 0
  },
  "activeMs": 0,
  "canBeRecorded": true,
  "canBeSilentJoined": true,
  "canBeWhisperJoined": true,
  "isOnHold": true,
  "holdStartTime": "2016-12-19T19:06:15.257Z",
  "isRecording": false,
  "isSilentJoined": false,
  "isWhisperJoined": false,
  "queuedMs": 0,
  "sessionHasEnded": true,
  "sessionStatus": "Abandoned",
  "agents": {
    "items": [],
    "count": 0
  },
  "offers": {
    "items": [],
    "count": 0
  },
  "agentName": "Unknown",
  "callFlowId": 1,
  "callFlowName": "Starter Quick Ivr",
  "customerId": "Jonah Ruffer",
  "customerName": "Jonah Ruffer",
  "customerPhone": "sip:jruffer@claritycon.com",
  "modality": "Audio",
  "modalityId": 2,
  "sessionId": 78520,
  "sessionType": "Queued",
  "queueId": 3,
  "queueName": "Jonah Queue",
  "startTimeStamp": "2016-12-19T19:06:03.803Z"
}

The Sessions by Id response is specified in detail at: Session By Id Response

Failed Responses

1. If there is an error on the API server while getting a response, return a 500 – internal server error response

2. If no active Sessions are found for the specified Id, return a 500– internal server error response

Additional Authorization

If the API consumer does not have MBU permissions to see the requested Agent’s Sessions, return a 401 – Unauthorized

Get GRUU for Session

• The Get GRUU for Session method returns the GRUU associated with the session

• The Get GRUU for Session method is accessible off the Connect Web API Root URL at: /webapi/api/v2/sessions/{sessionId}/gruu

Request – HTTP GET

Requires Authorization, Accept, and Accept-Encoding headers.

GET /webapi/api/v2/sessions/18/gruu HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eEEiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmludGVybmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQj1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQyOTQxMzcsIm5iZiI6MTQ3NDI5MzUzN30.gy48Uf5xNRWKUt74qrSXuFCDreaWhyfnCWa4xiaI
Accept: */*
Accept-Encoding: gzip

Response – 200 OK

A response containing a string representing the GRUU

Failed Responses

If there is an error on the API server while getting a response, return a 500 – internal server error response

Customer History by Session ID

• The Customer History By Session Id method returns customer history for the Session’s customer.

• The Customer History By Session Id method is accessible off the Connect Web API Root URL at: /webapi/api/v2/sessions/customerHistory/{sessionId}

• Maximum amount of records that can be retrieved in one request is 50.

• This method was added in Connect versions 4.0.10 and 4.1.2.

Request – HTTP GET

• Requires Authorization, Accept and Accept-Encoding headers.

• Query string parameters:

o start (optional) - earliest timestamp boundary. If specified, 50 historical records from start time stamp until present timestamp are retrieved.

o end (optional) - latest timestamp boundary. If specified, 50 historical records from beginning of time until this end time stamp are retrieved.

o limit (optional) - number of customer history records to retrieve. If not specified, get 50 of the most recent records. If limit is over 50 or under 0, retrieve 50 records.

Acceptable query string combinations:

Combination	Description	Sample URL	Sample Explained
start	Returns records from start until now	/customerHistory/123?start=2016-6-15 5:30:00.15	Get records from 2016-6-15 5:30:00:15 until now for the session Id 123.
start, end	Returns records between start and end	/customerHistory/123?start=2016-6-15 5:30:00.15&end=2016-10-15 8:30:00.15	Get customer historical records between 2016-6-15 5:30:00:15 and 2016-10-15 8:30:00.15 for the session Id 123.
start, end, limit	Not supported	/customerHistory/123?start=2016-6-15 5:30:00.15&end=2016-10-15 8:30:00.15&limit=10	Not supported
start, limit	Returns limit number of records from start until now	/customerHistory/123?start=2016-6-15 5:30:00.15&limit=10	Get first 10 customer historical records from 2016-6-15 5:30:00:15 until today for the session Id 123.
end	Returns all records from beginning of time to end	/customerHistory/{sessionId}?end=2016-10-15 8:30:00.15	Get customer historical records from beginning of time until 2016-10-15 8:30:00.15 for the session Id 123.
limit	Not supported	/customerHistory/123?limit=10	Not supported
none	Returns all historical records	/customerHistory/123	Get all historical records for the session Id 123.
end, limit	Returns limit number of records from beginning of time to end.	/customerHistory/123?end=2016-10-15 8:30:00.15&limit=10	Get first 10 customer historical records from 2016-10-15 8:30:00.15 until beginning of time for the session Id 123.

Here is a sample request to get customer history for Session Id 123 between 2016-6-15 5:30:00.12 and 2016-11-15

GET /webapi/api/v2/sessions/customerHistory/123?start=2016-6-15 5:30:00.13&end=2016-11-15 HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eEEiOiJKV1QiLCJhbGciOiJIUz
Accept: */*
Accept-Encoding: gzip

Response – 200 OK

• A List Response of Session Base objects.

• There is no customer history for the specified session Id.

 

{
  "items": [
    {
      "agentId": 41,
      "agentName": "Rob T.",
      "customerId": "Captain Jean-Luc Picard",
      "customerName": "Captain Jean-Luc Picard",
      "customerPhone": "sip:picard@ccdev2015.internal",
      "modality": "Audio",
      "modalityId": 2,
      "sessionId": 71736,
      "sessionType": "Queued",
      "queueId": 5,
      "queueName": "robsQ",
      "startTimeStamp": "2016-09-06T14:56:06.95Z"
    },
    {
      "agentId": 41,
      "agentName": "Rob T.",
      "customerId": "Captain Jean-Luc Picard",
      "customerName": "Captain Jean-Luc Picard",
      "customerPhone": "sip:picard@ccdev2015.internal",
      "modality": "Audio",
      "modalityId": 2,
      "sessionId": 71738,
      "sessionType": "Queued",
      "queueId": 5,
      "queueName": "robsQ",
      "startTimeStamp": "2016-09-06T15:02:08.643Z"
    }
    
  ],
  "count": 2
}

• The Customer History by Session Id response is specified in detail here: List Response of Session Base

Failed Responses

1. If there is an error on the API server while getting a response, return a 500 – internal server error response

Additional Authorization

1. If the API consumer does not have MBU permissions to see the requested Session data, return a 401 – Unauthorized

Update Session Extra Items

• The Update Session Extra Items method updates extra item data in the session

• The Update Session Extra Items method is accessible off the Connect Web API Root URL at: /webapi/api/v2/sessions/{sessionId}/setextraitems

Request – HTTP GET

Requires Authorization, Accept and Accept-Encoding headers.

A request update the extra data for session 18 would look like:

GET /webapi/api/v2/sessions/18/setextraitem HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eEEiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmludGVybmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQj1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQyOTQxMzcsIm5iZiI6MTQ3NDI5MzUzN30.gy48Uf5xNRWKUt74qrSXuFCDreaWhyfnCWa4xiaI
Accept: */*
Accept-Encoding: gzip

{
  “extraItemId”: 12,
  “extraItemName”: “Subject”,
  “extraItemValue”: “test”
}

The Update Session Extra Items request is specified in detail at: Update Session Extra Items Request

Response – 204 NO CONTENT

Failed Responses

1. If there is an error on the API server while getting a response, return a 500 – internal server error response

2. If the request body is null, the extra item Id is null and the extra item name is null, or the extra item value is null, return a 400 – bad request error response

Save Call Notes

• The Save Call Notes method sets notes for the session

• The Save Call Notes method is accessible off the Connect Web API Root URL at: /webapi/api/v2/sessions/{sessionId}/setcallnotes

Request – HTTP GET

Requires Authorization, Accept and Accept-Encoding headers.

A request set call notes for session 18 would look like:

GET /webapi/api/v2/sessions/18/setcallnotes HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eEEiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmludGVybmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQj1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQyOTQxMzcsIm5iZiI6MTQ3NDI5MzUzN30.gy48Uf5xNRWKUt74qrSXuFCDreaWhyfnCWa4xiaI
Accept: */*
Accept-Encoding: gzip

{
  “note”: “test”
}

The Save Call Notes request is specified in detail at: Save Call Notes Request

Response – 204 NO CONTENT

Failed Responses

1. If there is an error on the API server while getting a response, return a 500 – internal server error response

2. If the request body is null, return a 400 – bad request error response

Save Dispositions

• The Save Dispositions method sets dispositions for the session

• The Save Dispositions method is accessible off the Connect Web API Root URL at: /webapi/api/v2/sessions/{sessionId}/setdispositions

Request – HTTP GET

Requires Authorization, Accept and Accept-Encoding headers.

A request set dispositions for session 18 would look like:

GET /webapi/api/v2/sessions/18/setdispositions HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eEEiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmludGVybmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQj1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQyOTQxMzcsIm5iZiI6MTQ3NDI5MzUzN30.gy48Uf5xNRWKUt74qrSXuFCDreaWhyfnCWa4xiaI
Accept: */*
Accept-Encoding: gzip

{
  “dispositionId”: 1,
  “subDispositionId”: 1
}

The Save Dispositions request is specified in detail at: Save Dispositions Request

Response – 204 NO CONTENT

Failed Responses

1. If there is an error on the API server while getting a response, return a 500 – internal server error response

2. If the request body is null, return a 400 – bad request error response

Start Recording Sessions by Agent

• The Start Recording Sessions by Agent method starts recording for all Sessions the Agent is participating in

• The Start Recording Sessions by Agent method is accessible off the Connect Web API Root URL at: /webapi/api/v2/sessions/callcontrol/startRecordingSessions/{agentId}

• This method was added in Connect versions 4.0.10 and 4.1.2

Request – HTTP POST

• Requires Authorization, Accept and Accept-Encoding headers.

• Query string parameters:

o agentId - the Agent Id of the participating agent.

• No POST body content is required

For example:

POST /webapi/api/v2/sessions/callcontrol/startRecordingSessions/5 HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eEEiOiJKV1QiLCJhbGciOiJIU
Accept: */*
Accept-Encoding: gzip

Response – 200 OK

A List Response of Session Recording Request Status objects for Sessions the Agent is currently participating on.

{
  "items": [
    {
      "sessionId": 100,
      "isRecording": false,
      "canBeRecorded": true,
      "requestDenied": false,
      "requestFailed": false
    }
   ],
   "count": 1
 }

The Session Recording Request Status response is specified in detail at: Session Recording Request Status Response

Failed Responses

1. If there is an error on the API server while getting a response, return a 500 – internal server error response

2. If no active Sessions are found for this Agent, return a 200 – OK with an empty array as the response

Additional Authorization

1. If the API consumer does not have MBU permissions to see the requested Agent’s Sessions, return a 401 – Unauthorized

2. If the API Consumer is not authorized to record the Primary Agent on the Session, return a 401—Unauthorized

3. If recording the specified Session is prohibited, return a 401—Unauthorized

Stop Recording Sessions by Agent

• The Stop Recording Sessions by Agent method stops recording for all Sessions the Agent is participating in

• The Stop Recording Sessions by Agent method is accessible off the Connect Web API Root URL at: /webapi/api/v2/sessions/callcontrol/stopRecordingSessions/{agentId}

• This method was added in Connect versions 4.0.10 and 4.1.2

Request – HTTP POST

• Requires Authorization, Accept and Accept-Encoding headers.

• Query string parameters:

o agentId - the Agent Id of the participating Agent

• No POST body content is required

For example:

POST /webapi/api/v2/sessions/callcontrol/stopRecordingSessions/5 HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eEEiOiJKV1QiLCJhbGciOiJIU
Accept: */*
Accept-Encoding: gzip

Response – 200 OK

A List Response of Session Recording Request Status objects for Sessions the Agent is currently participating on.

{
  "items": [
    {
      "sessionId": 100,
      "isRecording": false,
      "canBeRecorded": true,
      "requestDenied": false,
      "requestFailed": false
    }
   ],
   "count": 1
 }

The Session Recording Request Status response is specified in detail at: Session Recording Request Status Response

Failed Responses

1. If there is an error on the API server while getting a response, return a 500 – internal server error response

2. If no active Sessions are found for this Agent, return a 200 – OK with an empty array as the response

Additional Authorization

1. If the API consumer does not have MBU permissions to see the requested Agent’s Sessions, return a 401 – Unauthorized

2. If the API Consumer is not authorized to record the Primary Agent on the Session, return a 401—Unauthorized

3. If recording the specified Session is prohibited, return a 401—Unauthorized

Agent Status

The Agent Status endpoint is where an API consumer can get an agent’s current Connect Status and update the agent’s Connect Status.

Agent Status by Agent

• The Agent Status by Agent method returns the Agent’s current Connect Status

• The Agent Status by Agent method is accessible off the Connect Web API Root URL at: /webapi/api/v2/agentStatus/{agentId}?currentOnly=true

• This method was added in Connect versions 4.0.9 and 4.1.1.

Request – HTTP GET

• Requires Authorization, Accept and Accept-Encoding headers.

• Url parameters:

o agentId - the Id of the Agent to set Connect Status for

• Query string parameters:

o currentOnly - only include the Agent’s current Connect Status. Always true.

GET /webapi/api/v2/agentStatus/5?currentOnly=true HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eEEiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmludGVybmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQj1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQyOTQxMzcsIm5iZiI6MTQ3NDI5MzUzN30.gy48Uf5xNRWKUt74qrSXuFCDreaWhyfnCWa4xiaI
Accept: */*
Accept-Encoding: gzip

 

Response– 200 OK

The Connect Agent Status for the requested Agent

For example:

{
  "type": "agent",
  "id": 15,
  "name": "Peter Miller",
  "currentStatus": {
    "agentStatus": "unavailable",
    "agentStatusId": 3,
    "reasonCodeName": "In A Meeting",
    "reasonCodeId": 1,
    "startTime": "2016-10-14T13:59:54.993Z",
    "isSuspended": false
  }
}

• The Agent Status by Agent response is specified in detail at: Agent Status by Agent Response
• If the requested Agent has an invalid SIP address, the Agent Status by Agent response will be for Unknown status:

{
  "type": "agent",
  "id": 15,
  "currentStatus": {
    "agentStatus": "unknown",
    "agentStatusId": 4,
  }
}

Failed Responses

1. If there is an error on the API server while getting a response, return a 500 – internal server error response

2. If currentOnly is false, return a 400 – bad request with message that must have query string parameter currentOnly=true

Additional Authorization

1. If the API consumer does not have MBU permissions to see the Agent’s Connect Status, return a 401 - Unauthorized

Update Agent Status

• The Update Agent Status method lets you set the Agent’s current Connect Status, including away Reason Code and suspended flag

• The Update Agent Status method is accessible off the Connect Web API Root URL at: /webapi/api/v2/agentStatus/update/{agentId}

• This method was added in Connect versions 4.0.9 and 4.1.1.

Request – HTTP POST

• Requires Authorization, Accept and Accept-Encoding and Content-Type headers.

• Url parameters:

o agentId - the Id of the Agent to set Connect Status for

• POST body

o The Agent Status Id (and away Reason Code Id if Unavailable)

OR the isSuspended flag

A request to set Agent 5 to Unavailable (Away) with a reason code of 1 (On Break) would look like:

POST /webapi/api/v2/agentstatus/update/5 HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmlbmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQjFBMC1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQzMDczMTAsIm5iZiI6MTQ3NDMwNjcxMH0.iLSb78NAoam-SU6YOHVBy4OVOQWkP6KGsB7Ak
Accept: */*
Accept-Encoding: gzip
Content-Type: application/json
{ 
	"agentStatusId": 3,
	"reasonCodeId": 1
}

A request to un-suspend Agent 5 would look like:

POST /webapi/api/v2/agentstatus/update/5 HTTP/1.1

Host: connect.customer.com

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmlbmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQjFBMC1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQzMDczMTAsIm5iZiI6MTQ3NDMwNjcxMH0.iLSb78NAoam-SU6YOHVBy4OVOQWkP6KGsB7Ak

Accept: */*

Accept-Encoding: gzip

Content-Type: application/json

{

"isSuspended”: false

}

A request to un-suspend Agent 5 would look like:

POST /webapi/api/v2/agentstatus/update/5 HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmlbmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQjFBMC1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQzMDczMTAsIm5iZiI6MTQ3NDMwNjcxMH0.iLSb78NAoam-SU6YOHVBy4OVOQWkP6KGsB7Ak
Accept: */*
Accept-Encoding: gzip
Content-Type: application/json
{ 
	"isSuspended”: false
}

• The Update Agent Status request is specified in detail at: Update Agent Status Request

Response – 204 NO CONTENT

A 204 – No Content success response means the Connect Agent Status change request went through successfully. This change can be either a status change or suspension status change, but not both.

Failed Responses

1. If there is an error on the API server while getting a response, return a 500 – internal server error response

2. If the request body is null or empty, return a 400 – bad request

3. If the request body contains both an AgentStatusId and IsSuspended, return a 400 – bad request

4. If the request body contains ReasonCodeId and the AgentStatusId is not Unavailable, return a 400 – bad request

Additional Authorization

1. If the API consumer does not have MBU permissions to see the Agent Id, return a 401 - Unauthorized

List Agent Statuses by Agent

• By making a request to the List Agent Statuses by Agent endpoint with the Agent ID you can get the possible Connect Agent Statuses the Agent can be in, including Away statuses with all valid Away Reason Codes for the Agent

• he Agent Status by Agent method is accessible off the Connect Web API Root URL at: webapi/api/v2/agentStatus/list/{agentId}

Request – HTTP GET

• Requires Authorization, Accept and Accept-Encoding headers.

• Url parameters:

◦ agentId - the Id of the Agent to set Connect Status for

A sample request would therefore look like:

GET /webapi/api/v2/agentStatus/list/5 HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eEEiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmludGVybmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQj1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQyOTQxMzcsIm5iZiI6MTQ3NDI5MzUzN30.gy48Uf5xNRWKUt74qrSXuFCDreaWhyfnCWa4xiaI
Accept: */*
Accept-Encoding: gzip

Response – 200 OK

A HTTP GET to List Agent Statuses by Agent returns a JSON response that is a List Response wrapping an array of Connect Agent Status data objects

For example:

{
  items: [ 
    {
  	“agentStatus”: “Available”,
    	“agentStatusId”: 1
    },
    {
	“agentStatus”: “Unavailable”,
      “agentStatusId”: 3,
    },
    {
	“agentStatus”: “Unavailable”,
	“agentStatusId”: 3,
	“reasonCodeName”: “On Break”,
	“reasonCodeId”: “1”
    },
    {
	“agentStatus”: “Unavailable”,
	“agentStatusId”: 3,
	“reasonCodeName”: “At Lunch”,
	“reasonCodeId”: “2”
    },
    …
  ],
  count: 10
}

The List Agent Statuses by Agent response is specified in detail at: List Agent Statuses By Agent Response

Failed Responses

If there is an error on the API server while getting a response, return a 500 – internal server error response

Additional Authorizations

If the API consumer does not have MBU permissions to see the list of Agent’s Connect Statuses, return a 401 - Unauthorized

Agent Metrics

The Agent Metrics endpoint is where an API consumer can retrieve metrics for Agent(s).

AGENT BY ID

• The Agent By Id method retrieves metrics, session, and status data for a single Agent given the Agent Id in the URI.

• The Agent By Id method is accessible off the Connect Web API Root URL at: /webapi/api/v2/metrics/agents/{id}

• There are 3 data structures available that can be requested: metrics, session, and status

o To request only metrics, add “/metrics”: /webapi/api/v2/metrics/agents/{id}/metrics

o To request only the session data, add “/sessions”: /webapi/api/v2/metrics/agents/{id}/sessions

o To request only status data, add “/status”: /webapi/api/v2/metrics/agents/{id}/status

o No specified resource will default to receiving all data (metrics, session, status): /webapi/api/v2/metrics/agents/{id}

• This API supports both GET and POST verbs for this method.

Request – HTTP GET

• Requires Authorization, Accept and Accept-Encoding and Content-Type headers.

• Url parameters: Refer to Common Query String Parameters

A GET request to get metrics for Agent Id 41 would look like:

GET /webapi/api/v2/agents/41 HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc
Accept: */*
Accept-Encoding: gzip
Content-Type: application/json

The response would look like this:

{
  "type": "agent",
  "metrics": {
    "audio": {
      "ronaCount": 0,
      "answeredCount": 0,
      "directInboundCallCount": 0,
      "directOutboundCallCount": 0,
      "longestAfterCallTime": 0,
      "longestHandleTime": 0,
       …
	 …
    }
  },
  "name": "Rob T.",
  "id": 41,
  "currentStatus": {
    "agentStatus": "ringOnNoAnswer",
    "startTime": "2016-10-27T19:56:02.98Z",
    "isSuspended": false
  }
}

Request – HTTP POST

• The POST request lets the consumer specify in the POST body which metrics, session, and status properties to be included in the response.

• Requires Authorization, Accept and Accept-Encoding and Content-Type headers.

• Url parameters: Refer to Common Query String Parameters

A POST request to get the specified metric, and status properties for Agent Id 41 would look like:

POST /webapi/api/v2/agents/41 HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc
Accept: */*
Accept-Encoding: gzip
Content-Type: application/json
{
	"metricProperties": ["takenCount"],
	"statusProperties": ["agentStatus"]
}

The response would look like this:

{
  "type": "agent",
  "metrics": {
    "instantMessage": {
      "takenCount": 0
    }
  },
  "name": "Rob T.",
  "id": 41,
  "currentStatus": {
    "agentStatus": "ringOnNoAnswer"
  }
}

• The Agent By Id request is specified in detail at: Realtime Data Response

Response – 200 OK

A 200 – OK success response means the request was successfully processed and returned valid metric data.

Failed Responses

If there is an error on the API server while getting a response, return a 500 – internal server error response

Additional Authorization

1. If the requesting Agent Id is not authorized for the specified entity Id(s), return a 401 – Unauthorized.

2. If an entity Id is not specified in the query string parameters, return a 401 – Unauthorized.

Multiple Agents by ID

• The Multiple Agents By Ids method retrieves metrics and real-time data for multiple Agents given the Agent Ids in the URI.

• The Multiple Agents By Ids method is accessible off the Connect Web API Root URL at: /webapi/api/v2/metrics/agents/

• There are 3 data structures available that can be requested: metrics, session, and status

o To request only metrics, add “/metrics”: /webapi/api/v2/metrics/agents/metrics

o To request only the session data, add “/sessions”: /webapi/api/v2/metrics/agents/sessions

o To request only status data, add “/status”: /webapi/api/v2/metrics/agents/status

o No specified resource will default to receiving all data (metrics, session, status): /webapi/api/v2/metrics/agents/

• This API supports both GET and POST verbs for this method.

Request – HTTP GET

• Requires Authorization, Accept and Accept-Encoding and Content-Type headers.

• Url parameters: Refer to Common Query String Parameters

A GET request to get metrics, session, and status information for Agent Ids 41 and 37 would look like (agent is currently not handling any sessions which is why there is no session key in the response):

GET /webapi/api/v2/agents/agentIds=41,37 HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc
Accept: */*
Accept-Encoding: gzip
Content-Type: application/json

The response would look like this:

[
  {
    "type": "agent",
    "metrics": {
"audio": { “ronaCount”: 0, “answeredCount”: 0 … },
"instantMessage": { “ronaCount”: 0, “answeredCount”: 0 … },
"message": { “ronaCount”: 0, “currentlyActiveCount”: 0 … },
"agnostic": { “availableTime”: 0, “total”: 0 … },
    },
    "name": "Rob T.",
    "id": 41,
    "currentStatus": {
      "agentStatus": "ringOnNoAnswer",
      "startTime": "2016-10-27T19:56:02.98Z",
      "isSuspended": false
    }
  },
  {
    "type": "agent",
    "metrics": {
"audio": { “ronaCount”: 0, “answeredCount”: 0 … },
"instantMessage": { “ronaCount”: 0, “answeredCount”: 0 … },
"message": { “ronaCount”: 0, “currentlyActiveCount”: 0 … },
"agnostic": { “availableTime”: 0, “total”: 0 … },
    },
"name": "Commander William T. Riker",
 "id": 37,
  "currentStatus": {
      "agentStatus": "unavailable",
      "startTime": "2016-10-28T04:50:32.503Z",
      "isSuspended": false
  }
  }  
]

Request – HTTP POST

• The POST request lets the consumer specify in the POST body which metrics, session, and status properties to be included in the response.

• Requires Authorization, Accept and Accept-Encoding and Content-Type headers.

• Url parameters: Refer to Common Query String Parameters

A request to get the TakenCount and AgentStatus metrics for Agent Ids 41 and 37 would look like:

POST /webapi/api/v2/agents/41 HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc
Accept: */*
Accept-Encoding: gzip
Content-Type: application/json
{
	"metricProperties": ["takenCount"],
	"statusProperties": ["agentStatus","reasonCodeName"]
}

The response would look like this:

[
  {
    "type": "agent",
    "metrics": {
      "instantMessage": {
        "takenCount": 0
      }
    },
    "name": "Rob T.",
    "id": 41,
    "currentStatus": {
      "agentStatus": "ringOnNoAnswer"
    }
  },
  {
    "type": "agent",
    "metrics": {
      "instantMessage": {
        "takenCount": 0
      }
    },
    "name": "Commander William T. Riker",
    "id": 37,
    "currentStatus": {
      "agentStatus": "unavailable"
    }
  }
]

• The Multiple Agents By Id response is a List of Realtime Data Response.

Response – 200 OK

A 200 – OK success response means the request successfully gathered Agents’ metrics.

Failed Responses

If there is an error on the API server while getting a response, return a 500 – internal server error response

Additional Authorization

1. If the requesting Agent Id is not authorized for the specified entity Id(s), return a 401 – Unauthorized.

2. If an entity Id is not specified in the query string parameters, return a 401 – Unauthorized.

Aggregate Agent Metrics

• The Aggregate Agent Metrics method retrieves one aggregated (summed up) set of Agent metrics for a list of Agents, Teams, BUs or Groups

• The Aggregate Agent Metrics method is accessible off the Connect Web API Root URL at: /webapi/api/v2/metrics/agents/aggregateBy

• This API supports both GET and POST verbs for this method.

Request – HTTP GET

• Requires Authorization, Accept and Accept-Encoding and Content-Type headers.

• Url parameters: Refer to Common Query String Parameters

GET /webapi/api/v2/agents/aggregateBy/agentIds=41,37 HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc
Accept: */*
Accept-Encoding: gzip
Content-Type: application/json

The response would look like this:

{
  "entityIds": [
    41,
    37
  ],
  "type": "agent",
  "metrics": {
	"audio": {
	   "ronaCount": 2,
	   "answeredCount": 5,
	   …
	   …
}
   }
}

Request – HTTP POST

• The POST request lets the consumer use the POST body that can be used to filter which metrics, session, and status properties are included in the response.

• Requires Authorization, Accept and Accept-Encoding and Content-Type headers.

• Url parameters: Refer to Common Query String Parameters

A POST request to get TakenCount metrics for Agent Id 41 would look like:

POST /webapi/api/v2/agents/aggregateBy?agentIds=41,37 HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc
Accept: */*
Accept-Encoding: gzip
Content-Type: application/json
{
	"metricProperties": ["ronaCount"]
}

The response would look like this:

{
  "entityIds": [
    41,
    37
  ],
  "type": "agent",
  "metrics": {
    "audio": {
      "ronaCount": 0
    },
    "instantMessage": {
      "ronaCount": 0
    },
    "message": {
      "ronaCount": 0
    }
  }
}

• The Aggregate Agent Metrics response is specified in detail at: Aggregate Metric Data Response

Response – 200 OK

A 200 – OK success response means the request was successfully processed and returned a response with valid metrics.

Failed Responses

1. If there is an error on the API server while getting a response, return a 500 – internal server error response

Additional Authorization

1. If the requesting Agent Id is not authorized for the specified entity Id(s), return a 401 – Unauthorized.

2. If an entity Id is not specified in the query string parameters, return a 401 – Unauthorized.

Group Agent Metrics

• The Group Agents Metrics method retrieves multiple aggregated (summed up) sets of Agent metrics for lists of Agents by team, group or business unit.

• The Group Agents Metrics method is accessible off the Connect Web API Root URL at: /webapi/api/v2/metrics/agents/groupBy

• This API supports both GET and POST verbs for this method.

• If more than one MBU is specified in the query string parameters, the prioritization is in this order: team, group, then business unit

Request – HTTP GET

• Requires Authorization, Accept and Accept-Encoding and Content-Type headers.

• Url parameters: Refer to Common Query String Parameters

A GET request to get metrics, session, and status information for Agent Ids would look like:

GET /webapi/api/v2/agents/groupBy/groupIds=2,3,5
Host: connect.customer.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc
Accept: */*
Accept-Encoding: gzip
Content-Type: application/json

The response would look like this:

[
  {
    "groupType": "group",
    "groupId": 2,
    "entityIds": [],
    "type": "agent"
  },
  {
    "groupType": "group",
    "groupId": 3,
    "entityIds": [],
    "type": "agent"
  },
  {
    "groupType": "group",
    "groupId": 5,
    "entityIds": [
      49,
      52
    ],
    "type": "agent",
    "metrics": {
      "audio": {
        "ronaCount": 1,
        "answeredCount": 1,
	  …        
      },
      "message": {
        "ronaCount": 0,
        "currentlyActiveCount": 1,
	   …
      },
      "agnostic": {
        "availableTime": {
          "total": 13205103,
          "average": 6602551.5,
          "count": 2,
	    …
        },
        "directInboundTime": {
          "total": 0,
          "average": 0,
          "count": 0
        },
      }
    },
    "sessions": {
      "message": {
        "sessions": [
          {
            "sessionId": 72331,
            "sessionType": "queued",
…
          }
        ]
      }
    }
  }
]

Request – HTTP POST

• The POST request lets the consumer specify in the POST body which metrics, session, and status properties are included in the response.

• Requires Authorization, Accept and Accept-Encoding and Content-Type headers.

• Url parameters: Refer to Common Query String Parameters

A POST request to get particular metrics for Agent Id 41 would look like:

POST /webapi/api/v2/agents/teamIds=2,3 HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc
Accept: */*
Accept-Encoding: gzip
Content-Type: application/json
{
	"metricProperties": ["ronaCount"],
}

The response would look like this:

[
  {
    "groupType": "team",
    "groupId": 2,
    "entityIds": [1, 2, 3, 26, 30, 39, 43, 48, 50, 57],
    "type": "agent"
  },
  {
    "groupType": "team",
    "groupId": 3,
    "entityIds": [5, 31, 32, 33, 34, 36, 40, 41, 42, 44, 45, 56],
    "type": "agent",
    "metrics": {
      "instantMessage": {
        "ronaCount": 3
      }
    }
  }
]

• The Group Agents Metrics response is specified in detail at: Group Metric Data Response

Response – 200 OK

A 200 – OK success response means the request successfully gathered Agents’ metrics and other real time data.

Failed Responses

1. If there is an error on the API server while getting a response, return a 500 – internal server error response

Additional Authorization

1. If the requesting Agent Id is not authorized for the specified entity Id(s), return a 401 – Unauthorized.

2. If an entity Id is not specified in the query string parameters, return a 401 – Unauthorized.

Resource

The Resource endpoint provides an API consumer the ability to get localization strings for the specified language.

Resource by Locale Key

• The Get Localized Strings method returns a dictionary of the localization keys and translated values.

• The Get Localized Strings method is accessible off the Connect Web API Root URL at: /webapi/api/v2/resources/dashboard/localization/{locale}

Request – HTTP GET

• Requires Authorization, Accept and Accept-Encoding headers.

• Query string parameters:

o Locale - the locale specifies which language; for example, “en-us” or “fr-fr." This locale maps to the Locale.LocaleKey column

GET /webapi/api/v1.0/resources/dashboard/localization/en-us HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eEEiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmludGVybmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQj1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQyOTQxMzcsIm5iZiI6MTQ3NDI5MzUzN30.gy48Uf5xNRWKUt74qrSXuFCDreaWhyfnCWa4xiaI
Accept: application/json
Accept-Encoding: gzip

Response – 200 OK

A dictionary of the localization keys and their translated values based on the locale key given

{
  "abandonedAfterSLACount": "Abandoned After SLA Count",
  "abandonedAfterSLACountDescription": "Abandoned After SLA Count",
  "abandonedAfterSLACountShort": "Abandoned After SLA Count Short",
  "abandonedBeforeSLACount": "Abandoned Before SLA Count",
  "abandonedBeforeSLACountDescription": "Abandoned Before SLA Count",
  "abandonedBeforeSLACountShort": "Abandoned Before SLA Count Short",
  "abandonedCount": "Abandoned Count"
..
..
}

Failed Responses

1. If there is an error on the API server while getting a response, the Resource endpoint should return a 500 – internal server error response.

2. If the localization strings could not be found using the query string parameter, return a 404 – not found error response.

Specific Server

The Specific Server endpoint gives the API consumer the server FQDN.

Base Specific Server

• The base specific server method returns the server FQDN as a string.

• The base specific server method is accessible off the Connect Web API Root URL at: /webapi/api/v2/metrics/specificserver

Request – HTTP GET

Requires Authorization, Accept, and Accept-Encoding headers.

GET /webapi/api/v2/metrics/specificserver HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eEEiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmludGVybmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQj1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQyOTQxMzcsIm5iZiI6MTQ3NDI5MzUzN30.gy48Uf5xNRWKUt74qrSXuFCDreaWhyfnCWa4xiaI
Accept: application/json
Accept-Encoding: gzip

Response – 200 OK

The server FQDN as a string

"https://connect.customer.com/webapi"

Failed Responses

If there is an error on the API server while getting a response, the Specific Server endpoint should return a 500 – internal server error response.

Subscription

The Subscription endpoint is where an API consumer can add, update, and delete subscriptions to MBU gold data.

Selecting Metrics

To receive updates for gold data, specify which particular metric events to subscribe to in the request body. Each metric is categorized under Agent Metric Types or Queue Metric Types depending on the whether it’s a request to subscribe to Agent(s) or Queue(s).

Processing Data

When the API receives gold diffs from the Metric Service, the Subscription Engine will handle processing the gold data and sending updates to subscribers via Signal R.

Request Headers

Below are the records for each query string parameter’s name, description, sample values, and the supporting methods detailed in the table below.

Query String Parameter	Description	Sample Value	Supporting Methods
modalities	Which modalities to subscribe to. Default value is all modalities.	audio, message, instantMessage	All methods except Subscribe To Alerts and Delete Subscription.
includeBreakdowns	Whether or not to include breakdowns of Agent metrics by Queue in the subscription. Default value is false.	true, false	All methods except Subscribe To Alerts and Delete Subscription.
includeStatusHistory	Whether or not to include the last 24 hours of Agent statuses in the subscription. Default value is false.	true, false	Only Subscribe To Agents and Update Subscription.

Subscribe to Agents

• The Subscribe to Agents method lets you subscribe to a single Agent or multiple Agent metrics.

• Agent metrics can be subscribed to for one to many Agents, based on the provided agent ids, a team, group or business unit.

• The Subscribe to Agents method is accessible off the Connect Web API Root URL at: /webapi/api/v2/subscriptions/agents

Request – HTTP POST

• Requires Authorization, Accept and Accept-Encoding and Content-Type headers.

• Url parameters: Refer to Request Headers

A request to add a subscription to metrics for Agent Ids 5 and 7 for only AV calls and include status history would look like:

POST /webapi/api/v2/subscriptions/agents?agentIds=5,7&modalities=2&includeStatusHistory=true HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmlbmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQjFBMC1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQzMDczMTAsIm5iZiI6MTQ3NDMwNjcxMH0.iLSb78NAoam-SU6YOHVBy4OVOQWkP6KGsB7Ak
Accept: */*
Accept-Encoding: gzip
Content-Type: application/json
{
	"connectionId":"88cfebc8-e9f5-47a5-bfea-01b949ff9247",
	"sessionPropertyType": ["queueId", "customerName"],
	"statusProperties": ["agentStatus","reasonCodeName"],
	"metricProperties”: ["AnsweredCount"]
}

• The Subscribe to Agent request is specified in detail at: Agent Subscription Request

Response – 200 OK

A 200 – OK success response means the subscription was successfully created.

Failed Responses

1. If there is an error on the API server while getting a response, return a 500 – internal server error response

2. If the subscription Id was not found, return a 404 – Not Found

Additional Authorization

1. If the Subscription is not accessible, return a 401 – Unauthorized.

2. If an entity Id is not specified in the query string parameters, return a 401 – Unauthorized.

Subscribe to Agent Aggregation

• The Subscribe to Agent Aggregation method lets you subscribe to Agent metrics that are aggregated (summed up) by the provided request parameters

• Agent metrics can be aggregated by a list on agent ids, a team, group or business unit.

• The Subscribe to Agents method is accessible off the Connect Web API Root URL at: /webapi/api/v2/subscriptions/agents/aggregateBy

Request – HTTP POST

• Requires Authorization, Accept and Accept-Encoding and Content-Type headers.

• Url parameters: Refer to Request Headers

A request to add a subscription to metrics for Agent Ids 5 and 7 for only AV would look like:

POST /webapi/api/v2/subscriptions/agents/aggregateBy?agentIds=5,7&modalities=audio HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmlbmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQjFBMC1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQzMDczMTAsIm5iZiI6MTQ3NDMwNjcxMH0.iLSb78NAoam-SU6YOHVBy4OVOQWkP6KGsB7Ak
Accept: */*
Accept-Encoding: gzip
Content-Type: application/json
{
	"connectionId":"88cfebc8-e9f5-47a5-bfea-01b949ff9247",
	"sessionPropertyType": ["queueId", "customerName"],
	"statusProperties": ["agentStatus","reasonCodeName"],
"metricProperties”: ["AnsweredCount"]
}

• The Update Agent Status request is specified in detail at: Agent Subscription Request

Failed Responses

1. If there is an error on the API server while getting a response, return a 500 – internal server error response

Additional Authorization

1. If the API consumer does not have MBU permissions to see the Agent Id, return a 401 – Unauthorized

2. If an entity Id is not specified in the query string parameters, return a 401 – Unauthorized.

Subscribe to Agent Grouping

• The Subscribe to Agent Grouping method lets you subscribe to a Agent metrics grouped by the provided request parameters.

• Agent metrics can be grouped by team, group or business unit.

• The Subscribe to Agent Grouping method is accessible off the Connect Web API Root URL at: /webapi/api/v2/subscriptions/agents/groupBy

Request – HTTP POST

• Requires Authorization, Accept and Accept-Encoding and Content-Type headers.

• Url parameters: Refer to Request Headers

A request to add a subscription to AV metrics Currently Active Counts for Agents grouped by Group Ids 5 and 7 would look like:

POST /webapi/api/v2/subscriptions/agents/groupBy?groupIds=5,7&modalities=audio&teamIds=2 HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmlbmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQjFBMC1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQzMDczMTAsIm5iZiI6MTQ3NDMwNjcxMH0.iLSb78NAoam-SU6YOHVBy4OVOQWkP6KGsB7Ak
Accept: */*
Accept-Encoding: gzip
Content-Type: application/json
{
	"connectionId":"88cfebc8-e9f5-47a5-bfea-01b949ff9247",
	"sessionPropertyType": ["queueId", "customerName"],
	"statusProperties": ["agentStatus","reasonCodeName"],
"metricProperties”: ["AnsweredCount"]
}

• The Update Agent Status request is specified in detail at: Agent Subscription Request

Failed Responses

If there is an error on the API server while getting a response, return a 500 – internal server error response

Additional Authorization

1. If the API consumer does not have MBU permissions to see the Agent Id, return a 401 - Unauthorized

2. If an entity Id is not specified in the query string parameters, return a 401 – Unauthorized.

Subscribe to Queues

• The Subscribe to Queues method lets you subscribe to a single Queue or multiple Queue metrics.

• Queue metrics can be subscribed to for one to many Queues, based on the provided queue ids, a team, group or business unit.

• The Subscribe to Queues method is accessible off the Connect Web API Root URL at: /webapi/api/v2/subscriptions/queues

Request – HTTP POST

• Requires Authorization, Accept and Accept-Encoding and Content-Type headers.

• Url parameters: Refer to Request Headers

A request to add a subscription for queue Ids 1 and 2 for queues for only AV calls would look like:

POST /webapi/api/v2/subscriptions/queues?queueIds=1,2&modalities=audio HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmlbmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQjFBMC1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQzMDczMTAsIm5iZiI6MTQ3NDMwNjcxMH0.iLSb78NAoam-SU6YOHVBy4OVOQWkP6KGsB7Ak
Accept: */*
Accept-Encoding: gzip
Content-Type: application/json
{
	"connectionId":"88cfebc8-e9f5-47a5-bfea-01b949ff9247",
	"sessionProperties": ["queueId", "customerName"],
	"metricProperties”: ["QueuedCount"]
}

• The Update Agent Status request is specified in detail at: Queue Subscription Request

Failed Responses

If there is an error on the API server while getting a response, return a 500 – internal server error response

Additional Authorization

1. If the API consumer does not have MBU permissions to see the Queue Id(s), return a 401 – Unauthorized

2. If an entity Id is not specified in the query string parameters, return a 401 – Unauthorized.

Subscribe to Queue Aggregation

• The Subscribe to Queue Aggregation method lets you subscribe to Queue metrics that are aggregated (summed up) by the provided request parameters.

• Queue metrics can be aggregated by a list of queueIds, a team, group or business unit.

• The Subscribe to Queue Aggregation method is accessible off the Connect Web API Root URL at:

/webapi/api/v2/subscriptions/queues/aggregateBy

Request – HTTP POST

• Requires Authorization, Accept and Accept-Encoding and Content-Type headers.

• Url parameters: Refer to Request Headers

A request to add a subscription to metrics for queues for AV calls would look like:

POST /webapi/api/v2/subscriptions/queues/aggregateBy?modalities=audio HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmlbmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQjFBMC1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQzMDczMTAsIm5iZiI6MTQ3NDMwNjcxMH0.iLSb78NAoam-SU6YOHVBy4OVOQWkP6KGsB7Ak
Accept: */*
Accept-Encoding: gzip
Content-Type: application/json
{
	"connectionId":"88cfebc8-e9f5-47a5-bfea-01b949ff9247",
	"metricProperties":["QueuedCount"]
}

• The Update Agent Status request is specified in detail at: Queue Subscription Request

Failed Responses

If there is an error on the API server while getting a response, return a 500 – internal server error response

Additional Authorization

If the API consumer does not have MBU permissions to see the Agent Id, return a 401 - Unauthorized

Subscribe to Queue Grouping

• The Subscribe to Queue Grouping method lets you subscribe to Queue metrics grouped by the provided request parameters.

• Queues can be grouped by team, group or business unit.

• The Subscribe to Queue Grouping method is accessible off the Connect Web API Root URL at: /webapi/api/v2/subscriptions/queues/groupBy

Request – HTTP POST

• Requires Authorization, Accept and Accept-Encoding and Content-Type headers.

• Url parameters:

o modalities (optional) - which modality Ids to subscribe to. Default value is all modalities.

o includeBreakdowns (optional) - whether or not to include breakdowns of Agent metrics by Queue in the subscription. Default value is false.

A request to add a subscription to metrics for queueId 5 and groupId 1 would look like:

POST /webapi/api/v2/subscriptions/queues/groupBy?queueIds=5&groupIds=1 HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmlbmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQjFBMC1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQzMDczMTAsIm5iZiI6MTQ3NDMwNjcxMH0.iLSb78NAoam-SU6YOHVBy4OVOQWkP6KGsB7Ak
Accept: */*
Accept-Encoding: gzip
Content-Type: application/json
{
	"connectionId":"88cfebc8-e9f5-47a5-bfea-01b949ff9247",
	"metricProperties":["queuedCount"]
}

• The Update Agent Status request is specified in detail at: Queue Subscription Request

Failed Responses

If there is an error on the API server while getting a response, return a 500 – internal server error response

Additional Authorization

If the API consumer does not have MBU permissions to see the Agent Id, return a 401 - Unauthorized

Subscribe to Alerts

• The Subscribe to Alerts method lets you subscribe to Connect alerts.

• The Subscribe to Alerts method is accessible off the Connect Web API Root URL at: /webapi/api/v2/subscriptions/alerts

Request – HTTP POST

• Requires Authorization, Accept and Accept-Encoding and Content-Type headers.

• POST body

o ConnectionId - SignalR connection id

A request to add a subscription to alerts configured in Connect would look like:

            POST /webapi/api/v2/subscriptions/alerts HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmlbmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQjFBMC1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQzMDczMTAsIm5iZiI6MTQ3NDMwNjcxMH0.iLSb78NAoam-SU6YOHVBy4OVOQWkP6KGsB7Ak
Accept: */*
Accept-Encoding: gzip
Content-Type: application/json
{
	"connectionId":"88cfebc8-e9f5-47a5-bfea-01b949ff9247"	
}

        

• The Subscribe to Alerts request is specified in detail at: Alert Subscription Request

Failed Responses

If there is an error on the API server while getting a response, return a 500 – internal server error response

Additional Authorization

If the API consumer does not have MBU permissions to see the Agent Id, return a 401 - Unauthorized

Update Subscription

• The Update Subscription method lets you update multiple subscription types from a single endpoint

• For more details on the parameters and options see the individual create subscription methods. Any options from those methods are valid in this method as well.

• The Update Subscription method is accessible off the Connect Web API Root URL at: /webapi/api/v2/subscriptions/{subscriptionId}

Request – HTTP POST

• Requires Authorization, Accept and Accept-Encoding and Content-Type headers.

• Url parameters: Refer to Request Headers

A request to update subscription Id “abc123” to receive AnsweredCount metrics for agentId 5 and 7 looks like this:

POST /webapi/api/v2/subscriptions/abc123/agentId=5,7 HTTP/1.1 Host: connect.customer.com Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmlbmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQjFBMC1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQzMDczMTAsIm5iZiI6MTQ3NDMwNjcxMH0.iLSb78NAoam-SU6YOHVBy4OVOQWkP6KGsB7Ak Accept: */* Accept-Encoding: gzip Content-Type: application/json { "connectionId":"100" "metricProperties”: ["AnsweredCount"] }

Response – 204 NO CONTENT

A 204 – No Content success response means updating the Subscription request went through successfully.

Failed Responses

1. If there is an error on the API server while getting a response, return a 500 – internal server error response

2. If the subscription Id was not found, return a 404 – Not Found

Additional Authorization

If the Subscription is not accessible, return a 401 – Unauthorized.

Delete Subscription

• The Delete Subscription method lets you delete a subscription.

• The Delete Subscription method is accessible off the Connect Web API Root URL at: /webapi/api/v2/subscriptions/{subscriptionId}

Request – HTTP DELETE

• Requires Authorization, Accept and Accept-Encoding and Content-Type headers.

• Url parameters:

o subscriptionId - the subscription Id to delete

A request to delete subscription Id “abc123” would look like:

DELETE /webapi/api/v2/subscriptions/abc123
Host: connect.customer.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmlbmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQjFBMC1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQzMDczMTAsIm5iZiI6MTQ3NDMwNjcxMH0.iLSb78NAoam-SU6YOHVBy4OVOQWkP6KGsB7Ak
Accept: */*
Accept-Encoding: gzip
Content-Type: application/json
{
	"connectionId":"bc494070-b64c-43a6-8b92-c7dbeac263d1"
}

Response – 204 NO CONTENT

A 204 – No Content success response means deleting the Subscription request went through successfully.

Failed Responses

If there is an error on the API server while getting a response, return a 500 – internal server error response

Additional Authorization

If the Subscription is not accessible, return a 401 – Unauthorized.

Batch Request

A Batch request let’s a consumer send multiple requests within one request.

Sending Multiple Requests

• The batch request returns responses from each request specified in the POST body.

• The batch request is accessible at the Connect Web API Root URL: /webapi/api/v2/

Request – HTTP POST

• Requires Authorization, Accept and Accept-Encoding and Content-Type headers.

• Url parameters: none

• POST body - an array of JSON objects containing each request’s response information.

• method is the HTTP verb used for the method.
• relativeUrl is the route suffix along with any query string parameters.
• body is any request body values the consumer wants to send with the request.

POST /webapi/api/v2/ HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eEEiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmludGVybmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQj1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQyOTQxMzcsIm5iZiI6MTQ3NDI5MzUzN30.gy48Uf5xNRWKUt74qrSXuFCDreaWhyfnCWa4xiaI
Accept: application/json
Accept-Encoding: gzip
[
	{
		"method":"POST",
		"relativeUrl":"../v2/subscriptions/agents/?modalities=2&agentIds=5"
	},
	{
		"method":"GET",
		"relativeUrl":"../v2/profile"
		
	}
]

The Batch request is specified in detail at: Batch Request

Response – 200 OK

The batch request returns an array of objects. Each object contains the response status code and body for each request inside the batch request.

[
  {
    "code": 500,
    "body": {
      "message": "Failed to subscribe to agents"
    }
  },
  {
    "code": 200,
    "body": {
      "type": "agent",
      "id": 41,
      "teamId": 3,
      "name": "Rob T.",
      "emailAddress": "rtorres@cc",
      "localeKey": "en-us",
      "enabledModalities": [
        "audio",
        "instantMessage",
        "message"
      ],
      "isDirectProxyEnabled": true,
      "isFederatedDeployment": false,
      "canMarkSelfAsSuspended": true,
      "useSilverlightAgentConsole": true,
      "hideRecordButton": false,
      "attendantSipUri": "sip:Connect.40.Attendant@ccdev2015.internal",
      "domain": "ccdev2015.internal",
      "hideRecordingButton": false,
      "discoveryXFrameUrlOverride": "",
      "discoveryUserUrlOverride": ""
    }
  }
]

Client Logs

The Client Logs endpoint allows API consumers to send log requests.

Write Log from Client

• The Write Log from Client method lets you send log requests for specific log levels and components.

• The request is accessible at the Connect Web API Root URL: /webapi/api/v2/clientlogs/

Request – HTTP POST

• Requires Authorization, Accept and Accept-Encoding and Content-Type headers.

• Url parameters - none

• POST body:

• SessionId
• Component
• LogLevel
• Message

A request to log a test message at VERBOSE would look like:

POST /webapi/api/v2/clientlogs HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmlbmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQjFBMC1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQzMDczMTAsIm5iZiI6MTQ3NDMwNjcxMH0.iLSb78NAoam-SU6YOHVBy4OVOQWkP6KGsB7Ak
Accept: */*
Accept-Encoding: gzip
Content-Type: application/json
{ 
	“message”: “test”,
	“logLevel”: “verbose”
}

A complex request would look like:

POST /webapi/api/v2/clientlogs HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmlbmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQjFBMC1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQzMDczMTAsIm5iZiI6MTQ3NDMwNjcxMH0.iLSb78NAoam-SU6YOHVBy4OVOQWkP6KGsB7Ak
Accept: */*
Accept-Encoding: gzip
Content-Type: application/json
{ 
	“message”: “test”,
	“logLevel”: “info”,
	“sessionId”: 2,
	“component”: “auth”
}

The Write Log from Client request is specified in detail at: Write Log from Client Request

Response – 200 OK

A 200 – OK success response means the message was written at the specified component (or Other) and at the specified log level or debug.

Failed Responses

1. If there is an error on the API server while getting a response, return a 500 – internal server error response

2. If the request body is null or message is null or empty, return a 400 – bad request

Search

The search endpoint allows API consumers to search for agents and queues.

SEARCH

• The Search method lets you search for agents and queues based on a query.

• The request is accessible at the Connect Web API Root URL: /webapi/api/v2/search/{query}

Request – HTTP GET

• Requires Authorization, Accept and Accept-Encoding and Content-Type headers.

• Url parameters:

o Query – string to match to agents or queues based on presence in the following fields:

• First name
• Last name
• Email address
• Login name
• Public name
• Phone number
• Sip address
• Queue name

A request to search for test would look like:

GET /webapi/api/v2/search/test HTTP/1.1
Host: connect.customer.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25uZWN0X2FnZW50X2lkIjoiNSIsImlzcyI6Imh0dHBzOi8vNDAuY2NkZXYyMDE1LmlbmFsL3dlYmF1dGgvdG9rZW4iLCJhdWQiOiIwNDQ0QzM5Mi0zODQ1LTRBQzAtQjFBMC1ENjM3MDYxODBCQTkiLCJleHAiOjE0NzQzMDczMTAsIm5iZiI6MTQ3NDMwNjcxMH0.iLSb78NAoam-SU6YOHVBy4OVOQWkP6KGsB7Ak
Accept: */*
Accept-Encoding: gzip

Response – 200 OK

A 200 – OK success response means query ran successfully.

For Example:

{
  agentsFound: [ 
    {
      “agentId”: 53,
      “firstName”: “Test”,
      “lastName”: “User”,
      “publicName”: “Test”,
      “loginName”: “test.user@domain.com”,
      “sipAddress”: “sip:test.user@domain.com”,
      “emailAddress”: “test.user@domain.com”,
      “phoneNumber”: NOTSET,
      “status”: 4,
      “callsAnswered”: 0,
      “ronas”: 0,
      “type”: “agentSearch”,
      “id”: 53
    },
    …
  ],
  queuesFound: [
    {
      “queueId”: 7,
      “queueName”: “Test’s Queue”,
      “isOpen”: true,
      “agentsOnline”: 0,
      “agentsAvailable”: 0,
      “estimatedWaitTime”: 120,
      “callsToday”: 0,
      “type”: “queueSearch”,
      “id”: 7
    },
    …
  ],
  message: “Query 'sip' found 3 agent(s) and 2 queue(s).”
}

• The Search response is specified in detail at: Search Response

Failed Responses

If the query is null or empty, return a 400 – bad request

Request & Response Dictionary

This section specifies the API request and response objects for each method in detail.

List Response

List Response is a collection wrapper for response objects that need to return a list of objects and count.

Field Name	Data Type	Description	Sample Value	Source
items	array	Collection of objects
count	integer	The count of items	10

Common Query String Parameters

The following chart provides details on common query string parameters for different endpoints. Each parameter, it’s description, sample values, and the supporting methods are detailed in the chart below.

Query String Parameter	Description	Sample Value	Supporting Methods
modalities	Which modalities to subscribe to. Default value is all modalities.	audio, message, instantMessage	Supported by all methods except Subscribe To Agents and Delete Subscription.
includeBreakdowns	Whether or not to include breakdowns of Agent metrics by Queue in the subscription. Default value is False.	true, false	Supported by all Subscription methods except and Delete Subscription.Supported by all Agent Metrics methods.
includeStatusHistory	Whether or not to include the last 24 hours of Agent statuses in the subscription. Default value is false.	true, false	Subscribe To Agents, Update Subscription, Agent By Id, Multiple Agents By Id

Info

Base Info Response

Field Name	Data Type	Description	Sample Value	Source
connectVersion	string	The version of Connect this instance is running	“4.0.9”	DbSchemaHistory.Version
We take the Version from the row with the most recent AppliedAt timestamp
apiVersions	array of API Version objects
The versions of the API this instance supports		Hard-coded in the DbApiInfoRepository in the Web API project
signalRTransports	array of string	The SignalR transports this instance supports	"webSockets", "serverSentEvents", "longPolling"

API Version

Field Name	Data Type	Description	Sample Value	Source
version	string	A version of the API that this instance supports	“1.0”
relativeUrl	string	The relative URL from the API root URL to reach this API version at	“/v1.0”

Profile

Hidden Queue

Field Name	Data Type	Description	Sample Value	Source
queueId	integer	The id of the hidden queue	-1, 0, 9999	-2 Direct Outbound
-1 Direct Inbound
0 Rollup Queue
9999 Direct Calls
queueName	string	The name of the hidden queue	Brad’s Queue, Direct Calls	Queue.PublicName

Base Profile Response

Field Name	Data Type	Description	Sample Value	Source
type	string	The “type” of object this is.
A legacy field from the v1 API	“agent”
This is the only valid value	Hard-coded to always be “agent” for legacy v1.0 API reasons
id	integer	The Agent’s Id	10	Agent.AgentId
teamId	integer	The Id of the Agent’s Team	1	MbuAgent.Team.Id
Gold Copy (ConnectGoldCopyAuthorization)
If the Agent is not assigned to a Team, -1 is returned for teamId
name	string	The Agent’s Public Name	“Jean Luc Picard”	Agent.PublicName
emailAddress	string	The Agent’s email address	“jpicard@starfleet.com”	Agent.Email
localeKey	string	The key for the preferred localization locale for this Agent
In 4.0 API v1 /me this field was called Locale	“en-us”	Agent.LocaleId -> Locale.LocaleKey
enabledModalities	array of strings	The modalities that are enabled in the Portal	[“audio”, “instantMessage”]
“audio”, “instantMessage” and “message” are the only valid values in this array	Config.SettingName =
“IsVoiceEnabled” -> “audio”
Config.SettingName =
“IsIMEnabled” -> “instantMessage”
Config.SettingName =
“IsMessageEnabled” -> “message”
isDirectProxyEnabled	bool	Are this Agent’s direct calls proxied by Connect	false	Agent.ProxyDirectCalls
isFederatedDeployment	bool	Are Agents in a federated domain, rather than the Front End's domain	false	Config.SettingName = “IsFederatedDeployment”
canMarkSelfAsSuspended	bool	Is the Agent able to mark themself as suspended	false	MbuAgent.CanMarkSelfAsSuspended
Gold Copy (ConnectGoldCopyAuthorization)
useSilverlightAgentConsole	bool	Is the Agent required to use the legacy Silverlight Agent Console	false	Config.SettingName = “ACS_ToggleSilverlightAgentConsole”
In 4.0 this value is always true
hideRecordButton	bool	Is recording disabled globally for all Agents	false	Config.SettingName = “ACS_HideRecordButton”
In 4.0 this is always false
attendantSipUri	string	Returns a random portal attendant endpoint that is configured. In high volume environments, SfB could not handle conference management from a single endpoint which is why the portal was modified to be able to use multiple attendants.	“sip:Connect.41.Attendant@ccdev2015.internal”	Config.SettingName = “AttendantSipUri”
*Attendant URIs will be pipe delaminated if using multiple*
Domain	string	The AD domain of the Agent	“ccdev2015.internal”	Config.SettingName = “ImpersonatedContactDomain”
hideRecordingButton	string	Is recording disabled for this Agent	false	Agent.HideRecordingButton
discoveryXFrameUrlOverride	string	Custom configuration for Skype Web SDK sign-in	“”	Config.SettingName =
“ACS_Autodiscover_User_URL”
In 4.0 this is always “”
discoveryUserUrlOverride	string	Custom configuration for Skype Web SDK sign-in	“”	Config.SettingName =
“ACS_Autodiscover_XFrame_URL”
In 4.0 this is always “”
agentGRUU	string	GRUU for the Agent from Skype Web SDK	sip:user@domain.com;opaque=user:epid:2Siiti_4p1O4UkVD79Vt9QAA;gruu	Agent.SkypeWebApiGruu
proxyDirectCalls	bool	Determines if direct calls are serviced and tracked by Connect for the Agent.	false	Agent.ProxyDirectCalls
hiddenQueues	List Response of Hidden Queue objects	List of queueId and queueNames that are hidden by the agent		AgentQueueVisibility

Get MBU Structure Response

The response object is made up of arrays of agent, queue, team, group, and business unit response objects which in turn are specializations of a MBU Entity Response object.

MBU Entity Response

Field Name	Data Type	Description	Sample Value	Notes
Type	string	What type of entity this is	Agent, Queue, Team, Group, Business Unti
Id	integer	The Id of the entity	12
Name	string	The name of the entity	“Test”:

Agent Response

Field Name	Data Type	Description	Sample Value	Notes
teamId	integer	Team Id for this Agent	12
canSilentJoin	boolean	Can this Agent silent join sessions	true, false
canWhisperJoin	boolean	Can this Agent whisper join sessions	true, false
canRecord	boolean	Can this Agent record sessions	true, false

Queue Response

Field Name	Data Type	Description	Sample Value	Notes
businessUnitId	integer	What Business Unit this Queue belongs to	12
teamIds	array of integer	The Teams that are associated with this Queue	1, 2, 3	If empty it will not be included in the response

Team Response

Field Name	Data Type	Description	Sample Value	Notes
businessUnitId	integer	What Business Unit this Team belongs to	12
groupId	array of integer	What Groups contain this Team	1, 2, 3	If empty it will not be included in the response
agentIds	array of integer	What Agents are on this Team	1, 2, 3	If empty it will not be included in the response
queueIds	array of integer	The Queues that are associated with this Team	1, 2, 3	If empty it will not be included in the response

Group Response

Field Name	Data Type	Description	Sample Value	Notes
teamIds	array of integer	The Teams in this Group	1, 2, 3	If empty it will not be included in the response

Business Unit Response

Field Name	Data Type	Description	Sample Value	Notes
teamIds	array of integer	The Teams in this Business Unit	1, 2, 3	If empty it will not be included in the response
queueIds	array of integer	The Queues in this Business Unti	1, 2, 3	If empty it will not be included in the response

Response

Field Name	Data Type	Description	Sample Value	Notes
Agents	array of Agent Response			If empty it will not be included in the response
Queues	array of Queue Response			If empty it will not be included in the response
Teams	array of Team Response			If empty it will not be included in the response
Groups	array of Group Response			If empty it will not be included in the response
businessUnits	array of Business Unit Response			If empty it will not be included in the response

Get Dashboard Settings Response

Field Name	Data Type	Description	Sample Value	Notes
templateId	integer	The id of the Dashboard template	1
templateRevision	integer	The revision of the Dashboard template	1
definition	object	The JSON document that defines the dashboard template
agentConsoleTemplateId	integer		0
agentConsoleTemplateRevision	integer		0
agentConsoleDefinition	object
attendantEndpoint	string

Sessions

Sessions by Agent Response

Field Name	Data Type	Description	Sample Value	Source
items	array of Session Base objects	One or many Sessions the Agent is primary Agent on		Session where Session.AgentId is equal to the requested Agent Id and the Session.SessionStatus is NOT Completed, Transferred, CompletedAfterHours or Abandoned
count	integer	How many Sessions are in the items array	1	Count of items array

Session by ID Response

This response includes all the Properties of the Model Session plus the properties below.

Field Name	Data Type	Description	Sample Value	Source
customerHistory	List Response of Session Base objects	Past customer session records	"items": [ { "agentId": 41, "agentName": "Rob T.", "callFlowId": 1, "callFlowName": "Starter", "customerId": "Captain Jean-Luc Picard", "customerName": "Captain Jean-Luc Picard", … } ], "count": 1
aftercallConfig	Aftercall Config			Can be null
holdTimerThreshold	integer
imPropts	List Response of IM Prompt objects			Can be null
ivrData	List Response of IVR Data objects			Can be null
callDispositions	List Response of Call Disposition objects			Can be null
transcript	Transcript Message objects			Can be null
extraItems	List Response of Extra Item objects			Can be null
sessionEventHistory	List Response of Session Event History objects			Can be null
sessionMessages	List Response of Session Message objects			Can be null

Model Session

The Model Session includes all the Properties of the Session Base plus the properties below.

Field Name	Data Type	Description	Sample Value	Source
isRecording	bool	Whether the Session is being recorded	false	Session.IsRecording 4.0 – Always false
canBeRecorded	bool	Can the Session be recorded	false	Session.CanBeRecorded 4.0 – Always false
isSilentJoined	bool	Whether anyone is Silent Joined to the Session	false	If (Session.AgentSession where AgentSessionTypeId = SilentJoin and EndTime is null) -> true Else -> false 4.0 – Always false
isWhisperJoined	bool	Whether anyone is Whisper Joined to the Session	false	If (Session.AgentSession where AgentSessionTypeId = WhisperJoin and EndTime is null) -> true Else -> false 4.0 – Always false
sessionStatus	string	The status of the Session	“New” Valid values are: “New” “Queued” “Active” “Completed” “Connected” “Terminating” “Abandoned” “CallingCustomer” “Transferred” “AfterCall” “NotifyingAgent” “CompletedAfterHours” “DirectInboundDial” “DirectOutboundDial” “ReEnqueued” “ActiveImOnly”	Session.SessionStatusId -> parse string enum value
queuedMs	integer	How long the Session was Queued in milliseconds	30000	If Session.SessionStatusId = Queued -> (UtcNow – Session.StartTime) Else -> 0 Only has a non-zero value if the Session is currently Queued
activeMs	Integer	How long the Session was Active in milliseconds	550000	Session is not active with any Agent -> 0 Session has completed -> EndTimeStamp – ActiveTimeStamp Session is currently active -> Utc Now - ActiveTimeStamp
canBeSilentJoined	bool	Can the Session by Silent Joined	false	If (Session is Whisper Joined || Session is Silent Joined) -> false Else -> true
canBeWhisperJoined	bool	Can the Session be Whisper Joined	false	If (Session is Whisper Joined || Session is Silent Joined) -> false Else -> true
isOnHold	bool	Whether the Session is currently on hold	false	Session.IsOnHold
holdStartTime	string – datetime This timestamp will be in the JSON timestamp format	If the Session is currently on hold, when did that hold start (in UTC)	"2016-08-31T17:41:16.967Z"	Session.HoldStartTime
recordingStartTime	string – datetime This timestamp will be in the JSON timestamp format	If the Session is currently being recorded, when did the recording start (in UTC)	"2016-08-31T17:41:16.967Z"	Session.RecordingStartTime
answeredTimeStamp	string – datetime This timestamp will be in the JSON timestamp format	When the Session was answered by the current primary Agent (in UTC)	"2016-08-31T17:41:16.967Z"	Session.AgentSession.StartTime for Emails Session.AgentSession.AcceptTime for AV and IM
sessionHasEnded	bool	Whether the Session has ended	false	If (Session.AgentSession where AgentId is the Session.AgentId and EndTime is null) -> true Else -> false
agents	List Response of Agent Participation objects	List of information about what Agents are participating in this Session. Contacts will not show up when consulting or invited.		Session.AgentSession where AgentId is the Session.AgentId and EndTime is null and AgentParticipationStatusId is not Offering, Accepted or RONA
offers	List Response of Agent Offer objects	List of information about which Agents are being offered to participate in the Session		Session.AgentSession where AgentId is the Session.AgentId and EndTime is null and AgentParticipationStatusId is Offering
screenPopUrl	String	Web page to load in the Agent Console	http://sf.com/account/5	session.SessionExtraItem.Value
activeTimeStamp	string – datetime This timestamp will be in the JSON timestamp format	When the Session became active with an Agent (IM or Voice)	"2016-08-31T17:41:16.967Z"	From SessionStatusHistory.LastUpdated for Active or ActiveImOnly
endTimeStamp	string – datetime This timestamp will be in the JSON timestamp format	When the Session completed	"2016-08-31T17:41:16.967Z"	From SessionStatusHistory.LastUpdated for completed states
sessionDurationMs	Integer	The total duration of the Session from New status to a completed status or Utc Now	60000	Session has completed -> EndTimeStamp – startTimestamp Session is currently active -> Utc Now - startTimestamp

Session Base

Field Name	Data Type	Description	Sample Value	Source
sessionId	integer	The Session Id	10	SessionDetail.SessionId
sessionType	string	The type of Session	“Queued” Valid values are: “Queued” “Direct Inbound” “Direct Outbound”	If SessionDetail.QueueId > 0 -> “Queued” If SessionDetail.QueueId = -1 -> “Direct Inbound” If SessionDetail.QueueId = -2 -> “Direct Outbound”
queueName	string	The name of the Queue the Session was first enqueued in	“New Order”	If SessionDetail.Queue.PublicName -> PublicName If ! SessionDetail.Queue.PublicName -> “Unknown” If SessionDetail.QueuedId = -1 -> “Direct Inbound” If SessionDetail.QueueId = -2 => “Direct Outbound”
queueId	integer	The id of the Queue the Session was first enqueued in	1	SessionDetail.QueueId
customerId	integer	Customer’s Identifier	“John Doh”	sessionDetail.CustomerIdentifier
customerName	string	The Customer’s name	“James T. Kirk”	Session.SessionDetail.CustomerFullName
customerPhone	string	The Customer’s phone number or SIP URI	“sip:jtkirk@ccdev2015.internal”	Session.SessionDetail.CustomerSipUri
agentId	integer	The id of the Responding (first answering) Agent	5	Session.SessionDetail.AgentId
agentName	string	The Responding (first answering) Agent’s public name	“Bob”	Session.SessionDetail.AgentId to Agent.AgentId, Agent.PublicName If Agent.PublicName is null, “Unknown” If no Agent, “None”
modalityId	integer	The original modality of the Session	1 Valid values are: 1 (InstantMessage) 2 (AudioVideo) 3 (Message)	Session.ModalityId
modality	string	The original modality of the Session	“InstantMessage” Valid values are: “InstantMessage” “AudioVideo” “Message” “Unknown”	Session.ModalityId -> parse string from enum “Unknown” if parse fails
startTimeStamp	string – datetime This timestamp will be in the JSON timestamp format	When the Session started (in UTC)	"2016-08-31T17:41:16.967Z"	Session.StartTime
callFlowName	string	Name of the Call Flow that this Session went through	“Best Call Flow Ever”	callFlowSession with sessionId of session and then to callFlowDefinition
callFlowId	integer	The Call Flow Id of the Call Flow this Session went through	1	callFlowSession with sessionId of session and then to callFlowDefinition
callNote	string	Call notes	“Customer was locked out of their account after 3 failed attempts to login”	sessionDetail.CallNote
selectedCallDisposition	Selected Call Disposition	Call Disposition Id and Name for the Session	callDispositionId: 3 name: “Accounts”	sessionDetail.CallDispositionId
selectedCallSubDisposition	Selected Call SubDisposition	Call SubDisposition Id and Name for the Session	callSubDispositionId: 1 name: “Password Change”	sessionDetail.CallSubDispositionId

Agent Participation

Field Name	Data Type	Description	Sample Value	Source
agentId	integer	The id of the participating Agent	5	AgentSession.AgentId
agentName	string	The participating Agent’s public name	“Bob”	AgentSession.AgentId to Agent.AgentId, Agent.PublicName If Agent.PublicName is null, “Unknown” If no Agent, “None”
agentParticipationTypeId	integer	Id for how the Agent is participating in the Session	1 Valid values are: 1 (Agent) 4 (Consult) 5 (TransferAgent) 6 (Contact) 7 (WhisperJoin) 8 (SilentJoin) 9 (Invite) 10 (BargeIn)	AgentSession.AgentParticipationTypeId
agentParticipationType	string	How the Agent is participating in the Session	“Agent” Valid values are: “Agent” – answering Agent “Consult” – consulting with primary agent “TransferAgent” – new primary Agent after getting Session transferred to them “Contact” – Session transferred to them as a Contact? “WhisperJoin” – Joined as supervisor that only the Agent can hear or see “SilentJoin” – Joined as a supervisor that nobody can hear or see “Invite” – Invited by the primary Agent to also be heard/seen by the customer. Also could be a supervisor after a barge-in “BargeIn” – Joined as a supervisor Silent or Whisper and now have become a full participant in the Session and can be heard and seen by the customer	AgentParticipationType.Name
agentParticipationStatusId	integer	Id for the status of the Agent’s participation	3 Valid values are: 3 (Accepted) 4 (AfterCall)	AgentSession.AgentParticipationStatusId
agentParticipationStatus	string	The status of the Agent’s participation	“Accepted” “AfterCall” Valid values are: “Accepted” – are participating in the Session “AfterCall” – Agent is in After Call Because these objects are for active participations this property will always be “Accepted” or “AfterCall”	AgentParticipationStatus.Name
allocatedTimeStamp	string – datetime This timestamp will be in the JSON timestamp format	When the Agent was allocated to this Session	"2016-08-31T17:41:16.967Z"	AgentSession.StartTime
offeredTimeStamp	string – datetime This timestamp will be in the JSON timestamp format	When the Attendant contact offered the Session to the Agent	"2016-08-31T17:41:16.967Z"	AgentSession.OfferTime
acceptedTimeStamp	string – datetime This timestamp will be in the JSON timestamp format	When the Agent accepted the offer and was connected to the Session	"2016-08-31T17:41:16.967Z"	AgentSession.AcceptTime
afterCallStartTimeStamp	string – datetime This timestamp will be in the JSON timestamp format	When the Agent began After Call for this Session	"2016-08-31T17:41:16.967Z"	AgentSession.AfterCallStartTime
isPrimaryAgent	bool	Whether the Agent is the primary (call control) Agent on the Session	true	AgentSession.IsPrimaryAgent
primaryAgentStartTimeStamp	string – datetime This timestamp will be in the JSON timestamp format	When the Agent became the primary Agent on the Session (if isPrimaryAgent is true)	"2016-08-31T17:41:16.967Z"	AgentSession.PrimaryAgentStartTime
initiatingAgentId	integer	Id of the Agent that requested (initiated) this participation if the participation is a Consult, Invite, Contact or TransferAgent	7	AgentSession.InitiatingAgentId
initiatingAgentName	string	Name of the Agent that requested (initiated) this participation if the participation is a Consult, Invite, Contact or TransferAgent	“Captain Picard”	AgentSession.InitiatingAgentId to Agent.AgentId, Agent.PublicName If Agent.PublicName is null, “Unknown” If no Agent, “None”
activeMs	integer	Total milliseconds the Agent has been active on this Session, i.e. how long since they accepted the offer	55000	Utc Now - AgentSession.AcceptTime

Agent Offer

Field Name	Data Type	Description	Sample Value	Source
agentId	integer	The id of the participating Agent	5	AgentSession.AgentId
agentName	string	The participating Agent’s public name	"Bob"	AgentSession.AgentId to Agent.AgentId, Agent.PublicName If Agent.PublicName is null, “Unknown” If no Agent, “None”
agentParticipationTypeId	integer	Id for what type of participation the offer is for	1 Valid values are: 1 (Agent) 4 (Consult) 5 (TransferAgent) 6 (Contact) 7 (WhisperJoin) 8 (SilentJoin) 9 (Invite) 10 (BargeIn)	AgentSession.AgentParticipationTypeId
agentParticipationType	string	What type of participation the offer is for	“Agent” Valid values are: “Agent” – answering Agent “Consult” – consulting with primary agent “TransferAgent” – new primary Agent after getting Session transferred to them “Contact” – Session transferred to them as a Contact? “WhisperJoin” – Joined as supervisor that only the Agent can hear or see “SilentJoin” – Joined as a supervisor that nobody can hear or see “Invite” – Invited by the primary Agent to also be heard/seen by the customer. Also could be a supervisor after a barge-in “BargeIn” – Joined as a supervisor Silent or Whisper and now have become a full participant in the Session and can be heard and seen by the customer	AgentParticipationType.Name
agentParticipationStatusId	integer	Id for the status of the Agent’s participation	2 Valid values are: 2 (Offering)	AgentSession.AgentParticipationStatusId
agentParticipationStatus	string	The status of the Agent’s participation	“Offering” Valid values are: “Offering” – offering to the Agent Because these objects are for offers this property will always be “Offering”	AgentParticipationStatus.Name
allocatedTimeStamp	string – datetime This timestamp will be in the JSON timestamp format	When the Agent was allocated to this Session	"2016-08-31T17:41:16.967Z"	AgentSession.StartTime
offeredTimeStamp	string – datetime This timestamp will be in the JSON timestamp format	When the Attendant contact offered the Session to the Agent	"2016-08-31T17:41:16.967Z"	AgentSession.OfferTime
initiatingAgentId	integer	Id of the Agent that requested (initiated) this participation if the participation is a Consult, Invite, Contact or TransferAgent	7	AgentSession.InitiatingAgentId
initiatingAgentName	string	Name of the Agent that requested (initiated) this participation if the participation is a Consult, Invite, Contact or TransferAgent	“Captain Picard”	AgentSession.InitiatingAgentId to Agent.AgentId, Agent.PublicName If Agent.PublicName is null, “Unknown” If no Agent, “None”

Session Call Flow

Field Name	Data Type	Description	Sample Value	Source
sessionId	integer	Session Id	123456789	CallFlowSession.SessionId
callFlowId	Integer	Call Flow Id	123456789	CallFlowSession.CallFlowId
callFlowName	String	Call Flow Name	“Accounts Payable Call Flow”	CallFlowDefinition.Name

Selected Call Disposition

Field Name	Data Type	Description	Sample Value	Source
callDispositionId	integer	The Agent’s Id	10	SessionDetail.CallDispositionId
name	string	Call Disposition name	“Accounts”	CallDisposition.CallDisposition1

Selected Call SubDisposition

Field Name	Data Type	Description	Sample Value	Source
callSubDispositionId	integer	Call SubDisposition Id	5	SessionDetail.CallSubDispositionId
name	string	Call SubDisposition name	“Change Password”	CallDisposition.CallSubDisposition1

Entity

Field Name	Data Type	Description	Sample Value	Source
type	string	The type of entity	Entity
id	integer	The id of the entity	12
Name	string	The name of the entity	Test

Session Message

Session Message contains all the properties of Entity plus the properties below.

Field Name	Data Type	Description	Sample Value	Source
sessionId	string	Id of the session associated with the session message	1
agentId	string	Id of the agent associated with the session message	2
sessionMessageTypeId	string	Type Id of the session message	1
published	string – datetime
This timestamp will be in the JSON timestamp format	When the session message was published	2016-12-02T17:01:40.393Z

IM Prompt

IM Prompt contains all the properties of Entity plus the properties below.

Field Name	Data Type	Description	Sample Value	Source
promptName	string	The prompt name	Greeting
promptValue	string	The prompt value	Greeting

IVR Data

IVR Data contains all the properties of Entity plus the properties below.

Field Name	Data Type	Description	Sample Value	Source
callFlowName	string	Name of the call flow	Quick Starter IVR
ivrNodes	List Response of IVR Node objects	Collection of IVR Nodes

IVR Node

IVR Node contains all the properties of Entity plus the properties below.

Field Name	Data Type	Description	Sample Value	Source
nodeName	string	Name of the node	Main Menu
selectedResult	string	Result selected for the node	2	Can be null
nodeNote	string	Note of the node	Selected 2
Duration	integer	Duration of the node	0

Call Disposition

Call Disposition contains all the properties of Entity plus the properties below.

Field Name	Data Type	Description	Sample Value	Source
dispositionId	integer	Id of the call disposition	1
Disposition	string	String representation of the call disposition	Test
businessUnitId	integer	Id of the business unit associated with the call disposition	0	Can be null
subDispositions	List Response of Call Sub-Disposition objects	Sub-Dispositions associated with the call disposition

Call Sub-Disposition

Call Sub-Disposition contains all the properties of Entity plus the properties below.

Field Name	Data Type	Description	Sample Value	Source
subDispositionId	integer	Id of the call sub-disposition	1
subDisposition	string	String representation of the call sub-disposition	Test

Extra Item

Extra Item contains all the properties of Entity plus the properties below.

Field Name	Data Type	Description	Sample Value	Source
extraItemId	integer	Id of the extra item	1
key	string	Key of the extra item	Priority
value	string	Value of the extra item	0
isSearchable	bool	Is the Extra Item marked as Searchable in the Admin Site	false	ExtraItem.Searchable

Session Even History

Session Event History contains all the properties of Entity plus the properties below.

Field Name	Data Type	Description	Sample Value	Source
eventText	string	Text of the session event	Session Created
lastUpdated	string – datetime
This timestamp will be in the JSON timestamp format	Last time the session event was updated	2016-12-02T17:01:40.393Z
updatedBy	string	What updated the session event	APP-01

Aftercall Config

Aftercall Config contains all the properties of Entity plus the properties below.

Field Name	Data Type	Description	Sample Value	Source
IsManualAfterCallEnabled	bool	Whether or not manual calling is enabled after call	True
afterCalltimeSeconds	integer	Time duration after the call	10

Get IM Transcript History Response

Field Name	Data Type	Description	Sample Value	Source
items	array of Transcript Message objects	One or many Transcript Messages
count	integer	How many Transcript Messages are in the items array	1	Count of items array

Transcript Message

Field Name	Data Type	Description	Sample Value	Source
timeStamp	integer	Time the message occurred	01-01-2006
to	string	Destination of the message	Test User
from	string	Originator of the message	Test User 2
message	string	Message	Test
fromAgent	boolean	Whether the message was from an Agent	true/false
type	string		imMessage
id	integer	Id of this entity	12

Get GRUU for Session

Field Name	Data Type	Description	Sample Value	Source
gruu	string	GRUU for the Session	sip:app-01.ccdev2015.internal@ccdev2015.internal;gruu;opaque=srvr:connect.40:B7LaoOm5-VCntKDyYgg5NAAA

Update Session Extra Item Request

Field Name	Data Type	Description	Sample Value	Source
extraItemId	integer	Id of the extra item data in the session	1
extraItemName	string	Key name of the extra item	Subject
extraItemValue	string	Value of the extra item	test

Save Call Notes Request

Field Name	Data Type	Description	Sample Value	Source
note	string	Call note to save to the session	test

Save Dispositions Request

Field Name	Data Type	Description	Sample Value	Source
dispositionId	integer	Id of the disposition for the session	1
subDispositionId	integer	The Id of the sub-disposition for the session	1

Session Recording Request Status Response

Field Name	Data Type	Description	Sample Value	Source
sessionId	integer	Session Id of a Session the Agent is participating in	105	SessionDetail.SessionId
isRecording	bool	Is the Session currently being recorded	true	Session.IsRecording
canBeRecorded	bool	Can the Session be recorded (or is it prohibited by rule)	true	Session.CanBeRecorded
requestDenied	bool	Whether the API consumer (requesting Agent) is unauthorized to record the Session based on its primary Agent	false
requestFailed	bool	Whether the stop or start recording request failed when sent to the Portal	false

Agent Status

Agent Status by Agent Response

Field Name	Data Type	Description	Sample Value	Source
type	string	The “type” of object this is. A legacy field from the v1 API	"agent" This is the only valid value	Hard-coded to always be “agent” for legacy v1.0 API reasons
id	integer	The Agent’s Id	10	AgentStatusHistory.Agent.AgentId Most recent row by AgentStatusHistory.LastUpdated
name	string	The Agent’s Public Name	"Jean Luc Picard"	AgentStatusHistory.Agent.PublicName Most recent row by AgentStatusHistory.LastUpdated
currentStatus	Connect Agent Status object	The Agent’s current Connect Status

Connect Agent Status

Field Name	Data Type	Description	Sample Value	Source
agentStatus	string	Agent Status as a string	“available” Possible values are: “available” “inCall” “unavailable” “unknown” “afterCall” “loggedOut” “offPhoneActivity” “ringOnNoAnswer” “busy” “beRightBack” “directCall” “inactive” “inImCall” “directInboundDial” “directOutboundDial” “atLunch” “offWork” “conferenceCall” “ringing”	AgentStatusHistory.AgentStatus.Name Most recent row by AgentStatusHistory.LastUpdated These values are camel-cased (start with a lower-case letter because the Dashboard is hard-coded to look for camel-cased agent status values)
agentStatusId	integer	Agent Status Id	3 Possible values are: 1 (Available) 2 (InCall) 3 (Unavailable) 4 (Unknown) 5 (AfterCall) 6 (LoggedOut) 7 (OffPhoneActivity) 8 (RingOnNoAnswer) 9 (Busy) 10 (BeRightBack) 11 (DirectCall) 12 (Inactive) 14 (InImCall) 15 (DirectInboundDial), 16 (DirectOutboundDial) 17 (AtLunch) 18 (OffWork) 19 (ConferenceCall) 20 (Ringing)	AgentStatusHistory.AgentStatusId Most recent row by AgentStatusHistory.LastUpdated
reasonCodeName	string	Away Reason Code if set in Away status	"On Break"	If (AgentStatusHistory.ReasonCode != null) -> AgentStatusHistory.ReasonCode. Description Else -> null Most recent row by AgentStatusHistory.LastUpdated
startTime	integer	The Away Reason Code Id	2	AgentStatusHistory.ReasonCodeId Most recent row by AgentStatusHistory.LastUpdated
endTime	string - datetime This timestamp will be in the JSON timestamp format	When the Agent left this status. In UTC. Will not be populated in any current Agent Status response.		Will not be populated in any current Agent Status response.
isSuspended	bool	Is the Agent suspended from taking Connect Sessions	false	AgentStatusHistory.Agent.IsSuspended Most recent row by AgentStatusHistory.LastUpdated

Update Agent Status Request

Field Name	Data Type	Description	Sample Value	Source
agentStatusId	integer	Desired Agent Status Id	3 Possible values are; 1 (Available), 2 (InCall), 3 (Unavailable), 4 (Unknown), 5 (AfterCall), 6 (LoggedOut), 7 (OffPhoneActivity), 8 (RingOnNoAnswer), 9 (Busy), 10 (BeRightBack), 11 (DirectCall), 12 (Inactive), 14 (InImCall), 15 (DirectInboundDial), 16 (DirectOutboundDial), 17 (AtLunch), 18 (OffWork), 19 (ConferenceCall), 20 (Ringing)
reasonCodeId	integer	Desired Away Reason Code Id if Agent Status Id is set to 3	5	ReasonCodeId is used if the AgentStatusId is set and set to 3 OR if the ReasonCodeId is set and AgentStatus is not, in which case it defaults AgentStatus to 3
isSuspended	bool	Desired Suspended Status of Agent	false	IsSuspended is only used if the AgentStatusId property is NOT set (or NULL) in the POST body

List Agent Statuses by Agent Response

The response contains a single List Response object wrapping a collection of Connect Agent Status. The source of this information is from the AgentStatusId Enum as

well as any reason codes found in the repository.

Agent Metrics

Realtime Data Response

Field Name	Data Type	Description	Sample Value	Source
type	string	Entity type: Agent or Queue	“agent”	Gold Copy
metrics	Metric Bag	Metrics for this entity	“audio”	Gold Copy
name	string	Name of the Entity	“Jean Luc Picard”	Gold Copy
id	integer	Entity Id		Gold Copy
sessions	Session Bag	Sessions associated with the entity	See Session Bag reference	Gold Copy
currentStatus	string	Connect Status of the entity (if an Agent)	“active”	Gold Copy
statusHistory	string	The Agent’s Public Name	{ “agentStatus”: “available”, “startTime”: “2016-1-1 05:00”, “endTime”: “2016-1-1 06:00” }	Gold Copy
addedBreakdowns	string	Any new breakdowns	TODO	Gold Copy
breakdowns	string	All breakdowns	TODO	Gold Copy
removedBreakdowns	string	Any breakdowns that were removed	TODO	Gold Copy

Metric Bag

Field Name	Data Type	Description	Sample Value	Source
audio	Object	AV related metrics	ronaCount	Gold Copy
instantMessage	Object	Instant message related metrics	answeredCount	Gold Copy
message	Object	Message related metrics	closedTodayMessageCount	Gold Copy
agnostic	Object	Metrics not broken down by modality	availableTime	Gold Copy

Session Bag

Field Name	Data Type	Description	Sample Value	Source
audio	Added And Removed Session Model	AV related metrics	ronaCount	Gold Copy
instantMessage	Added And Removed Session Model	Instant message related metrics	answeredCount	Gold Copy
message	Added And Removed Session Model	Message related metrics	closedTodayMessageCount	Gold Copy

Added and Removed Session Model

Field Name	Data Type	Description	Sample Value	Source
addedSessions	List<Session Model>	AV related metrics	{ "sessionId": 82673, "sessionType": "queued", "queueId": 11, ... }	Gold Copy
sessions	List<Session Model>	Instant message related metrics	{ "sessionId": 82673, "sessionType": "queued", "queueId": 11, ... }	Gold Copy
removedSessions	List<Session Model>	Message related metrics	{ "sessionId": 82673, "sessionType": "queued", "queueId": 11, ... }	Gold Copy

Session Model

Field Name	Data Type	Description	Sample Value	Source
sessionId	integer	Session Id	123456	Gold Copy
sessionType	String	The type of Session	Queued, DID, DOD	Gold Copy
queueId	Integer	The Session’s Queue	123456	Gold Copy
customerName	String	Customer Name	“John Smith”	Gold Copy
agentId	Integer	The Session's Primary Agent	123456	Gold Copy
isRecording	Bool	Whether or not the Session is being recorded	True/False	Gold Copy
canBeRecorded	Bool	Can the Session be recorded	True/False	Gold Copy
isSilentJoined	Bool	Whether or not anyone is Silent Joined to the Session	True/False	Gold Copy
isWhisperJoined	Bool	Whether or not anyone is Whisper Joined to the Session	True/False	Gold Copy
sessionStatus	String	Status of the Session	New, Queued, Active, Completed, Connecting, Terminating, Abandoned	Gold Copy
queuedMs	Integer	How long the Session was Queued	34887	Gold Copy
activeMs	Integer	How long the Session was Active	22954	Gold Copy
canBeSilentJoined	Bool	Can the Session by Silent Joined	True/False	Gold Copy
canBeWhisperJoined	Bool	Can the Session be Whisper Joined	True/False	Gold Copy

Status Model

Field Name	Data Type	Description	Sample Value	Source
agentStatus	integer	Connect Status as a string	Available, InCall, Unavailable, Unknown, AfterCall, LoggedOut, OffPhoneActivity, RingOnNoAnswer, Busy, BeRightBack, DirectCall, Inactive, InImCall, DirectInboundDial, DirectOutboundDial, AtLunch, OffWork, ConferenceCall, Ringing	Gold Copy
reasonCodeName	string	Reason code if in Away status	“Out for Lunch”	Gold Copy
startTime	Integer	When the Agent entered this status (in UTC)	“2016-11-01T21:13:10.293Z”	Gold Copy
endTime	String	When the Agent left this status (in UTC). Null if still in this status	“2016-11-01T21:13:10.293Z”	Gold Copy
isSuspended	integer	Is the Agent suspended from taking Connect sessions	True/False	Gold Copy

Aggregate Metric Data Response

The Aggregate Metric Data Response includes all the Properties of the Realtime Data Response plus the property below.

Field Name	Data Type	Description	Sample Value	Source
entityIds	List<integer>	Entity ids included in this aggregation	1,2,3	Gold Copy

Group Metric Data Response

The Group Metric Data Response includes all the Properties of the Aggregate Metric Data Response plus the properties below.

Field Name	Data Type	Description	Sample Value	Source
groupType	String	The type of the grouped metrics: Agent or Queue	Agent	Gold Copy
groupId	integer	The id of the grouping	1	Gold Copy

Subscription

Agent Subscription Request

Field Name	Data Type	Description	Sample Value	Notes
connectionId	string	SignalR connection Id	“88cfebc8-e9f5-47a5-bfea-01b949ff9247”
sessionProperties	List<SessionPropertyType>	Session properties to include in the response: , SessionStatus, QueuedMs, ActiveMs, CanBeSilentJoined, CanBeWhisperJoined	{ 1, 3, 4 } SessionType, AgentId, and CustomerName selected.
statusProperties	List<StatusPropertyType>	Status properties to include in the response: AgentStatus, ReasonCodeName, UtcStartTime, UtcEndTime, IsSuspended	{1,2} AgentStatus and ReasonCodeName selected.

Queue Subscription Request

Field Name	Data Type	Description	Sample Value	Notes
connectionId	string	SignalR connection Id	“88cfebc8-e9f5-47a5-bfea-01b949ff9247”
metricProperties	List<string>	Metrics to include in the response.	{ 1, 3, 4 } SessionType, AgentId, and CustomerName selected.
sessionPropertyType	List<SessionPropertyType>	Session properties to include in the response for any sessions for this Queue: SessionType, QueueId, AgentId, CustomerName, IsRecording, CanBeRecorded, IsSilentJoined, IsWhisperJoined, SessionStatus, QueuedMs, ActiveMs, CanBeSilentJoined	{1,2} AgentStatus and ReasonCodeName selected.

Alert Subscription Request

Field Name	Data Type	Description	Sample Value	Notes
connectionId	string	SignalR connection Id	“88cfebc8-e9f5-47a5-bfea-01b949ff9247”

Batch

Batch Request

Field Name	Data Type	Description	Sample Value	Notes
method	string	HTTP verb associated with endpoint method	GET
relativeUrl	string	The URL suffix off the root api URL. This includes the route to the desired endpoints.	../v1.0/subscriptions/agents/?modalities=2&agentIds=5
body	List<string>	Values to be sent in the request body.	{ "connectionId":"123-456-789" }

Client Logs

Write Log From Client Request

Field Name	Data Type	Description	Sample Value	Notes
sessionId	integer	The session Id associated with the request	1	Can be null
component	string	The component controls which log to write to.	“auth”	If left empty it will be written to the other log file.
logLevel	string	Log Level: Verbose Debug Info Warn Error Fatal	“error”	If not specified debug will be used.
message	string	String to write to log	“Error occurred on line 2146”	Cannot be null or empty.

Search

Search Response

Search Response is made up of Agent Search and Queue Search objects. Those objects are specializations of Search Entity Response.

Search Entity by Response

Field Name	Data Type	Description	Sample Value	Notes
type	string	The type of request (agent or queue)	agentSearch, queueSearch
id	integer	Id of this request	1
name	string			Can be null

Agent Search

Field Name	Data Type	Description	Sample Value	Notes
agentId	integer	Id of the agent	1
firstName	string	First name of the agent	Test
lastName	string	Last name of the agent	User
publicName	string	Display name of the agent	Test User
loginName	string	Login name of the agent	test.user@domain.com
sipAddress	string	SIP of the agent	sip:test.user@domain.com
phoneNumber	string	Phone number of the agent	“1234567890”
status	integer	Status of the agent	4	Can be null
callsAnswered	integer	Number of calls answered by the agent	1
ronas	integer

Queue Search

Field Name	Data Type	Description	Sample Value	Notes
queueId	integer	Id of the queue	1
queueName	string	Name of the queue	Test’s Queue
isOpen	boolean	If the queue is open or closed	false
agentsOnline	integer	Number of agents online in the queue	6
agentsAvailable	integer	Number of agents available in the queue	4
estimatedWaitTime	integer	Estimated time to wait in the queue	120
callsToday	integer	Number of calls the queue received today	15

Response

Field Name	Data Type	Description	Sample Value	Notes
agentsFound	array of Agent Search	Collection of agents found		Can be null
queuesFound	array of Queue Search	Collection of queues found		Can be null
message	string	If the queue is open or closed	Query 'queue' found 0 agent(s) and 15 queue(s).

Call Control

Session Action Request

Field Name	Data Type	Description	Sample Value	Notes
sessionId	integer	The session Id associated with the request	1	Can be null
component	string	The component controls which log to write to.	“auth”	If left empty it will be written to the other log file.
logLevel	string	Log Level: Verbose Debug Info Warn Error Fatal	“error”	If not specified debug will be used.
message	string	String to write to log	“Error occurred on line 2146”	Cannot be null or empty.