JSON API Tutorial

With Unified Messaging, we also upgraded our available JSON APIs - integrating Userlike into your own platforms and workflows has never been easier. Below you find the general documentation as well as a detailed description of each API resource available.

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.

Currently, the following resource endpoints are available using the Userlike JSON API:

The specifics for each resource are described further below, after the introduction of the general features of the JSON API.

Our APIs are constantly evolving, but we are striving to implement any new features in a backwards compatible way. If breaking changes are necessary, we will introduce a new API version. Examples for breaking changes are:

• Removing, renaming, or moving API entities.
• Changing or removing functionality.
• Making optional parameters or properties mandatory.

Non-breaking changes, like new endpoints or new optional properties, can happen anytime.
When we deprecate older versions of the API, we will provide at least 90 days of notice.

The current version of our JSON API is /v2/, which was released July 30th, 2021.

The previous version /v1/ is deprecated, but will remain available until at least November 1st, 2021.
You can find its documentation here: JSON API V1

The following changes were made with v2:

• The messages inside a conversation are no longer in the Single Conversation endpoint /api/um/v2/conversations/{id}/, the object returned there no longer has a transcript key. Instead there is a new Messages endpoint. Note that this endpoint uses cursor based pagination and allows a maxiumum of 100 messages per page.
• There is a new endpoint to access navigation events. Those happen whenever a contact navigates to a new URL, if this is enabled in the widget. In v1, those events were contained inside the transcript key of the objects returned by the Single Conversation endpoint /api/um/v2/conversations/{id}/.
• Objects returned by the Single Conversation endpoint /api/um/v2/conversations/{id}/ now have two new keys: contact_first_message_sent_at and contact_last_message_sent_at. They represent the first and the last time the contact interacted with the conversation, which means they sent a message, filled out a form or clicked on a button.
• The list of conversations returned by the Single Conversation endpoint /api/um/v2/conversations/{id}/ can be filtered and ordered by contact_first_message_sent_at and contact_last_message_sent_at.
• Objects returned by the Single Conversation endpoint /api/um/v2/conversations/{id}/ no longer have an ended_at key.
• The following filters are not available anymore for the Conversations endpoint /api/um/v2/conversations/: to_date, from_date, iso_to_date_time and iso_from_date_time.
• Endpoint URLs without versioning scheme, e.g. /api/um/conversations/, are aliases for the JSON API V1 endpoints and are deprecated.

All API requests must be authenticated with an API token, i.e. 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.

The organization authentication token gives you access to the resources (conversations, contacts, ...) of a single organization. You can find it in your Dashboard under **Account** > **API settings**:

The customer authentication token by default gives you access to the resources (conversations, contacts, ...) of your default organization. You can find it in your Dashboard under **Account** > **API settings**:

But when you need to access the resources of a different organization, you can now simply provide the extra header "Userlike-organization-Id" with your request, there indicating the ID of the desired organization:

To find the ID of one of your organizations, go to **Account** > **Organizations** and start editing the respective organization. In the URL bar you can now see the ID of the organization:

If you provide a wrong organization ID, the request will again be made against your default organization resources.

When you want to update existing resources, you have to send a PATCH request with a valid JSON body. Additionally, you must specify the content type of your request being "application/json" - otherwise your body data cannot be processed correctly.

By default, API requests run in the context of the account’s operator. If you want to limit the privileges of requests made via the JSON API without affecting the capabilities of the owner, you can make your requests in the context of a less privileged operator.

In these cases we’d recommend the creation of a dedicated API operator, to whom you then assign a (customized) role with the desired set of capabilities. For all API request you can now send this operator’s ID by setting the custom "Userlike-Operator-Id" header:

All requests made this way will check for your API operator’s capabilities before performing any actions. This way you could ensure, for example, that no destructive operations are allowed via the API. Here you learn more about roles and capabilities.

You can make up to 2000 API requests per day to a specific resource of an organization. After the resource limit is reached, you’ll receive a response with HTTP status code 429.

Each resource has its own limit, as does each organization. This means that requesting conversations of organization A does not affect the count for requesting contacts from the same organization - nor does it affect the count for requesting conversations of organization B. The following three example calls all add to a different call counter:

In this context, requests for a specific resource of an organization (e.g. conversations) all add to the same count, no matter if they are made to the list or single endpoint, or what HTTP method is used. So a "DELETE" of a single conversation adds a hit to the same counter as does a "GET" to the same organization’s conversation list endpoint. The following three example calls all add to the same call counter:

Most of our endpoint use limit offset pagination, the only exceptions are the conversation messages list and the navigation event list. By default you will get the 10 latest resource items that have been created. The result will also contain the total number of existing resource items, and provide links to the previous and next results page (if applicable).

To get the next 10 resource items, you can now simply make your next API call using the "next" link.

By default, we offer result pagination with a page size of 10 resource items. You can adapt the page size to your needs and return more or less resource items per API call:

And if you need to start at a specific offset, you can of course also provide that:

The maximum page size is 100 resource items. If you provide a limit larger than that, we will fallback to this limit. Also, if you provide an offset larger than the actual number of existing resource items, you will receive an empty result set.

You can filter the results of each resource’s list endpoint. These filters are specific to each resource, so we’ll explain them for each resource further below. Here we’ll only highlight some details that apply to filters in general.

Searching is really a special kind of filtering, available for the conversation and contact list endpoints. For each resource, certain fields will be searched and all matching results will be returned, ordered by a specific ranking. We will explain the individual fields and ranking for each resource below.

To search an endpoint for specific resources, simply add the "search_query" parameter to your request, followed by the search keyword:

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

Multiple keywords are "ORed", meaning that a search for "userlike+gregor" will return results that match either the first or the second keyword:

The ranking of all results matching your keyword(s) is determined by two factors: where the matching content was found and how often it was found. A match in a contact’s name ranks higher than a match in a contact’s notes, and three matches in one conversation rank higher than only one match in another.

The ranking of each resource’s search fields are described below.

When you provide a keyword, it is first reduced to its stem. After that we do a prefix search with the result. E.g. if you enter "users", we first reduce it to the word stem "user" and then do a prefix search with that. So it would return results for e.g. "userlike". Multiple keywords are all treated as prefixes as well:

Keep this in mind if your search returns too many (undesired) results, and provide more specific search keyword(s).

Fetch a list of conversations you had with your contacts. The response will return a JSON object with a results array, by default containing the last 10 conversations that were created. The response JSON further contains pagination details.

The conversation resource items returned by the list endpoint only contain the last message of the conversation. If you want to get all messages of a conversation, you must make a request to the conversation messages endpoint. We’ll show you how to do that further below.

Delete a list of conversations you had with your contacts. The response contains no data and has the HTTP status 204.

The conversation list endpoint lets you filter its resources for the following fields:

You can use these filters alone or in combination to extract exactly the resource items you need.

You can also use these filters to immediately delete the filtered resource items.

Make sure you also read the general remarks on result filtering.

The conversation list endpoint lets you search its resources by matching your search keyword(s) against certain data fields of or related to your conversations. If your keyword(s) match(es) any of the contents of the following fields, the respective conversation will be part of the result set:

We intentionally rank matches in the associated contacts' data higher than matches in the conversations' own content, since that data is much more structured and qualified.

You can also use the search feature to immediately delete the matching conversations:

Make sure you also read the general remarks on resource searching.

The conversation list endpoint results can be alternatively ordered by the following fields:

Make sure you also read the general remarks on result filtering.

Fetch a specific conversation you had with one of your contacts by providing its ID.

If you need the full conversation data for a specific set of conversations, first filter the resource items accordingly using the list endpoint. Then use the conversation IDs you get from the filtered result set to fetch the single resource items, which will contain the full data.

Delete a specific conversation you had with one of your contacts by providing its ID. Response contains no data and has HTTP status 204.

Fetch the messages for a specific conversation you had with one of your contacts by providing its ID. The response will return a JSON object with a results array, by default containing the last 100 messages that were created.

The conversation messages endpoint lets you filter its resources for the following fields:

You can use these filters alone or in combination to extract exactly the resource items you need.

Make sure you also read the general remarks on result filtering.

The conversation messages endpoint uses cursor based pagination with a maximum page size of 100 messages.

You can provide us with a message reference in the cursor query parameter and we will return messages that either come before or after the cursor, depending on which ordering query parameter you send.

Responses you receive will have a next-link and a previous-link with the correct cursor set, if there are messages in the conversation that come before or after the result list. The next and previous link in the response will always have the same page size as the request.

The conversation messages endpoint results can alternatively be ordered by the following fields:

Make sure you also read the general remarks on result filtering.

Fetch a list of notes. The response will return a JSON object with a results array, by default containing the last 10 notes that were created. The response JSON further contains pagination details.

There are two types of notes: notes on conversations and notes on contacts. Notes on conversations have a non-null conversation_id, while notes on contacts have a non-null contact_identity_id. To learn how to fetch the notes for a specific conversation or a specific contact, please see the section on filtering the note list endpoint.

The note list endpoint lets you filter its resources for the following fields:

Combining these filter would always result in an empty response, as notes either have a conversation_id or a contact_identity_id.

Make sure you also read the general remarks on result filtering.

The note list endpoint results are sorted by their ID, in descending order - meaning that the most recently created notes are coming first.

Fetch a specific note by providing its ID.

Delete a specific note by providing its ID. Response contains no data and has the HTTP status 204.

Fetch all navigation events that a contact triggered. You can either use the conversation_id query parameter to get all navigation events that happened during a specific conversation, or you can use the contact_identity_id query parameter to get all navigation navigation events a contact triggered. Please note that either conversation_id or contact_identity_id needs to be set.

The navigation events endpoint lets you filter its resources for the following fields:

Make sure you also read the general remarks on result filtering.

The default page size is 100, the maximum page size we allow is 1000. You can specify a custom page size by using the page_size query parameter. All results contain a count_earlier and count_later key, which tells you if you fetched all events available. In order to get a full list of navigation events, you can use the filters described above together with the ordering query parameter.

The navigation events endpoint results can alternatively be ordered by the following fields:

Make sure you also read the general remarks on result filtering.

Fetch a list of contacts. Returns a JSON object with a results array, by default containing the last 10 contacts that have been created. The response JSON further contains pagination details.

Delete a list of contacts. The response contains no data and has HTTP status 204.

The contact list endpoint lets you filter its resources for the following fields:

You can use these filters to extract exactly the resource items you need.

You can also use these filters to immediately delete the filtered resource items.

Make sure you also read the general remarks on result filtering.

The contact list endpoint lets you search its resources by matching your search keyword(s) against certain data fields of your contacts. If your keyword(s) match(es) any of the contents of the following fields, the respective contact will be part of the result set:

An example contact search:

You can also use the search feature to immediately delete the matching contacts:

Make sure you also read the general remarks on resource searching.

The contact list endpoint results can be alternatively ordered by the following fields:

Make sure you also read the general remarks on result filtering.

Fetch a specific contact by providing its ID. The returned JSON object contains the full contact representation.

Update certain data of a specific contact. The returned JSON object contains the full and updated contact.

The following fields can be updated:

You can update one or more of these fields with a single patch request.

In contrast to a single conversation, you can update nearly all fields of a contact via the API. This allows you to enrich your Userlike contacts with data from another CRM system you might have, for example.

Delete a specific contact by providing its ID. Response contains no data and has HTTP status 204.

In contrast to the other resources, the operator resource’s list endpoint does not offer bulk deletion. This is to prevent destructive API calls that could seriously affect the operation of your Userlike account.

Fetch a list of operators. Returns a JSON object with a results array, by default containing the last 10 operators that have been created, including their current chat slot utilization. The response JSON further contains pagination details.

The operator list endpoint lets you filter its resources for the following fields:

You can use these filters to extract exactly the resource items you need.

Make sure you also read the general remarks on result filtering.

The operator list endpoint results can be alternatively ordered by the following fields:

Make sure you also read the general remarks on result filtering.

Fetch a specific operator by providing its ID. The returned JSON object contains the full operator representation, including operator group and organization.

Make various changes to a specific operator.

You can use the PATCH method to update an operator’s out of office status or notification settings. The response will have the format of the slot view as described below.

The following fields can be updated:

You can update one or more of these fields with a single PATCH request.

You can toggle an operator’s availability between **online** and **away** by making a PATCH request. The response contains the operator’s slot data and has the HTTP status code 200.

Delete a specific operator by providing its ID. The response contains no data and has HTTP status 204.

Since deleting an operator can affect the operation of your Userlike account, we take some precautions to prevent you from causing serious harm when making a DELETE call.

We make sure that you do not accidentally:

• Delete the Owner of your Userlike account
• Delete the operator making the request (which in most cases is the Owner)
• Delete the last operator of an organization

When you make a call that would cause one of these actions, you’ll instead get a 403 status response, indicating your request was denied. In the JSON body you’ll find the details on why it was denied.

For single operator resource items, we offer an additional endpoint that only returns the specific operator’s slot data when making a GET request to it. Apart from that, all other requests behave exactly the same as those to the regular operator resource single endpoint.

Use this reduced "view" on a specific operator’s chat slot utilization if all you need is this subset of the operator’s data. For example, when you are using the JSON API to sync your operators' chat availability with an external support system.

The fields of an operator’s slot data are:

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

This basic example shows you how to retrieve the list of the latest 10 conversations you had with your customers with a small Python script.

This larger example shows you how to work with different endpoints and request types to fulfill a task.

Imagine the following use case: you want to automatically add phone numbers from your CRM to the contacts in Userlike.

For this, you first have to get the ID of each customer by filtering the contact resource endpoint with their email address. Then, you have to update the contacts by sending patch requests to each individual contact resource endpoint.