Analytics API Tutorial

Introduction

Our Analytics JSON APIs allows you to easily integrate Userlike with your favorite third-party tracking software, CRM, or your own custom tracking solutions. Each API provides a download interface for all our tracked Analytics events, allowing you to enhance our data with your own. Also, you can create customized reports that incorporate your company setup or build aggregations and generate new insights by combining multiple data vectors. Below you find our general documentation as well as a detailed description of each API resource available. Please note that based on the timeouts defined for chats, some events might appear in your API requests with a short delay.

We prepared some cURL-based examples. With the help of the cURL tool you can test drive our API quickly from the command line. This should give you a straightforward understanding how to use our API.

TopicDescription
Resource endpointsAvailable resource endpoints of the Analytics JSON API
AuthenticationAccessing the API
Request headersAdditional request headers
Rate limitsAPI rate limits
Result filteringFilter list endpoints for specific resource items
Result typeThe data point format of each resource
ResourcesEndpoint return values
Resource detailsDetails for respective endpoint
Code samplesWorking (Python) code examples

Resource endpoints

Currently, the following resource endpoints are available via the Analytics JSON API:
https://api.userlike.com

Resource endpointsDescriptionAllowed methods
/api/um/analytics/um_conversation_first_message/Received first message in a conversationGET
/api/um/analytics/um_conversation_duration/Conversation duration, guaranteed to be unique per conversationGET
/api/um/analytics/um_chat_messages_total/Number of messages sent and received in a conversation sessionGET
/api/um/analytics/um_chat_messages_ct/Messages sent in a conversation sessionGET
/api/um/analytics/um_chat_messages_co/Messages received in a conversation sessionGET
/api/um/analytics/um_operator_status/Change of operator statusGET
/api/um/analytics/um_operator_slot_usage/Operator chat slot utilizationGET
/api/um/analytics/um_operator_response_time_first/First response time in a conversation sessionGET
/api/um/analytics/um_operator_response_time_first_service_time/First response time in a conversation session (service times considered)GET
/api/um/analytics/um_operator_response_time_conversation_first/First response time in the first session of a conversationGET
/api/um/analytics/um_operator_response_time_conversation_first_service_time/First response time in the first session of a conversation (service times considered)GET
/api/um/analytics/um_operator_response_time/Response times per operatorGET
/api/um/analytics/um_operator_response_time_service_time/Response times per operator (service times considered)GET
/api/um/analytics/um_operator_response_time_to_unanswered_session_first/First response time in an unanswered conversation session with no previous operator messagesGET
/api/um/analytics/um_operator_response_time_to_unanswered_session_first_service_time/First response time in an unanswered conversation session with no previous operator messages (service times considered)GET
/api/um/analytics/um_operator_response_time_to_unanswered_session/Response time in any unanswered conversation sessionGET
/api/um/analytics/um_operator_response_time_to_unanswered_session_service_time/Response time in any unanswered conversation session (service times considered)GET
/api/um/analytics/um_conversation_rating/A contact leaves a conversation rating, the actual value will be returnedGET
/api/um/analytics/um_conversation_feedback/A contact leaves feedbackGET
/api/um/analytics/um_conversation_unanswered_live/A live conversation reaches the timeout without an operator’s replyGET
/api/um/analytics/um_conversation_unanswered_ended/A conversation ends without without a single operator messageGET
/api/um/analytics/um_conversation_goal_reached/A conversation goal is reachedGET
/api/um/analytics/um_missed_opportunity/A contact tries to start a new conversation while no operator is availableGET
/api/um/analytics/um_conversation_topic/A topic or a combination of topics is changed for a conversationGET
/api/um/analytics/um_conversation_topic_change/Topic(s) were changed for a conversationGET
/api/um/analytics/um_conversation_pre_survey/A pre-conversation survey is answeredGET
/api/um/analytics/um_conversation_post_survey/A post-conversation survey is answeredGET
/api/um/analytics/um_contact_unique_visit/A unique visitor is identified via cookie and starts a conversationGET
/api/um/analytics/um_contact_country/A contact starts or resumes a conversation, their country is tracked onceGET
/api/um/analytics/um_contact_browser/A contact starts or resumes a conversation, their browser is tracked onceGET
/api/um/analytics/um_contact_response_time_backchannel/Contact response time to offline replies from operatorsGET
/api/um/analytics/um_contact_response_time_backchannel_service_time/Contact response time to offline replies from operators (service times considered)GET
/api/um/analytics/um_conversation_category/A conversation starts, its status is tracked based on the availability status of operator and contactGET

You find the specifics of each resource further below, after our introduction of the Analytics JSON API’s general features.

API versioning

Currently we only offer one version of our Analytics JSON API: /v1/

You can access all endpoints as described above, without version scheme, or by explicitly using the version in the URLs like this:

/api/um/v1/analytics/um_conversation_duration/
/api/um/v1/analytics/um_chat_messages_total/
/api/um/v1/analytics/um_conversation_first_message/
/api/um/v1/analytics/um_chat_messages_ct/
/api/um/v1/analytics/um_chat_messages_co/
/api/um/v1/analytics/um_operator_status/
/api/um/v1/analytics/um_operator_slot_usage/
/api/um/v1/analytics/um_operator_response_time_first/
/api/um/v1/analytics/um_operator_response_time_first_service_time/
/api/um/v1/analytics/um_operator_response_time_conversation_first/
/api/um/v1/analytics/um_operator_response_time_conversation_first_service_time/
/api/um/v1/analytics/um_operator_response_time/
/api/um/v1/analytics/um_operator_response_time_service_time/
/api/um/v1/analytics/um_operator_response_time_to_unanswered_session_first/
/api/um/v1/analytics/um_operator_response_time_to_unanswered_session_first_service_time/
/api/um/v1/analytics/um_operator_response_time_to_unanswered_session/
/api/um/v1/analytics/um_operator_response_time_to_unanswered_session_service_time/
/api/um/v1/analytics/um_conversation_rating/
/api/um/v1/analytics/um_conversation_feedback/
/api/um/v1/analytics/um_conversation_unanswered_live/
/api/um/v1/analytics/um_conversation_unanswered_ended/
/api/um/v1/analytics/um_conversation_goal_reached/
/api/um/v1/analytics/um_conversation_reopen/
/api/um/v1/analytics/um_missed_opportunity/
/api/um/v1/analytics/um_conversation_topic/
/api/um/v1/analytics/um_conversation_topic_change/
/api/um/v1/analytics/um_conversation_pre_survey/
/api/um/v1/analytics/um_conversation_post_survey/
/api/um/v1/analytics/um_contact_unique_visit/
/api/um/v1/analytics/um_contact_country/
/api/um/v1/analytics/um_contact_browser/
/api/um/v1/analytics/um_contact_response_time/
/api/um/v1/analytics/um_contact_response_time_service_time/
/api/um/v1/analytics/um_conversation_category/

Future versions will be described here and follow the naming scheme "v{integer}", for example: /v2/. Endpoint URLs without version scheme will always default to the **latest** version.

Authentication

All API requests must be authenticated with an API token, that means the API token must be passed as an authorization header with each request:

Userlike offers two types of authentication tokens: the “customer authentication token,” allowing access to the resources of all organizations, and the “organization authentication token,” allowing access to the resources of a single organization.

Organization authentication token

The organization authentication token gives you access to the resources of Analytics data of a single organization. You find it in your Dashboard under **Config > API settings**:

Customer authentication token

The customer authentication token gives you access to the resources of Analytics data for all organizations. You find it in your Dashboard under **Company > API settings**:

API rate limits

You can send up to 320 API requests per minutes to our Analytics API. After the resource limit is reached, you’ll receive a response with HTTP status code 429 (too many requests).
https://api.userlike.com

Resource (per organization)Methodscombined requests/minute
/api/um/analytics/um_conversation_first_message/GET320
/api/um/analytics/um_conversation_duration/GET320
/api/um/analytics/um_chat_messages_total/GET320
/api/um/analytics/um_chat_messages_ct/GET320
/api/um/analytics/um_chat_messages_co/GET320
/api/um/analytics/um_operator_status/GET320
/api/um/analytics/um_operator_slot_usage/GET320
/api/um/analytics/um_operator_response_time_first/GET320
/api/um/analytics/um_operator_response_time_first_service_time/GET310
/api/um/analytics/um_operator_response_time_conversation_first/GET320
/api/um/analytics/um_operator_response_time_conversation_first_service_time/GET310
/api/um/analytics/um_operator_response_time/GET320
/api/um/analytics/um_operator_response_time_service_time/GET320
/api/um/analytics/um_operator_response_time_to_unanswered_session_first/GET320
/api/um/analytics/um_operator_response_time_to_unanswered_session_first_service_time/GET320
/api/um/analytics/um_operator_response_time_to_unanswered_session/GET320
/api/um/analytics/um_operator_response_time_to_unanswered_session_service_time/GET320
/api/um/analytics/um_conversation_rating/GET320
/api/um/analytics/um_conversation_feedback/GET320
/api/um/analytics/um_conversation_unanswered_live/GET320
/api/um/analytics/um_conversation_unanswered_ended/GET320
/api/um/analytics/um_conversation_inactivity_action/GET320
/api/um/analytics/um_conversation_goal_reached/GET320
/api/um/analytics/um_conversation_reopen/GET320
/api/um/analytics/um_missed_opportunity/GET320
/api/um/analytics/um_conversation_topic/GET320
/api/um/analytics/um_conversation_topic_change/GET320
/api/um/analytics/um_conversation_pre_survey/GET320
/api/um/analytics/um_conversation_post_survey/GET320
/api/um/analytics/um_contact_unique_visit/GET320
/api/um/analytics/um_contact_country/GET320
/api/um/analytics/um_contact_browser/GET320
/api/um/analytics/um_contact_response_time_backchannel/GET320
/api/um/analytics/um_contact_response_time_backchannel_service_time/GET320

Filtering

You can filter the results of each resource’s endpoint. The filters you choose apply to all resources. Here we’ll highlight the details of each Analytics filter.

Organization filter

By default, the resources returned by all Analytics endpoints are returned for all organizations.

Widget filter

By default, the resources returned by all Analytics endpoints are returned for all Widgets.

Operator filter

By default, the resources returned by all Analytics endpoints are returned for all operators.

Operator group filter

By default, the resources returned by all Analytics endpoints are returned for all operator groups.

Date and time filter

By default, the resources returned by all Analytics endpoints are returned for the current day. If only one of the date filters is used, it will default to that single day. The required format for all date filters is YYYY-mm-dd expected to be in UTC time zone.

If needed, the filters 'event_date_from' and 'event_date_to' can be enhanced with time filters in the format YYYY-mm-ddTHH:MM:SS.

Combining filters

You can also apply several filters to an API request. Just connect additional filters with an “and”, the selection will return all resource items that match each filter criterion.

The more filters you add, the more specific your request will be and chances are that there are no items matching all criteria.

Multiple keywords

You can search for multiple keywords in one request by providing the parameter with a white-space-separated value. Since you cannot use literal whitespaces in your request URLs, use one of the following encodings:

EncodingValueExample
"Percent" encoding%20?um_widget_id=3%204
"Plus" encoding+?um_widget_id=3+4

You can use multiple keywords by connecting them with a “+”. Still, they’ll follow an “or” logic, which means that a search for um_widget_id “3+4” will return results that match either the first **or** the second Widget ID:

Data point format

Each resource yields a list of data points in the following format:

KeyData typeRemarks
um_widget_idlist of numbers
organization_idnumber
operator_idnumberNot available for um_missed_opportunity
operator_group_idnumberNot available for um_missed_opportunity
timelist of numbers
valuenumberRelevance depends on accessed resource
value_strstringRelevance depends on accessed resource

Resources

ResourceDescription'value''value_str'Remarks
um_operator_statusOperator status changes, due to an explicit operator action or slot changeonline
slots_full
away
offline
Detailed expanations
um_operator_slot_usageAn operator’s number of occupied chat slots changesCurrent chat slot utilization of the operator in percentExact number of occupied slots and maximum number of slots set for the operator, in the form: 'current_slots':'total_slots'
um_conversation_topicLatest topic(s) set for a specific conversationIDs of set topic(s)Verbose names of topic(s)Counts only 1 event per conversation (the latest change)
um_conversation_pre_surveyA pre-conversation survey is answeredIndex ID of selected optionVerbose label of selected option
um_conversation_post_surveyA post-conversation survey is answeredIndex ID of selected optionVerbose label of selected option
um_contact_browserA contact’s browser is identified during a conversationBrowser identification
um_contact_countryA contact’s country is identified during a conversationCountry identification
um_conversation_durationThe duration of a conversation when it endsDuration in secondsMultiple events can occur if a conversation is resumed and ends again
um_conversation_first_messageThe first message in a conversation is sentMessage could be from operator or contact
um_conversation_ratingA contact rates a conversationRating value selected by contactOnly tracks the latest rating in a conversation
um_conversation_feedbackA contact leaves feedback in a conversation1Only tracks the occurrence of the feedback not its content
um_chat_messages_totalA message is sent or received in a conversationMessage countTracked at the end of a conversation session
um_chat_messages_ctAn operator sends a message in a conversation sessionMessage countTracked at the end of a conversation session
um_chat_messages_coCounts all messages received in a conversation sessionMessage countTracked at the end of a conversation session
um_conversation_unanswered_liveA live conversation session times out without an operator reply1Only tracks 1 event per conversation, even if the contact made another conversation attempt. Counts only if an operator was online, ignores slot status
um_conversation_unanswered_endedA conversation ends without an operator reply1Only tracks 1 event per conversation
um_conversation_inactivity_actionThe system triggers an inactivity prevention action for a conversation based on the Widget’s settings under **Chat > Behavior > Inactivity prevention**.1status_unassign
status_reassign_fail
status_reassign
active_notification
active_reassign_fail
active_reassign
offline_reassign_fail
offline_reassign
Detailed expanations
um_conversation_goal_reachedA conversation goal is reachedID of goal reachedName of the actual goal reached
um_conversation_reopenAn ended conversation is resumed1New status after conversation is resumed
um_missed_opportunityA contact tries to start a new conversation while no operator is available1ID of the relevant conversation as text value
um_contact_unique_visitA unique visitor is identified via cookie and starts a conversation1ID of the relevant conversation as text valueEvent is registered at the end of the conversation session
um_operator_response_time_firstThe first response time of an operator in a conversation sessionResponse time in secondsTracked at the first operator response
um_operator_response_time_first_service_timeThe first response time of an operator in a conversation session (service times considered)Response time in secondsTracked at the first operator response. Service time needs to be enabled.
um_operator_response_time_conversation_firstThe first response of an operator in the first session of a conversationResponse time in secondsTracked at the first operator response
um_operator_response_time_conversation_first_service_timeThe first response of an operator in the first session of a conversation (service times considered)Response time in secondsTracked at the first operator response. Service time needs to be enabled.
um_operator_response_timeResponse time of an operator in a conversation sessionResponse time in secondsTracked for all but the first operator response.
um_operator_response_time_service_timeResponse time of an operator in a conversation session (service times considered)Response time in secondsTracked for all but the first operator response. Service time needs to be enabled.
um_operator_response_time_to_unanswered_session_firstResponse time in the first session of a conversation started while no operator was availableResponse time in seconds
um_operator_response_time_to_unanswered_session_first_service_timeResponse time in the first session of a conversation started while no operator was available (service times considered)Response time in secondsService time needs to be enabled.
um_operator_response_time_to_unanswered_sessionResponse time in a conversation session started while no operator was availableResponse time in seconds
um_operator_response_time_to_unanswered_session_service_timeResponse time in a conversation session started while no operator was available (service times considered)Response time in secondsService time needs to be enabled.
um_conversation_categoryA conversation starts, its status is tracked based on the availability status of operator and contact1live
offline
re-engage
Detailed expanations
um_contact_response_time_backchannelResponse time of a contact to an asynchronous operator reply.Response time in seconds
um_contact_response_time_backchannel_service_timeResponse time of a contact to an asynchronous operator reply (service times considered)Response time in secondsService time needs to be enabled.

Resource Details

ResourceResource valueDescription
um_operator_statusonlineOperator is available and has open slots
um_operator_statusslots_fullOperator is available but all slots are full
um_operator_statusawayOperator is set to away
um_operator_statusofflineOperator is offline
um_conversation_inactivity_actionstatus_unassignAn offline conversation is automatically set to unassigned because no operator replied within the defined time.
um_conversation_inactivity_actionstatus_reassign_failAn offline conversation’s automatic reassignment fails, e.g. because no operator is available.
um_conversation_inactivity_actionstatus_reassignA new conversation does not receive a timely operator reply and is automatically reassigned to another operator.
um_conversation_inactivity_actionactive_notificationA new conversation does not receive a timely operator reply, therefore the **Inactivity message live** is sent to the contact.
um_conversation_inactivity_actionactive_reassign_failA conversation still does not receive a timely operator reply after the **Inactivity message live** is sent and cannot be reassigned to another operator.
um_conversation_inactivity_actionactive_reassignA new conversation does not receive a timely operator reply and is reassigned to another operator.
um_conversation_inactivity_actionoffline_reassign_failA contact replies to an existing conversation while the assigned operator is not available and the conversation cannot be reassigned to another operator.
um_operaum_conversation_inactivity_actiontor_statusoffline_reassignA contact replies to an existing conversation while the assigned operator is not available and the conversation is immediately reassigned to another operator.
um_conversation_categoryliveConversation is started by operator or contact while both are available
um_conversation_categoryofflineConversation is started by contact while operator is unavailable
um_conversation_categoryre-engageConversation is started by operator while contact is unavailable

Python examples

We prepared a few examples on how to access the Userlike Analytics API using Python. It’s pretty straightforward, we use the Python library “requests” for the HTTP requests, always adding the required Authorization headers.

More complex example: Calculate 'online', 'away', 'offline' durations for a single operator in a defined timeframe

This larger example shows you how to combine and interpret the data, to access individual operator IDs, please refer to JSON API tutorial