Customer Records Retriever

Introduction:

This document describes how to utilize the Customer Records Retriever (CRR) to retrieve session data from Glance, making a series of HTTP requests and interpreting the responses.

How to retrieve sessions:

  1. Make an HTTP POST to the following REST endpoint: https://cloud.glance.net/api/auth/service, with the following characteristics.

    1. Content-Type header is set to application/json.
    2. Request body is set to a JSON string that looks like the following, with user credentials procured through your Glance Networks representative: 
       {
     "username": "<USERNAME>",
     "password": "<PASSWORD>"
   }

  2. The response from the above call will look like the following, where the long access_token value is a JWT to be used in further HTTP calls:

       {
     "access_token": "eyJhbGciOi..."
   }

  3. Make an HTTP POST call to one of the the following REST endpoints:

    • For Completed Sessions: Use https://cloud.glance.net/api/crr/sessions/completed. This endpoint is for sessions with a ‘clean close’ status.

    • For All Sessions: Use https://cloud.glance.net/api/api/crr/sessions/ended: This includes both completed sessions (with a ‘clean close’) and sessions without a ‘clean close’, such as those that timed out.

      1. Content-Type header is set to application/json.
      2. Authorization header is set to Bearer <token> , where <token> is the JWT returned from the Authentication Service in step 2 above.
      3. Request body is set to a JSON string that looks like the following: 
       {
     "partnerId": 12345,
     "apiKey": "<REDACTED>",
     "startDate": "2023-08-12T00:00:00Z",
     "endDate": "2023-08-15T00:00:00Z",
     "pageId": 0,
     "channelBatchSize": 1000
   }

  4. The requested session data records will look like the following:

    a. Code 200 - on success (for Completed Sessions):

    {
   "sessions": [
  {
   "id": "111111111",
   "key": "5555",
   "status": "completed",
   "started_at": "2023-08-14T17:36:06.000Z",
   "ended_at": "2023-08-14T17:38:23.000Z",
   "extra": {
     "xid": "1234123412342134"
   },
   "channels": [
     {
       "type": "cobrowse",
       "id": "111111111",
       "key": "5555",
       "remote_assist_accepted": true,
       "legs": [
         {
           "type": "host",
           "participant_type": "visitor",
           "started_at": "2023-08-14T17:36:02.000Z",
           "ended_at": "2023-08-14T17:38:22.000Z",
           "extra": {
             "name": "Guy Example",
             "email": "guy@example.com",
             "phone": "555-123-4567"
           }
         },
         {
           "type": "viewer",
           "participant_type": "agent",
           "participant_id": "77777777",
           "participant_role": "AgentRole1",
           "origin": "AGENTAPP/1.2.3",
           "started_at": "2023-08-14T17:36:06.000Z",
           "ended_at": "2023-08-14T17:38:22.000Z"
         }
       ]
     },
     {
       "type": "video",
       "id": "222222222",
       "key": "5555V999999",
       "legs": [
         {
           "type": "host",
           "participant_type": "visitor",
           "started_at": "2023-08-14T17:36:46.000Z",
           "ended_at": "2023-08-14T17:38:22.000Z",
           "extra": {
             "name": "Guy Example",
             "email": "guy@example.com",
             "phone": "555-123-4567"
           }
         },
         {
           "type": "viewer",
           "participant_type": "agent",
           "participant_id": "77777777",
           "participant_role": "AgentRole1",
           "started_at": "2023-08-14T17:36:48.000Z",
           "ended_at": "2023-08-14T17:38:23.000Z"
         }
       ]
     },
     {
       "type": "video",
       "id": "333333333",
       "key": "5555V777777",
       "legs": [
         {
           "type": "host",
           "participant_type": "agent",
           "participant_id": "77777777",
           "participant_role": "AgentRole1",
           "started_at": "2023-08-14T17:36:47.000Z",
           "ended_at": "2023-08-14T17:38:22.000Z"
         },
         {
           "type": "viewer",
           "participant_type": "visitor",
           "started_at": "2023-08-14T17:36:49.000Z",
           "ended_at": "2023-08-14T17:38:23.000Z",
           "extra": {
             "name": "Guy Example",
             "email": "guy@example.com",
             "phone": "555-123-4567"
           }
         }
       ]
     },
     {
       "type": "screenshare",
       "id": "444444444",
       "key": "5555S888888",
       "legs": [
         {
           "type": "host",
           "participant_type": "agent",
           "participant_id": "77777777",
           "participant_role": "AgentRole1",
           "started_at": "2023-08-14T17:37:18.000Z",
           "ended_at": "2023-08-14T17:38:22.000Z"
         },
         {
           "type": "viewer",
           "participant_type": "visitor",
           "started_at": "2023-08-14T17:37:19.000Z",
           "ended_at": "2023-08-14T17:38:22.000Z",
           "extra": {
             "name": "Guy Example",
             "email": "guy@example.com",
             "phone": "555-123-4567"
           }
         }
       ]
     }
   ]
  }
 ],
 "nextPageId": 123456789
}

    b. Code 200 - on success (for All Sessions):

    {
      "sessions": [
    {
      "id": "14012522",
      "key": "270818",
      "status": "completed",
      "started_at": "2024-11-19T01:24:05.000Z",
      "ended_at": "2024-11-19T01:57:21.000Z",
      "channels": [
        {
          "type": "cobrowse",
          "id": "14012522",
          "key": "270818",
          "remote_assist_accepted": true,
          "legs": [
            {
              "participant_type": "visitor",
              "started_at": "2024-11-19T01:23:52.000Z",
              "ended_at": "2024-11-19T01:57:20.000Z",
              "type": "host"
            },
            {
              "participant_type": "agent",
              "started_at": "2024-11-19T01:24:05.000Z",
              "ended_at": "2024-11-19T01:57:20.000Z",
              "origin": "AGENTJOIN/6.37.0",
              "participant_role": "Example role",
              "participant_id": "24418",
              "type": "viewer"
            }
          ]
        },
        {
          "type": "video",
          "id": "14012523",
          "key": "270818V604450",
          "legs": [
            {
              "participant_type": "visitor",
              "started_at": "2024-11-19T01:24:05.000Z",
              "ended_at": "2024-11-19T01:57:19.000Z",
              "type": "host"
            },
            {
              "participant_type": "agent",
              "started_at": "2024-11-19T01:24:09.000Z",
              "ended_at": "2024-11-19T01:57:20.000Z",
              "participant_role": "Example role",
              "participant_id": "24418",
              "type": "viewer"
            }
          ]
        },
        {
          "type": "video",
          "id": "14012524",
          "key": "270818V670838",
          "legs": [
            {
              "participant_type": "agent",
              "started_at": "2024-11-19T01:24:10.000Z",
              "ended_at": "2024-11-19T01:57:20.000Z",
              "participant_role": "Example role",
              "participant_id": "24418",
              "type": "host"
            },
            {
              "participant_type": "visitor",
              "started_at": "2024-11-19T01:24:11.000Z",
              "ended_at": "2024-11-19T01:25:08.000Z",
              "type": "viewer"
            },
            {
              "participant_type": "visitor",
              "started_at": "2024-11-19T01:25:14.000Z",
              "ended_at": "2024-11-19T01:57:21.000Z",
              "type": "viewer"
                }
              ]
            }
          ]
        },
        {
          "id": "14012459",
          "key": "942635",
          "status": "quit",
          "started_at": "2024-11-18T18:19:08.000Z",
          "ended_at": "2024-11-18T18:19:27.000Z",
          "channels": [
            {
              "type": "cobrowse",
              "id": "14012459",
              "key": "942635",
              "remote_assist_accepted": false,
              "legs": [
                {
                  "participant_type": "visitor",
                  "started_at": "2024-11-18T18:19:08.000Z",
                  "ended_at": "2024-11-18T18:19:27.000Z",
                  "type": "host"
                }
              ]
            }
          ]
        },
        {
          "id": "14012533",
          "key": "0490",
          "status": "timed out",
          "started_at": "2024-11-19T02:52:13.000Z",
          "ended_at": "2024-11-19T03:04:20.000Z",
          "channels": [
            {
              "type": "screenshare",
              "id": "14012533",
              "key": "0490",
              "legs": [
                {
                  "participant_type": "visitor",
                  "started_at": "2024-11-19T02:52:13.000Z",
                  "ended_at": "2024-11-19T03:04:19.000Z",
                  "type": "viewer"
            }
          ]
        }
      ]
    }
  ],
  "nextPageId": 14012562
}

    c. Code 400 - badly formed request, with reason given:

      {
    "status": 400,
    "message": "Unknown environment"
  }

    d. Code 401 - bad JWT:

      {
    "status": 401,
    "message": "Unauthorized"
  }

    e. Code 422 - semantically bad request, with reason given:

      {
    "status": 422,
    "message": "Bad startDate value - not a valid date string"
  }

    f. Code 429 - request rate limit exceeded:

      {
    "status": 429,
    "message": "Too Many Requests"
  }

    g. Code 500 - unspecified internal error, or incorrect API Key specified in JSON payload:

      {
    "status": 500,
    "message": "Internal Server Error"
  }

Session Data Description:

The following is a description of the data returned in step 4 above, on success.

  • Each session in sessions has the following properties:

    1. id: A unique identifier for the session.
    2. key: The code/key a participant would use to interact with the session.
    3. status: An enumerated field which can have one of the following values:
      • For sessions/completed:
        • completed
      • For sessions/ended:
        • completed
        • quit
        • timed out
        • error
    4. started_at: A timestamp in RFC 3339 format (with zeroed-out milliseconds) denoting the time the session started, to second accuracy.
    5. ended_at: A timestamp in RFC 3339 format (with zeroed-out milliseconds) denoting the time the session ended, to second accuracy.
    6. channels: A list of JSON objects representing the channels used during the session (see below). A channel can be thought of as a stream of communication (e.g., cobrowse, video, screenshare) with a single active host/broadcaster and typically one or more passive viewers. There may be more than one channel per channel type in a given session.
    7. extra: A JSON object of arbitrary properties set by the customer through a Glance client. Here are some common properties used:
      • xid: An external ID for matching the session with the session record in another system used by the customer.

  • Each channel within a session has the following properties:

    1. type: An enumerated field which can have one of the following values:
      • cobrowse
      • video
      • screenshare
    2. id: A unique identifier for the channel. The "main" channel of a session will have the same value as the session id.
    3. key: The code/key a participant would use to interact with the session. The "main" channel of a session will have the same value as the session key.
    4. remote_assist_accepted: A boolean indicating whether Remote Assist was used - i.e., an agent's Remote Assist request was accepted by the visitor (Cobrowse channels only).
    5. legs: A list of JSON objects, each representing a span of time when a participant had been the channel (see below).

  • Each leg within a channel has the following properties:

    1. type: The type of leg, which can have one of the following values:
      • host: The participant hosted the channel.
      • viewer: The participant was a passive viewer of the host's data on the channel.
    2. participant_type: An enumerated field which can have one of the following values:
      • agent: A customer agent.
      • visitor: A site visitor.
      • guest: A guest of the session.
    3. participant_id: If participant_type is agent, this may contain the partner user ID of the agent. Only the main channel is guaranteed to have a leg with this set, and it is set for the agent who initiated the session with the visitor. For non-agent participants, this field will not be set.
    4. participant_role: If participant_type is agent, this may contain the name of the role of the agent, signifying a set of permissions. For non-agent participants, this field will not be set.
    5. origin: If participant_type is agent, this may contain the application used by the agent to join the channel. Can be null or missing if unrecorded. For non-agent participants, this field will not be set.
    6. started_at: A timestamp in RFC 3339 format (with zeroed-out milliseconds) denoting the time the participant joined the channel, to second accuracy.
    7. ended_at: A timestamp in RFC 3339 format (with zeroed-out milliseconds) denoting the time the participant left the channel, to second accuracy.
    8. extra: A JSON object of arbitrary properties set by the customer through a Glance client. Here are some common properties used:
      • name: The participant's name.
      • email: The participant's email address.
      • phone: The participant's phone number.

Assumptions:

  • The date range between startDate and endDate in step 3.c must not be 31 days or longer.
  • The apiKey value used in step 3.c is the same as the secret key used to access data from other endpoints on the glance.net Web Server. Please request this from your Glance Networks representative.
  • The batch size specified by channelBatchSize in step 3.c must not be greater than 1000.

Pagination

Pagination is recommended (but not required) to avoid pulling too much data in a single call, leading to 5xx errors due to the inability of the system to handle the request.

To use pagination effectively, set pageId to 0 in the first request, and as long as the value of nextPageId in the response of the last request made is not 0, continue to make requests with all parameters identical to the last call (although it is fine to modify channelBatchSize if desired) except for pageId, which should be set to the value of nextPageId in the previous response. Stop making requests when a response returns a nextPageId of 0. Note that it is normal for this last response to have an empty set of sessions.

Note that pageId is not a page number (i.e., 1, 2, 3, etc.), and that channelBatchSize is not the number of sessions returned in the response. channelBatchSize is related to the number of channels included in the session data, but the number of channels actually returned may be more than the number provided, in order to ensure that each session returned contains all its related channels - even those that may have ended before the given startDate.

Rate Limiting:

The endpoint in step 3 above is configured to only allow two requests per second for any given partnerId specified in the body. Making requests more frequently than that, over a period of time, will result in a 429 response.