Shelf Answer Assist Events Usage and Export Guide


Document Purpose 

This document details the Shelf Insights API for exporting Shelf Answer Assist usage events. All actions described in this document are executed in Postman. 
The target audience for this document is the Shelf customers’ engineers, integrators, and admins who are responsible for configuring, integrating, and processing the Shelf Answer Assist events.


Document Version History 

Version number

Modified by

Modifications made

Date modified

Status

1.0

Shelf

Initial release of the document.

16 January  2023

Expired

1.1

Shelf

Examples of answers added for each Answer Assist event type.

13 February 2023

Expired

1.2

Shelf

The document has been updated due to renaming and minor changes in the text.

23 August 2024

Active





Prerequisites

In order to be able to configure, integrate, and process the Shelf Answer Assist events for the Shelf Insights API, the Admin level of permissions is required in Shelf.


Useful links 


Example collection 



Obtaining the Shelf API token

In order to retrieve events from the Insights API, an API Token is needed. The procedure below describes how you can obtain it in Shelf.

  1. Log into your Shelf instance account using your valid Admin-level credentials.
  2. Once logged, go to the Admin Panel and find and select the API Tokens option in the sidebar panel.
  3. On the API Tokens page that opens, click the Create API Token button.
    Figure 1. Creating the API Token in Shelf

  4. Specify name, access type and a user group that has been granted access to Shelf Insights. 
    Figure 2. Configuring the API Token in Shelf

  5. Click the CREATE button and wait for the API Token to be created. Then copy the generated token and store it in a secure location for future reference.
    Figure 3. Viewing and copying the generated API Token

Sending Initial Query for the Shelf Answer Assist Events

Now you need to work with the Postman software to create and send inquiries for events that occur in the Answer Assist.

  1. Create a new POST request with the following URL: https://api.shelf.io/insights/agent-assist/events.
  2. Go to the Headers tab. Add a new header here with the Authorization key and paste the generated API Token into the value entry field.

    Figure 4. Entering the API Token in Postman

  3. Go to the Body tab and make sure that the type of the body is set to ‘raw’ and the content type is set to ‘JSON’. 

    Figure 5. Setting the request in Postman

    With providing an empty body “{}” you already will be able to fetch some results. Hitting the Send button results in the below response.
    {
       "events": {
           "totalCount":     12
               "edges": []
               "pageInfo": {
               "hasNextPage":     false
                   "hasPreviousPage": false
                   "startCursor": null
                   "endCursor": null
           }
      }
    }
    Calling the agent-assist/events endpoint with an empty body (“{}”)  returns the summary of the total count of events. The additional properties such as ‘edges’ and ‘pageInfo’ are detailed below.


Retrieving Event Data

To retrieve the detailed event data, the ‘first’ or ‘last’ property can be provided in the body of the request with the number of events to be fetched.
Figure 5. Indicating the number of events to be fetched

After making such a request, the response edges property will contain an array of the first 2 out of 12 found events. Every result consists of two parts: the node that contains the event itself, and the cursor that will be explained further.

{
   "events": {
       "totalCount": 12
       "edges": [
           {
               "node": {
                   "accountId": "abcd1234abcd56789",
                   "eventId": "dcba3214",
                   "eventCreatedAt": "2023-01-19T11:39:01.0123",
                   "eventName": "aa.session.start",
                   "userId": "bcad123123bcad",
                   "sessionId": "bcad321431"
               },
               "cursor": "MDFGTjZZMEg2RjI1SzZDTUo5UjE1MVNTOUU"
           },
           {
               "node": {
                   "accountId": "abcd1234abcd56789",
                   "eventId": "dcba3214",
                   "eventCreatedAt": "2023-01-19T11:42:01.0231,
                   "eventName": "aa.session.start",
                   "userId": "bcad123123bcad",
                   "sessionId": "bcad321431"
               },
               "cursor": "MDFGTjZZMEg2RjI1SzZDTUo5UjE1MVNTRBQU"
           }
       ],
}


If you enter ‘last’ instead of ‘first’ in the request, you will fetch last x events of the Shelf Answer Assist, respectively. 


Filtering Events

            

Filtering by Type 

You can specify what kind of events to fetch by adding the eventNames property to your request body with an array of event types names to filter.  For example, the below request will fetch only ‘session-start’ and ‘gem-page-viewed’ events.

Figure 6. Requesting certain Answer Assist event types


             

Filtering by Date 

The searched events can be filtered by date as well. Ender the startAt property in the request body to fetch events for a specific date and the endAt property to get events until the specified date. Please note that the date should be provided in ISO format (e.g. YYYY-MM-DDTHH:MM:SSZ). If no values are provided, the default ‘startAt’ is set to January 1, 2017 and ‘endAt’ is the current date.

Figure 7. Requesting Answer Assist events for certain dates


Sorting Events 

By default, the events fetched are sorted by their creation date as shown in the example below.


{
   "first": 10,
   "sortBy": "eventCreatedAt",
   "sortOrder": "asc"
}


The “sortBy”: “eventName” property enables you to change the default sorting behavior by grouping events by their names. Ascending or descending sorting order may be specified as well using the sortOrder property. The default sortOrder is ascending.

Figure 8. Sorting the Answer Assist events to be fetched


Pagination

You can navigate through the search results using the pagination option. Every fetched event consists of two parts: an event body and a cursor for the event. By providing such a cursor value in ‘after’ or ‘before’ property of the request body you will be able to fetch results after or before some specific event.

               "node": {
                   "accountId": "abcd1234abcd56789",
                   "eventId": "dcba3214",
                   "eventCreatedAt": "2023-01-19T11:39:01.0123",
                   "eventName": "aa.session.start",
                   "userId": "bcad123123bcad",
                   "sessionId": "bcad321431"
              },
              "cursor": "MDFGTjZZMEg2RjI1SzZDTUo5UjE1MVNTOUU"


You can also find the cursors of the first and the last events in response in the pageInfo section:

               "pageInfo" {
                   "hasNextPage": true,
                   "hasPreviousPage": false,
                   "startCursor": "MDFGTjZZMEg2RjI1SzZDTUo5UjE1MVNTOUU",
                   "endCursor": "MDFGTjZZMEg2RjI1SzZDTUo5UjE1MVNTRBQU"
              }

The hasNextPage property indicates whether there are any additional events available to be fetched. To retrieve the next page of events, the after property can be used in a subsequent query specifying the cursor value from the endCursor.

"first": 500,
   "after": "MDFGTjZZMEg2RjI1SzZDTUo5UjE1MVNTOUU",
   "startAt": "2023-01-01T00:00:00Z",
   "endAt": "2023-01-19T00:00:00Z

The hasPreviousPage property indicates that there are a set of events that occurred before the current result set. To retrieve the previous page of events, the before property can be used in a subsequent query specifying the cursor value from the startCursor.




Agent Assist Event Types

This section details the events available from the Answer Assist events API.



aa.session.start

The aa.session.start event is triggered when the Shelf Answer Assist application is rendered in an Agent’s environment.


Event Properties

Property name

Description

eventId

Unique Identifier for the event record

accountId

Unique account identifier for the Shelf Instance. This ID can be found in your Shelf instance at the following path: Admin Panel > Account Overview. Additionally, this ID can be retrieved by the Get Account Information API call.

eventCreatedAt

Date Timestamp of the event

eventName

Event Name (e.g. aa.session.start)

userId

Unique ID of the Shelf user. Additional Shelf User information can be retrieved using the List Account Users API. 

sessionId

Unique session identifier used to group all subsequent session usage events together


Example Event Properties

{
   "node": {
      "eventId": "01FM3BYPZ1A...",
      "accountId": "QTRZ4...",
      "eventCreatedAt": "2021-11-09T22:09:03.826Z",
      "eventName": "aa.session.start",
      "userId": "dfcf28f4-e32b-4bc2-964a-...",
      "sessionId": "607a854f-3a49-4c48-9bb2-..."
   },
   "cursor": "MDFGTlM4Q..."
}


Example of answers that can be received using the data fetched from the Insights API 

  • Total number of Answer Assist’s sessions 
  • Average number of Answer Assist’s sessions 
  • Percentage of Answer Assist’s sessions in the total sessions across agents’ environment 

Slices (specific portions of Answer Assist’s data): 
  • per account
  • per agent
  • per session 

Timeline (time span of Answer Assist’s data):
  • per day
  • per week
  • per month
  • per any custom time period.



aa.tab.clicked

This event is triggered when an Agent has selected an Answer Assist tab of interest by clicking the tab icon.


Event Properties 

Property name

Description

eventId

Unique Identifier for the event record

accountId

Unique account identifier for the Shelf Instance. This ID can be found in your Shelf instance at the following path: Admin Panel > Account Overview. Additionally, this ID can be retrieved by the Get Account Information API call.

eventCreatedAt

Date Timestamp of the event

eventName

Event Name (e.g. aa.tab.clicked)

userId

Unique ID of the Shelf user. Additional Shelf User information can be retrieved using the List Account Users API. 

tab

The Agent Assist tab from which the event originated. Possible values include  'suggestions'  'gem'  ‘search’  'favorites’  ’announcements’  'links'  'settings'    

sessionId

Unique session identifier used to group all subsequent session usage events together


Example Event Properties

{
   "node": {
      "eventId": "01FM3BYPZ1A...",
      "accountId": "QTRZ4...",
      "eventCreatedAt": "2023-01-19T12:09:03.826Z",
      "eventName": "aa.tab.clicked",
      "userId": "dfcf28f4-e32b-4bc2-964a-...",

“tab”: “search”,
      "sessionId": "607a854f-3a49-4c48-9bb2-..."
   },
   "cursor": "MDFGTlM4Q..."
}


Example of answers that can be received using the data fetched from the Insights API 

  • Total number of specific tab openings (this Answer Assist’s feature is one of the most interesting for agents)
  • Average number of specific tab openings

Slices (specific portions of Answer Assist’s data): 
  • per account
  • per agent
  • per session 

Timeline (time span of Answer Assist’s data):
  • per day
  • per week
  • per month
  • per any custom time period.



aa.gem_page.viewed

The aa.gem_page.viewed event is triggered when a Shelf Gem is viewed.


Event Properties 

Property name

Description

eventId

Unique Identifier for the event record

accountId

Unique account identifier for the Shelf Instance. This ID can be found in your Shelf instance at the following path: Admin Panel > Account Overview. Additionally this ID can be retrieved by the Get Account Information API call

eventCreatedAt

Date Timestamp of the event

eventName

Event Name (e.g. aa.gem_page.viewed)

userId

Unique ID of the Shelf user. Additional Shelf User information can be retrieved using the List Account Users API. 

gemId

ID of the Shelf Gem that has been displayed. Additional Gem Information can be retrieved using the Get gem information API

sessionId

Unique session identifier used to group all subsequent session usage events together


Example Event Properties

{
   "node": {
      "eventId": "dac531f2-f4f7-4d7c-a99d-...",
      "accountId": "QTRZ4...",
      "eventCreatedAt": "2021-11-29T20:47:15.121Z",
      "eventName": "aa.gem_page.viewed",
      "userId": "dfcf28f4-e32b-4bc2-964a-...",
      "gemId": "3c996736-6477-41e2-b008-...",
      "sessionId": "01FNXRG7JN5DQ6YVQ0S03XR661"
    },
    "cursor": "ZGFjNTMxZ..."
}


Example of answers that can be received using the data fetched from the Insights API 

  • Total number of Gem views
  • Average number of Gem views
  • Most popular Gems among agents
  • List of active agents that view Gems in Answer Assist to handle customers’ issues.

Slices (specific portions of Answer Assist’s data): 
  • per account
  • per agent
  • per session 

Timeline (time span of Answer Assist’s data):
  • per day
  • per week
  • per month
  • per any custom time period.



aa.gem_page.copied_to_clipboard

This event is triggered when an Agent has copied the specific text chunk once reviewing Gem in the Gem tab.


Event Properties

Property name

Description

eventId

Unique Identifier for the event record

accountId

Unique account identifier for the Shelf Instance. This ID can be found in your Shelf instance at the following path: Admin Panel > Account Overview. Additionally this ID can be retrieved by the Get Account Information API call

eventCreatedAt

Date Timestamp of the event

eventName

Event Name (e.g. aa.gem_page.copied_to_clipboard)

userId

Unique ID of the Shelf user. Additional Shelf User information can be retrieved using the List Account Users API. 

sessionId

Unique session identifier used to group all subsequent session usage events together

gemId

ID of the Shelf Gem that has been displayed. Additional Gem Information can be retrieved using the Get gem information API


Example Event Properties 

{
   "node": {
      "eventId": "dac531f2-f4f7-4d7c-a99d-...",
      "accountId": "QTRZ4...",
      "eventCreatedAt": "2023-01-19T10:52:15.121Z",
      "eventName": "aa.gem_page.copied_to_clipboard",
      "userId": "dfcf28f4-e32b-4bc2-964a-...",
      "sessionId": "01FNXRG7JN5DQ6YVQ0S03XR661",

      "gemId": "3c996736-6477-41e2-b008-..."
    },
    "cursor": "ZGFjNTMxZ..."
}


Example of answers that can be received using the data fetched from the Insights API 

  • Total number of copies from Gems
  • Average number of copies from Gems
  • Most popular Gems being copied
  • List of agents that copied text chunks from Gems in Answer Assist to handle customers’ issues.

Slices (specific portions of Answer Assist’s data): 
  • per account
  • per agent
  • per session 

Timeline (time span of Answer Assist’s data):
  • per day
  • per week
  • per month
  • per any custom time period.



aa.gem_page.sent_to_chat

This event is triggered when an Agent has sent the selected text chunk from the Gem being reviewed in the Gem tab to the chat with a customer.


Event Properties

Property name

Description

eventId

Unique Identifier for the event record

accountId

Unique account identifier for the Shelf Instance. This ID can be found in your Shelf instance at the following path: Admin Panel > Account Overview. Additionally this ID can be retrieved by the Get Account Information API call

eventCreatedAt

Date Timestamp of the event

eventName

Event Name (e.g. aa.gem_page.sent_to_chat)

userId

Unique ID of the Shelf user. Additional Shelf User information can be retrieved using the List Account Users API. 

sessionId

Unique session identifier used to group all subsequent session usage events together

gemId

ID of the Shelf Gem that has been displayed. Additional Gem Information can be retrieved using the Get gem information API


Example Event Properties 

{
   "node": {
      "eventId": "dac531f2-f4f7-4d7c-a99d-...",
      "accountId": "QTRZ4...",
      "eventCreatedAt": "2023-01-19T10:56:13.141Z",
      "eventName": "aa.gem_page.sent_to_chat",
      "userId": "dfcf28f4-e32b-4bc2-964a-...",
      "sessionId": "01FNXRG7JN5DQ6YVQ0S03XR661",

      "gemId": "3c996736-6477-41e2-b008-..."
    },
    "cursor": "ZGFjNTMxZ..."
}


Example of answers that can be received using the data fetched from the Insights API 

  • Total number of the selected Gem’s text chunk sendings
  • Average number of the selected Gem’s text chunk sendings
  • Most popular Gems from which the selected Gem’s text chunk has been sent
  • List of agents that sent text chunks from Gems in Answer Assist to handle customers’ issues.

Slices (specific portions of Answer Assist’s data): 
  • per account
  • per agent
  • per session 

Timeline (time span of Answer Assist’s data):
  • per day
  • per week
  • per month
  • per any custom time period.



aa.gem_page.favorited

This event is triggered when an Agent has added the Gem being reviewed in the Gem tab to Favorites.


Event Properties

Property name

Description

eventId

Unique Identifier for the event record

accountId

Unique account identifier for the Shelf Instance. This ID can be found in your Shelf instance at the following path: Admin Panel > Account Overview. Additionally this ID can be retrieved by the Get Account Information API call

eventCreatedAt

Date Timestamp of the event

eventName

Event Name (e.g. aa.gem_page.favorited)

userId

Unique ID of the Shelf user. Additional Shelf User information can be retrieved using the List Account Users API. 

sessionId

Unique session identifier used to group all subsequent session usage events together

gemId

ID of the Shelf Gem that has been displayed. Additional Gem Information can be retrieved using the Get gem information API


Example Event Properties 

{
   "node": {
      "eventId": "dac531f2-f4f7-4d7c-a99d-...",
      "accountId": "QTRZ4...",
      "eventCreatedAt": "2023-01-19T10:59:23.111Z",
      "eventName": "aa.gem_page.favorited",
      "userId": "dfcf28f4-e32b-4bc2-964a-...",
      "sessionId": "01FNXRG7JN5DQ6YVQ0S03XR661",

      "gemId": "3c996736-6477-41e2-b008-..."
    },
    "cursor": "ZGFjNTMxZ..."
}


Example of answers that can be received using the data fetched from the Insights API 

  • Total number of Gem favoriting operations
  • Average number of Gem favoriting operations
  • Most favorited Gems 
  • List of agents that favorited Gems

Slices (specific portions of Answer Assist’s data): 
  • per account
  • per agent
  • per session 

Timeline (time span of Answer Assist’s data):
  • per day
  • per week
  • per month
  • per any custom time period.



aa.gem_page.share

This event is triggered when an Agent has publicly shared the Gem being reviewed in the Gem tab (given the Public Share feature is enabled for this Account).


Event Properties

Property name

Description

eventId

Unique Identifier for the event record

accountId

Unique account identifier for the Shelf Instance. This ID can be found in your Shelf instance at the following path: Admin Panel > Account Overview. Additionally this ID can be retrieved by the Get Account Information API call

eventCreatedAt

Date Timestamp of the event

eventName

Event Name (e.g. aa.gem_page.share)

userId

Unique ID of the Shelf user. Additional Shelf User information can be retrieved using the List Account Users API. 

sessionId

Unique session identifier used to group all subsequent session usage events together

gemId

ID of the Shelf Gem that has been displayed. Additional Gem Information can be retrieved using the Get gem information API


Example Event Properties 

{
   "node": {
      "eventId": "dac531f2-f4f7-4d7c-a99d-...",
      "accountId": "QTRZ4...",
      "eventCreatedAt": "2023-01-19T11:03:28.231Z",
      "eventName": "aa.gem_page.share",
      "userId": "dfcf28f4-e32b-4bc2-964a-...",
      "sessionId": "01FNXRG7JN5DQ6YVQ0S03XR661",

      "gemId": "3c996736-6477-41e2-b008-..."
    },
    "cursor": "ZGFjNTMxZ..."
}


Example of answers that can be received using the data fetched from the Insights API 

  • Total number of Gem public share operations
  • Average number of Gem public share operations
  • Gems most shared publicly
  • List of agents that shared Gems publicly.

Slices (specific portions of Answer Assist’s data): 
  • per account
  • per agent
  • per session 

Timeline (time span of Answer Assist’s data):
  • per day
  • per week
  • per month
  • per any custom time period.



aa.gem_page.opened_in_shelf

This event is triggered when an Agent has clicked to open the Gem in Shelf and proceeded to work with the Gem there.


Event Properties 

Property name

Description

eventId

Unique Identifier for the event record

accountId

Unique account identifier for the Shelf Instance. This ID can be found in your Shelf instance at the following path: Admin Panel > Account Overview. Additionally this ID can be retrieved by the Get Account Information API call

eventCreatedAt

Date Timestamp of the event

eventName

Event Name (e.g. aa.gem_page.opened_in_shelf)

userId

Unique ID of the Shelf user. Additional Shelf User information can be retrieved using the List Account Users API. 

sessionId

Unique session identifier used to group all subsequent session usage events together

gemId

ID of the Shelf Gem that has been displayed. Additional Gem Information can be retrieved using the Get gem information API


Example Event Properties

{
   "node": {
      "eventId": "dac531f2-f4f7-4d7c-a99d-...",
      "accountId": "QTRZ4...",
      "eventCreatedAt": "2023-01-19T11:07:45.241Z",
      "eventName": "aa.gem_page.opened_in_shelf",
      "userId": "dfcf28f4-e32b-4bc2-964a-...",
      "sessionId": "01FNXRG7JN5DQ6YVQ0S03XR661",

      "gemId": "3c996736-6477-41e2-b008-..."
    },
    "cursor": "ZGFjNTMxZ..."
}


Example of answers that can be received using the data fetched from the Insights API 

  • Total number of Gem openings from Answer Assist in Shelf
  • Average number of Gem openings from Answer Assist in Shelf
  • Most opened Gems from Answer Assist in Shelf
  • List of agents that opened Gems from Answer Assist in Shelf.

Slices (specific portions of Answer Assist’s data): 
  • per account
  • per agent
  • per session 

Timeline (time span of Answer Assist’s data):
  • per day
  • per week
  • per month
  • per any custom time period.



aa.search.applied

This event is triggered when a search is performed in the Search tab.



Event Properties

Property name

Description

eventId

Unique Identifier for the event record

accountId

Unique account identifier for the Shelf Instance. This ID can be found in your Shelf instance at the following path: Admin Panel > Account Overview. Additionally this ID can be retrieved by the Get Account Information API call

eventCreatedAt

Date Timestamp of the event

eventName

Event Name (e.g. aa.search.applied)

userId

Unique ID of the Shelf user. Additional Shelf User information can be retrieved using the List Account Users API. 

tab

The Answer Assist tab from which events originated. Possible values include  'search'

extInteractionId

Interaction ID from the platform where Answer Assist is integrated

sessionId

Unique session identifier used to group all subsequent session usage events together

extAgentId

Agent ID taken from the platform where Answer Assist is integrated

extParticipantId

Participant ID (from the platform where Answer Assist is integrated) where purpose = customer


Example Event Properties 

{
   "node": {
      "accountId": "QTRZ4...",
      "eventId": "b3a65adc-ff9f-475b-a0cb-...",
      "eventCreatedAt": "2023-01-04T15:01:37.749Z",
      "eventName": "aa.search.applied",
      "userId": "dc018fdc-66a5-4a4a-93f9-...",
      "tab": "search",
      "extInteractionId": "3907d702-4943-49d8-a3f7-...",
      "sessionId": "01FNXT9WBCTCKT858ZS21N3M70",
      "extAgentId": "ce44e479-54a2-40d3-b7a0-...",
      "extParticipantId": "221355d6-92ac-4b13-..."
    },
    "cursor": "ZGFjNTMxZ..."
}


Example of answers that can be received using the data fetched from the Insights API 

  • Total number of searches 
  • Average number of searches
  • List of agents that executed searches in Answer Assist

Slices (specific portions of Answer Assist’s data): 
  • per account
  • per agent
  • per session 

Timeline (time span of Answer Assist’s data):
  • per day
  • per week
  • per month
  • per any custom time period.



aa.search.results_clicked

This event is triggered when Agent has selected a Gem of interest to be reviewed from search results


Event Properties 

Property name

Description

eventId

Unique Identifier for the event record

accountId

Unique account identifier for the Shelf Instance. This ID can be found in your Shelf instance at the following path: Admin Panel > Account Overview. Additionally this ID can be retrieved by the Get Account Information API call

eventCreatedAt

Date Timestamp of the event

eventName

Event Name (e.g. aa.search.results_clicked)

userId

Unique ID of the Shelf user. Additional Shelf User information can be retrieved using the List Account Users API. 

gemId

ID of the Shelf Gem that has been displayed. Additional Gem Information can be retrieved using the Get gem information API

sessionId

Unique session identifier used to group all subsequent session usage events together


Example Event Properties

{
   "node": {
      "eventId": "dac531f2-f4f7-4d7c-a99d-...",
      "accountId": "QTRZ4...",
      "eventCreatedAt": "2023-01-16T11:47:12.121Z",
      "eventName": "aa.search.results_clicked",
      "userId": "dfcf28f4-e32b-4bc2-964a-...",
      "gemId": "3c996736-6477-41e2-b008-...",
      "sessionId": "01FNXRG7JN5DQ6YVQ0S03XR661"
    },
    "cursor": "ZGFjNTMxZ..."
}


Example of answers that can be received using the data fetched from the Insights API 

  • Total number of clicks on search results offered
  • Average number of clicks on search results offered
  • Most opened Gems from search results.

Slices (specific portions of Answer Assist’s data): 
  • per account
  • per agent
  • per session 

Timeline (time span of Answer Assist’s data):
  • per day
  • per week
  • per month
  • per any custom time period.



aa.announcement.opened

This event is triggered when an Agent has selected an Announcement of interest from the list to review.


Event Properties

Property name

Description

eventId

Unique Identifier for the event record

accountId

Unique account identifier for the Shelf Instance. This ID can be found in your Shelf instance at the following path: Admin Panel > Account Overview. Additionally this ID can be retrieved by the Get Account Information API call

eventCreatedAt

Date Timestamp of the event

eventName

Event Name (e.g. aa.announcement.opened)

userId

Unique ID of the Shelf user. Additional Shelf User information can be retrieved using the List Account Users API. 

announcementId

Unique ID of the announcement

sessionId

Unique session identifier used to group all subsequent session usage events together


Example Event Properties

{
   "node": {
      "accountId": "QTRZ4...",
      "eventId": "b3a65adc-ff9f-475b-a0cb-...",
      "eventCreatedAt": "2023-01-01T15:06:37.749Z",
      "eventName": "aa.announcement.opened",
      "userId": "dc018fdc-66a5-4a4a-93f9-...",
      "announcementId": "5407d702-4321-49d8-a3f7-...",
      "sessionId": "01FNXT9WBCTCKT858ZS21N3M70"
    },
    "cursor": "ZGFjNTMxZ..."
}


Example of answers that can be received using the data fetched from the Insights API 

  • Total number of announcement opening from Answer Assist
  • Average number of announcement opening from Answer Assist
  • Most opened announcements from Answer Assist
  • List of agents that opened announcements from Answer Assist.

Slices (specific portions of Answer Assist’s data): 
  • per account
  • per agent
  • per session 

Timeline (time span of Answer Assist’s data):
  • per day
  • per week
  • per month
  • per any custom time period.



aa.answer.feedback

This event is triggered when an Agent has left the reaction (thumb up or down) on the Gem being suggested to them in the Suggestions tab based on the context mapped.


Event Properties

Property name

Description

eventId

Unique Identifier for the event record

accountId

Unique account identifier for the Shelf Instance. This ID can be found in your Shelf instance at the following path: Admin Panel > Account Overview. Additionally this ID can be retrieved by the Get Account Information API call

eventCreatedAt

Date Timestamp of the event

eventName

Event Name (e.g. aa.answer.feedback)

userId

Unique ID of the Shelf user. Additional Shelf User information can be retrieved using the List Account Users API. 

sessionId

Unique session identifier used to group all subsequent session usage events together

gemId

ID of the Shelf Gem that has been displayed. Additional Gem Information can be retrieved using the Get gem information API

origin

Suggestion origin of the provided feedback. Possible values include: 'context-suggestions' 

kind

Kind of the provided feedback. Possible values include: 'good'|'bad'

intent

Unique code for the system combination of the intentGroupId and intent used during context mapping

intentGroupId

Group ID for several intents gathered by some criteria (eg by market, specific topic, interaction channel etc.)


Example Event Properties 

{
   "node": {
      "accountId": "QTRZ4...",
      "eventId": "b3a65adc-ff9f-475b-a0cb-...",
      "eventCreatedAt": "2023-01-01T15:06:37.749Z",
      "eventName": "aa.answer.feedback",
      "userId": "dc018fdc-66a5-4a4a-93f9-...",
      "sessionId": "01FNXT9WBCTCKT858ZS21N3M70"

      "gemId": "5407d702-4321-49d8-a3f7-...",

      "origin": "context-suggestions",

      "kind": "bad",

      "intent": "321Intent231",

      "intentGroupId": "98IF-1346-IBF8"
    },
    "cursor": "ZGFjNTMxZ..."
}


Example of answers that can be received using the data fetched from the Insights API 

  • Total number of feedbacks provided on context suggestions
  • Average number of feedbacks provided on context suggestions
  • Gems from context suggestions that received the best feedback
  • Gems from context suggestions that received the worst feedback
  • List of agents that provided feedback on context suggestions.

Slices (specific portions of Answer Assist’s data): 
  • per account
  • per agent
  • per session 
  • per intent
  • per intent group ID

Timeline (time span of Answer Assist’s data):
  • per day
  • per week
  • per month
  • per any custom time period.



aa.answer.sent_to_chat

This event is triggered when an Agent clicks the Send to Chat button which sends a suggestion directly to the Chat interaction.


Event Properties

Property name

Description

eventId

Unique Identifier for the event record

accountId

Unique account identifier for the Shelf Instance. This ID can be found in your Shelf instance at the following path: Admin Panel > Account Overview. Additionally this ID can be retrieved by the Get Account Information API call

eventCreatedAt

Date Timestamp of the event

eventName

Event Name (e.g. aa.answer.sent_to_chat)

userId

Unique ID of the Shelf user. Additional Shelf User information can be retrieved using the List Account Users API. 

gemId

ID of the Shelf Gem that has been displayed. Additional Gem Information can be retrieved using the Get gem information API

tab

The Answer Assist tab from which view events originated. Possible values include  'suggestions'

extInteractionId

Interaction ID from the platform where Answer Assist is integrated

sessionId

Unique session identifier used to group all subsequent session usage events together

extAgentId

Agent ID taken from the platform where Answer Assist is integrated

extParticipantId

Participant ID (from the platform where Answer Assist is integrated) where purpose = customer


Example Event Properties 

{
   "node": {
      "accountId": "QTRZ4...",
      "eventId": "b3a65adc-ff9f-475b-a0cb-...",
      "eventCreatedAt": "2023-01-02T15:01:37.749Z",
      "eventName": "aa.answer.sent_to_chat",
      "userId": "dc018fdc-66a5-4a4a-93f9-...",
      "gemId": "3c996736-6477-41e2-b008-...",
      "tab": "suggestions",
      "extInteractionId": "3907d702-4943-49d8-a3f7-...",
      "sessionId": "01FNXT9WBCTCKT858ZS21N3M70",
      "extAgentId": "ce44e479-54a2-40d3-b7a0-...",
      "extParticipantId": "221355d6-92ac-4b13-..."

    },
    "cursor": "ZGFjNTMxZ..."
}


Example of answers that can be received using the data fetched from the Insights API 

  • Total number of submissions of FAQ answers provided as Answer Assist suggestions to chat with customers
  • Average number of submissions of FAQ answers provided as Answer Assist suggestions to chat with customers
  • Most popular FAQ Gem sent to customers
  • List of agents that sent FAQ answers provided as Answer Assist suggestions to customers.

Slices (specific portions of Answer Assist’s data): 
  • per account
  • per agent
  • per session 

Timeline (time span of Answer Assist’s data):
  • per day
  • per week
  • per month
  • per any custom time period.



aa.answer.copied_to_clipboard

This event is triggered when an Agent copies the answer to the clipboard.


Event Properties

Property name

Description

eventId

Unique Identifier for the event record

accountId

Unique account identifier for the Shelf Instance. This ID can be found in your Shelf instance at the following path: Admin Panel > Account Overview. Additionally this ID can be retrieved by the Get Account Information API call

eventCreatedAt

Date Timestamp of the event

eventName

Event Name (e.g. aa.answer.copied_to_clipboard)

userId

Unique ID of Shelf user. Additional Shelf User information can be retrieved using the List Account Users API. 

gemId

ID of the Shelf Gem that has been displayed. Additional Gem Information can be retrieved using the Get gem information API

tab

The Answer Assist tab from which view events originated. Possible values include  'suggestions'

extInteractionId

Interaction ID from the platform where Answer Assist is integrated

sessionId

Unique session identifier used to group all subsequent session usage events together

extAgentId

Agent ID taken from the platform where Answer Assist is integrated

extParticipantId

Participant ID (from the platform where Answer Assist is integrated) where purpose = customer


Example Event Properties 

{
   "node": {
      "accountId": "QTRZ4...",
      "eventId": "b3a65adc-ff9f-475b-a0cb-...",
      "eventCreatedAt": "2023-01-07T12:08:37.749Z",
      "eventName": "aa.answer.copied_to_clipboard",
      "userId": "dc018fdc-66a5-4a4a-93f9-...",
      "gemId": "3c996736-6477-41e2-b008-...",
      "tab": "suggestions",
      "extInteractionId": "3907d702-4943-49d8-a3f7-...",
      "sessionId": "01FNXT9WBCTCKT858ZS21N3M70",
      "extAgentId": "ce44e479-54a2-40d3-b7a0-...",
      "extParticipantId": "221355d6-92ac-4b13-..."
    },
    "cursor": "ZGFjNTMxZ..."
}


Example of answers that can be received using the data fetched from the Insights API 

  • Total number of copyings of FAQ answers provided as Answer Assist suggestions to chat with customers
  • Average number of copyings of FAQ answers provided as Answer Assist suggestions to chat with customers
  • Most popular FAQ Gem copied to chat with customers
  • List of agents that copied FAQ answers provided as Answer Assist suggestions to chat with customers.

Slices (specific portions of Answer Assist’s data): 
  • per account
  • per agent
  • per session 

Timeline (time span of Answer Assist’s data):
  • per day
  • per week
  • per month
  • per any custom time period.