JSON

⚠️

This document describes v3 of the JSON API. V2 was recently disabled. For details please refer to our changelog.

Introduction

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.

Resource endpoints

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

Resource endpoints	Description	Allowed methods
`https://api.userlike.com/api/um/v3/conversations/` `https://api.userlike.com/api/um/v3/conversations/all/` `https://api.userlike.com/api/um/v3/conversations/{id}/` `https://api.userlike.com/api/um/v3/conversations/{id}/messages/`	List of conversations List of all conversations Single conversation Single conversation’s messages	GET \| DELETE GET GET \| DELETE GET
`https://api.userlike.com/api/um/v3/notes/` `https://api.userlike.com/api/um/v3/notes/{id}/`	List of notes Single note	GET \| POSTGET \| DELETE
`https://api.userlike.com/api/um/v3/navigation/`	List of navigation events	GET
`https://api.userlike.com/api/um/v3/contact_identities/` `https://api.userlike.com/api/um/v3/contact_identities/all/` `https://api.userlike.com/api/um/v3/contact_identities/{id}/`	List of contactsList of all contactsSingle contact	GET \| DELETEGETGET \| PATCH \| DELETE
`https://api.userlike.com/api/um/v3/operators/` `https://api.userlike.com/api/um/v3/operators/{id}/` `https://api.userlike.com/api/um/v3/operators/{id}/slots/` `https://api.userlike.com/api/um/v3/operators/{id}/away/`	List of operators Single operator Single operator’s slot data Single operator’s away status	GET GET \| PATCH \| DELETE GET PATCH

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

API versioning

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 /v3/, which was released July 15, 2022.

The previous version /v2/ was disabled in February 2023.

Changelog

To improve overall performance, we changed some things concerning the pagination of conversations and contact list endpoints. /v3/ was introduced on July 22, 2022. Changes applied with /v3/:

Limit maximum amount of conversations returned for GET request to the conversation list endpoint (/api/um/v3/conversations/) to 10,000Limit maximum amount of contacts returned for GET request to the contact list endpoint (/api/um/v3/contact_identities/) to 10,000Add new conversation all endpoint (/api/um/v3/conversations/all/) with cursor-based pagination that has no limit on the number of returned conversationsAdd new contact all endpoint (/api/um/v3/contact_identities/all/) with cursor-based pagination that has no limit on the number of returned contactsChange PATCH request schema for single endpoints. You can now pass data directly without wrapping it in '{"update: {..}}"'.Remove option to update operator away status on the single endpoint. There now is a new endpoint to do that: /api/um/v3/operators/{id}/away/

Authentication

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:

curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/conversations/"

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 (conversations, contacts, ...) of a single organization. You can find it in your Dashboard under Chat tools > API settings:

Customer authenticaton token

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:

javascript
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --header  "Userlike-Organization-Id: 3" \
     "https://api.userlike.com/api/um/v3/conversations/"

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.

Additional request headers

Content-Type: Required for post and patch requests

If you want to create a resource or update an existing one, you must specify the content type of your request as “application/json” and send a valid JSON body - otherwise your body data cannot be processed correctly. Use POST requests to create resources and PATCH requests to update existing ones.

javascript
# provide content-type header 'application/json' for POST requests
curl --request POST \
     --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --header "Content-Type: application/json" \
     "https://api.userlike.com/api/um/v3/notes/" \
     --data '{"contact_identity_id": 50670, "body": "Is highly interested in our new product."}'

# result is the created resource item
{created resource item}


# provide content-type header 'application/json' for PATCH requests
curl --request PATCH \
     --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --header "Content-Type: application/json" \
     "https://api.userlike.com/api/um/v3/conversations/{id}/" \
     --data '{"topics":["Support"]}'

# result is the updated resource item
{patched resource item}



# otherwise request body cannot be processed
curl --request PATCH
     --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/conversations/{id}/" \
     --data '{"topics":["Support"]}'

Userlike-Operator-ID: Switching operator context

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:

javascript
# provide a different operator to use in request
curl --request DELETE \
     --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --header "Userlike-Operator-Id: 152" \
     "https://api.userlike.com/api/um/v3/operators/150/" \

# provided operator lacks capability to delete operators
{
    "detail":"You do not have permission to perform this action."
}

# running the same request with the default operator (owner)
curl --request DELETE \
     --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/operators/150/" \

# operator was successfully deleted
HTTP/1.1 204 No Content

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.

API rate limits

Sustained throttling

You can make up to 5000 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:

javascript
# adds to default organization's conversation resource count
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/conversations/"

# adds to other organization's conversation resource count
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --header "Userlike-Organization-Id: 3" \
     "https://api.userlike.com/api/um/v3/conversations/"

# adds to default organization's contact resource count
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/contact_identities/"

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:

javascript
# GET list endpoint adds to organization's conversation resource count
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/conversations/"

# GET single endpoint adds to organization's conversation resource count
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/conversations/{id}/"

# PATCH single endpoint adds to organization's conversation resource count
curl --request PATCH  \
     --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --header "Content-Type: application/json" \
     "https://api.userlike.com/api/um/v3/conversations/{id}/" \
     --data '{"topics":["Support"]}'

Resource (per organization)	Methods	combined requests/day
`https://api.userlike.com/api/um/v3/conversations/https://api.userlike.com/api/um/v3/conversations/all/` `https://api.userlike.com/api/um/v3/conversations/{id}/`	GET \| DELETEGETGET \| PATCH \| DELETE	5000
`https://api.userlike.com/api/um/v3/contact_identities/https://api.userlike.com/api/um/v3/contact_identities/all/` `https://api.userlike.com/api/um/v3/contact_identities/{id}/`	GET \| DELETE GET GET \| PATCH \| DELETE	5000
`https://api.userlike.com/api/um/v3/navigation/`	GET	5000
`https://api.userlike.com/api/um/v3/operators/` `https://api.userlike.com/api/um/v3/operators/{id}/` `https://api.userlike.com/api/um/v3/operators/{id}/slots/` `https://api.userlike.com/api/um/v3/operators/{id}/away/`	GET GET \| PATCH \| DELETE GET PATCH	5000

Burst throttling

On top of that, you may experience burst throttling if you send too many requests in a short time period. In this case you will also get a 429 response. You will be able to make another API call after waiting a few seconds.

Pagination

Depending on the endpoint, we use either limit offset or cursor-based pagination. Our standard list endpoints for conversations and contacts use offset pagination and support various sorting options. For performance reasons we limited the total amount of results that those endpoints can return to 10,000 in the /v3/ API. For accessing all contacts or conversations of your organization we implemented new /all/ endpoints that use cursor-based pagination.

Offset pagination

Endpoints with offset pagination can return a maximum of 10,000 results, but offer more flexible sorting. 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).

javascript
# GET without parameters to conversations list endpoint
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/conversations/"

# result JSON - we are on page 1, so we only have a 'next' link
{
    "count": 63,
    "next": "https://api.userlike.com/api/um/v3/conversations/?limit=10&offset=10",
    "previous": null,
    "results": [
        {conversation object},
        ...
    ]
}

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

javascript
# GET call using the next link provided in first call
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/conversations/?limit=10&offset=10"

# result JSON - we are now on page 2 and have previous and next link
{
    "count": 63,
    "next": "https://api.userlike.com/api/um/v3/conversations/?limit=10&offset=20",
    "previous": "https://api.userlike.com/api/um/v3/conversations/?limit=10",
    "results": [
        {conversation object},
        ...
    ]
}

You can adapt the page size to your needs and return more or less resource items per API call:

javascript
# GET call using a custom limit
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/conversations/?limit=5"

# result JSON with first 5 items - the offset has been automatically adjusted
{
    "count": 63,
    "next": "https://api.userlike.com/api/um/v3/conversations/?limit=5&offset=5",
    "previous": null,
    "results": [
        {conversation object},
        ...
    ]
}

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

javascript
# GET call using a custom limit and offset
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/conversations/?limit=5&offset=7"

# result JSON with items 8 - 12 - previous and next links are adjusted
{
    "count": 63,
    "next": "https://api.userlike.com/api/um/v3/conversations/?limit=5&offset=12",
    "previous": "https://api.userlike.com/api/um/v3/conversations/?limit=5&offset=2",
    "results": [
        {conversation object},
        ...
    ]
}

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.

Cursor pagination

Our endpoints with cursor-based pagination always use plain IDs as cursors. You can provide us with a resource reference in the cursor query parameter and we will return resources 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 resources that come before or after the results list. The next and previous link in the response will always have the same page size as the request.

javascript
# get messages after message with reference "2015.2508.14032"
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/conversation/123/messages/?ordering=id&cursor=2015.2508.14032&limit=50"

# JSON data with results array and pagination info
# you will automatically get a link to access the 50 messages that come after the latest results in
# "next" and a link to access the 50 results that come before the first result in "previous"
{
    "next": "https://api.userlike.com/api/um/v3/conversation/123/messages/?cursor=2015.2508.14082&limit=50",
    "previous": "https://api.userlike.com/api/um/v3/conversation/123/messages/?cursor=-2015.2508.13900&limit=50",
    "results": [...]
}

Filtering

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.

Ordering filter

By default, the list of resources returned by all list endpoints are sorted by their ID, in descending order - meaning that the most recently created resources are coming first.

For some resource list endpoints, you can provide an alternative ordering by providing the field by which the result list should be ordered. Prefixing the ordering field with a "-" (minus) sign will reverse the order from "ascending" to "descending":

javascript
# order all contacts by email (ascending) instead of ID
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/contact_identities/?ordering=email"

# results 1-10, sorted by email (ascending)
{
    "count": 14,
    "next": "https://api.userlike.com/api/um/v3/contact_identities/?limit=10&offset=10&ordering=email",
    "previous": null,
    "results": [
        {conversation object},
        ...
    ]
}

# order all contacts by email (descending) instead of ID
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/contact_identities/?ordering=-email"

# results 1-10, sorted by email (descending)
{
    "count": 14,
    "next": "https://api.userlike.com/api/um/v3/contact_identities/?limit=10&offset=10&ordering=-email",
    "previous": null,
    "results": [
        {conversation object},
        ...
    ]
}

For each resource list endpoint we’ll indicate which fields are available for alternative ordering.

Filters and pagination

Applying filters to an API requests means that the pagination is applied to the filtered result set, and the previous and next links provided in a filtered response will already have these filter set. This means that you can easily browse the single pages of a filtered result set by following these links.

javascript
# filter all conversations for a certain operator
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/conversations/?operator_id=154"

# filtered results 1-10, with operator filter in 'next' link
{
    "count": 30,
    "next": "https://api.userlike.com/api/um/v3/conversations/?limit=10&offset=10&operator_id=154",
    "previous": null,
    "results": [
        {conversation object},
        ...
    ]
}

Combining filters

You can apply more than one filter to an API request. The single filters are "ANDed" together, i.e. they will return all resource items that match each filter criterion.

javascript
# filter all conversations for a certain operator and a certain contact
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/conversations/?operator_id=154&contact_uuid=MGEwYWJmZmEtN2M1OS01NGI2LWE2OWYtZWYxNDY4OWM0YWQ3"

# filtered results 1-10 that match both operator and contact
{
    "count": 10,
    "next": null,
    "previous": null,
    "results": [
        {conversation object},
        ...
    ]
}

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

javascript
# filter all conversations for a certain operator and a certain contact and a certain chat widget
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/conversations/?operator_id=154&contact_uuid=MGEwYWJmZmEtN2M1OS01NGI2LWE2OWYtZWYxNDY4OWM0YWQ3&chat_widget_id=3"

# empty result set
{
    "count": 0,
    "next": null,
    "previous": null,
    "results": []
}

Exclude IDs

For any requests, to any resource endpoints, you can provide a "blacklist" of resource IDs. Just provide a comma-separated string with all IDs you wish to exclude via the "exclude_ids" filter. Resource(s) thus specified will not be fetched, updated or deleted.

This allows for more effective bulk actions, e.g. fetching all conversations that are not assigned to one specific operator with only two API calls:

First you filter all conversation resources for the operator whose conversations you want to exclude, extracting the single conversation IDs from the result list. Then you make another call to the conversation list resource endpoint, providing this list of IDs to be excluded, as comma-separated value:

javascript
# get all conversations assigned to the provided Operator
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/conversations/?operator_id=16?limit=100"

# results 1-100 of conversations for specific Operator
{
    "count": 4,
    "next": null,
    "previous": null,
    "results": [
        {conversation object},
        ...
    ]
}

# extract Ids from results
# provide extracted Ids as comma-separated string, as 'exclude_ids'value
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/conversations/?exclude_ids=22,34,678,59"

# results 1-10 of all conversations that are not assigned to the Operator
{
    "count": 230,
    "next": "https://api.userlike.com/api/um/v3/conversations/?exclude_ids=22%2C134%2C678%2C59&limit=10&offset=10",
    "previous": null,
    "results": [
        {conversation object},
        ...
    ]
}

Delete IDs

For DELETE requests to list endpoints, you can provide a "whitelist" of resource IDs. Just provide a comma-separated string with all IDs you wish to delete via the "delete_ids" filter. Only the resource(s) thus specified will be deleted.

This allows for safer bulk delete actions, since only the specified IDs will be deleted, no matter what other filters or limits are provided:

javascript
# delete these specific conversations
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --request DELETE \
     "https://api.userlike.com/api/um/v3/conversations/?delete_ids=154,153,2"

# no result data - expected response status
HTTP/1.1 204 No Content

Searching

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:

javascript
# search all contacts for the term "userlike"
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/contact_identities/?search_query=userlike"

# results 1-10, ordered by search ranking, with pagination applied
{
    "count": 14,
    "next": "https://api.userlike.com/api/um/v3/contact_identities/?limit=10&offset=10&search_query=userlike",
    "previous": null,
    "results": [
        {conversation object},
        ...
    ]
}

Multiple keywords

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:

Encoding	Value	Example
"Percent" encoding	`%20`	`?search_query=userlike%20gregor`
"Plus" encoding	`+`	`?search_query=userlike+gregor`

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

javascript
# search all contacts that match the term "userlike" or "gregor"
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/contact_identities/?search_query=userlike+gregor"

# results 1-10, ordered by search ranking, with pagination applied
{
    "count": 14,
    "next": "https://api.userlike.com/api/um/v3/contact_identities/?limit=10&offset=10&search_query=userlike+gregor",
    "previous": null,
    "results": [
        {conversation object},
        ...
    ]
}

Ranking

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.

Ranking factor	Example	Description
`Weight`	`A`	The ranking prominence follows the natural order of the letters, i.e. "A" ranks higher than "B" ranks higher than "C"
`Occurrence`	`3`	The more occurences, the higher the ranking

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

Stemming and prefix search

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:

Provided search keyword(s)	Actual search
`?search_query=user`	`user*`	Matches "user", but also e.g. "userlike"
`?search_query=user+greg`	`user` `\|\| greg`	Matches e.g. "user", "userlike", "greg" or "gregor"

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

Conversation resource

Resource endpoints	Description	Allowed methods
`https://api.userlike.com/api/um/v3/conversations/` `https://api.userlike.com/api/um/v3/conversations/all/` `https://api.userlike.com/api/um/v3/conversations/{id}/` `https://api.userlike.com/api/um/v3/conversations/{id}/messages/`	List of conversations (limited) List of all conversations Single conversation Single conversation’s messages	GET \| DELETE GET GET \| DELETE GET

Conversation list endpoint - GET

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. This endpoint uses offset pagination. Results are limited to a maximum of 10,000, but there are options to get the latest conversation. If you need to access all of your organization’s conversations, please use the all conversations endpoint. This endpoint is useful to get recently created or updated conversations.

javascript
# GET list endpoint
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/conversations/"


# JSON data with results array and pagination info
{
    "count": 53,
    "next": "https://api.userlike.com/api/um/v3/conversations/?limit=10&offset=10",
    "previous": null,
    "results": [
        {
            "accepts_messages": false,
            "addon_urls": {},
            "contact": {
                "city": null,
                "company": null,
                "contact_by_email": true,
                "contact_by_phone": false,
                "contact_by_userlike_channels": true,
                "contact_by_userlike_messenger": true,
                "country": null,
                "created_at": "2020-07-09T12:17:56.725918Z",
                "email": null,
                "email_verified": false,
                "external_customer_id": null,
                "first_message_sent_at": "2020-07-09T12:18:05.220985Z",
                "gender": null,
                "id": 5882,
                "is_blocked": false,
                "is_mobile_number_verified": false,
                "last_message_sent_at": "2020-07-09T12:18:39.825908Z",
                "loc_lat": 51.6017,
                "loc_lon": 7.2183,
                "locale": "en_US",
                "mobile_number": null,
                "name": null,
                "needs_register": true,
                "phone_number": null,
                "position": null,
                "read_permission": true,
                "salutation": null,
                "street": null,
                "url_facebook": null,
                "url_linkedin": null,
                "url_profile_picture": null,
                "url_twitter": null,
                "verified": false,
                "write_permission": true
            },
            "contact_channel": {
                "state": "valid", "type": "web"
            },
            "contact_first_message_sent_at": "2020-07-09T12:18:05.220985Z",
            "contact_last_message_sent_at": "2020-07-09T12:18:39.825908Z",
            "contact_last_update_at": "2020-07-09T12:19:15.212681Z",
            "conversation_contact_uuid": "099bc06d-a5ff-4830-b404-d91095352f77",
            "created_at": "2020-07-09T12:17:57.490194Z",
            "custom": {
                "basket": {
                    "item01": {
                        "desc": "33X Optical Zoom Camcorder Mini DV",
                        "id": "2acefe58-91e5-11e1-beba-000c2979313a",
                        "price": 139.99,
                        "url": "http://www.shop.com/en/electronics/34-camcorder.html"
                    },
                    "item02": {
                        "desc": "Home Theater System",
                        "id": "31aca2f2-91e5-11e1-beba-000c2979313a",
                        "long": "Lorem ipsum dolor sit amet",
                        "price": 499.99,
                        "url": "https://www.shop.com/en/electronics/39-home-theater.html"
                    }
                },
                "id": "428614f0-91e5-11e1-beba-000c2979313a",
                "ref": "3efd5462e"
            },
            "customer_id": 5,
            "data_privacy": false,
            "expiry_state": 0,
            "feedback_message": "I'm loving Userlike! Really awesome product seriously.",
            "id": 8982,
            "language_name": "English (US)",
            "last_message": {
                "body": "Great, thanks!",
                "conversation": {
                    "id": 8982
                },
                "conversation_id": 8982,
                "display_name": "Contact",
                "event": null,
                "id": "8982.12509.48084",
                "marked_read_contact": true,
                "marked_read_operator": true,
                "msgid": "8982.12509.48084",
                "name": "Contact",
                "operator_display_name": "",
                "operator_id": null,
                "operator_name": "",
                "part_id": 12509,
                "reference": null,
                "sender": {"id": 5882, "type": "contact"},
                "sent_at": "2020-07-09T12:18:39.825908Z",
                "sent_at_time": "12:18:39.825908",
                "state": {"error_code": null, "message": "Read by user", "type": 4},
                "type": "message",
                "url": null
            },
            "last_message_sent_at": "2020-07-09T12:19:18.669619Z",
            "locale": "en_US",
            "marked_read_contact": true,
            "marked_read_operator": true,
            "operator_assigned_to": 63,
            "organization_id": 8,
            "page_impressions": 1.0,
            "post_survey_option": null,
            "pre_survey_option": null,
            "rate": 5,
            "read_permission": true,
            "slot_reserved": false,
            "status": "ended",
            "status_description": "Ended",
            "subject": null,
            "topics": [{"id": 24,
            "organization_id": 8,
            "read_permission": true,
            "text": "Support",
            "write_permission": true}],
            "um_widget": {"id": 35,
            "language_name": "English (US)",
            "name": "Test"},
            "um_widget_goals": [],
            "unread_messages_operator": [],
            "updated_at": "2020-07-09T12:19:28.538574Z",
            "visits": null,
            "write_permission": true
        },
        {9 more conversation objects}
    ]
}

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.

Conversation all list endpoint - GET

Conversations in this endpoint have the same format as conversations from the normal conversation list endpoint, but this endpoint has cursor-based pagination and allows access to all conversations in your organization and an unlimited number of results. This endpoint only allows id ordering and has the same filter options as the normal conversation list endpoint. The conversation id is used as a cursor.

javascript
# GET list all endpoint
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/conversations/all/?cursor=123&limit=100&ordering=id"


# JSON data with results array and pagination info
{
    "count": 53,
    "next": "https://api.userlike.com/api/um/v3/conversations/?cursor=223&limit=100&ordering=id",
    "previous": "https://api.userlike.com/api/um/v3/conversations/?cursor=-124&limit=100&ordering=id",
    "results": [
        {conversation object},
        ...
    ]
}

Conversation list endpoint - DELETE

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

javascript
# bulk delete 10 (by default) conversations
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --request DELETE \
     "https://api.userlike.com/api/um/v3/conversations/"

# no result data - expected response status
HTTP/1.1 204 No Content

⚠️

Making a DELETE request to the conversation list endpoint will irrevocably delete a number of conversations at once: 10 by default and 100 at most. As a precaution, you cannot delete ongoing conversations.

Conversation list endpoint filter

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

Field	Sample value	Description
`contact_uuid`	`MGEwYWJmZmEtN2M1OS01NGI2LWE2OWYtZWYxNDY4OWM0YWQ3`	Get all conversations you had with a specific contact
`operator_id`	`23`	Get all conversations of a specific operator by their ID
`status`	`pending`	Get all conversations you assigned a certain status
`topics`	`Support`	Get all conversations you assigned a certain topic label to
`um_widget_id`	`42`	Get all conversations that were conducted (at least partially) via a specific Widget.
`contact_first_message_to_date`	`2018-09-22T14:01:54.9571247Z`	Get all conversations where the first contact message was sent before a specific time
`contact_first_message_from_date`	`2018-09-22T14:01:54.9571247Z`	Get all conversations where the first contact message was sent after a specific time
`contact_last_message_to_date`	`2018-09-22T14:01:54.9571247Z`	Get all conversations where the last contact message was sent before a specific time
`contact_last_message_from_date`	`2018-07-22T14:01:54.9571247Z`	Get all conversations where the last contact message was sent after a specific time
`updated_at_to_date`	`2018-09-22T14:01:54.9571247Z`	Get all conversations in which the last update happened before a specified time. New messages count as updates.
`updated_at_from_date`	`2018-07-22T14:01:54.9571247Z`	Get all conversations in which the last update happened after a specified time. New messages count as updates.
`id__gt`	`935673`	Get all conversations with an ID greater than the one specified.
`id__lt`	`935673`	Get all conversations with an ID smaller than the one specified.
`contact_identity_id`	`20`	Get all conversations that belong to a specific contact

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

javascript
# filter all conversations for a certain operator
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/conversations/?operator_id=154"

# filtered results 1-10 that match operator, pagination links have filters set
{
    "count": 22,
    "next": "https://api.userlike.com/api/um/v3/conversations/?operator_id=154&limit=10&offset=10",
    "previous": null,
    "results": [
        {conversation object},
        ...
    ]
}

# filter all conversations since a certain date with a specific status
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/conversations/?status=new&updated_at_from_date=2022-01-01T00:00:00"

# filtered results 1-10 that match date and status, pagination links have filters set
{
    "count": 23,
    "next": "https://api.userlike.com/api/um/v3/conversations/?contact_first_message_from_date=2022-01-01T00:00:00&limit=10&offset=10&status=new",
    "previous": null,
    "results": [
        {conversation object},
        ...
    ]
}

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

⚠️

Making a filtered DELETE request to the conversation list endpoint will also irrevocably bulk delete a number of conversations: 10 by default, 100 being the maximum allowed limit.

javascript
# delete all conversations of a certain operator
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --request DELETE \
     "https://api.userlike.com/api/um/v3/conversations/?operator_id=154"

# no result data - expected response status
HTTP/1.1 204 No Content

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

Conversation list endpoint searching

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:

Field	Ranking	Description
`Contact's name`	`A`	Get all conversations whose contact’s name matches the keyword
`Contact's email`	`A`	Get all conversations whose contact’s email matches the keyword
`Contact's street`	`A`	Get all conversations whose contact’s street name matches the keyword
`Contact's city`	`A`	Get all conversations whose contact’s city matches the keyword
`Conversation messages`	`C`	Get all conversations whose messages matches the keyword

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

javascript
# search all conversations for the term "userlike"
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/conversations/?search_query=userlike"

# results 1-10, ordered by search ranking, with pagination applied
{
    "count": 14,
    "next": "https://api.userlike.com/api/um/v3/conversations/?limit=10&offset=10&search_query=userlike",
    "previous": null,
    "results": [
        {conversation object},
        ...
    ]
}

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

⚠️

Making a search DELETE request to the conversation list endpoint will irrevocably bulk delete the matched conversations: 10 by default, 100 being the maximum allowed limit.

javascript
# search and delete all conversations matching the term "userlike"
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --request DELETE \
     "https://api.userlike.com/api/um/v3/conversations/?search_query=userlike"

 # no result data - expected response status
 HTTP/1.1 204 No Content

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

Conversation list endpoint ordering

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

Field	Value	Description
`ordering`	`id`	Order the conversations according to their IDs, in ascending order (oldest first).
`ordering`	`-id`	Order the conversations according to their IDs, in descending order (newest first).
`ordering`	`last_message_sent_at`	Order the conversations according to when the last message was sent, in ascending order (oldest first).
`ordering`	`-last_message_sent_at`	Order the conversations according to when the last message was sent, in descending order (latest first).
`ordering`	`contact_first_message_sent_at`	Order the conversations according to when the contact first interacted with them, in ascending order (oldest first).
`ordering`	`-contact_first_message_sent_at`	Order the conversations according to when the contact first interacted with them, in descending order (latest first).
`ordering`	`contact_last_update_at`	Order the conversations according to when its contact was last updated, in ascending order (oldest first).
`ordering`	`-contact_last_update_at`	Order the conversations according to when their contact was last updated, in descending order (latest first).
`ordering`	`contact_last_message_sent_at`	Order the conversations according to when the contact last interacted with them, in ascending order (oldest first).
`ordering`	`-contact_last_message_sent_at`	Order the conversations according to when the contact last interacted with them, in descending order (latest first).

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

Conversation single endpoint - GET

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

javascript
# GET single conversation with ID 199
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/conversations/199/"


# resulting JSON data with full conversation part set

{
    "accepts_messages": false,
    "addon_urls": {
        "github": "https://github.com/optixx/UserlikeTest/issues/36956",
        "jira": "https://userlike-dev.atlassian.net/browse/TEST-22874",
    },
    "contact": {
        "city": null,
        "company": null,
        "contact_by_email": true,
        "contact_by_phone": false,
        "contact_by_userlike_channels": true,
        "contact_by_userlike_messenger": true,
        "country": null,
        "created_at": "2020-07-09T12:17:56.725918Z",
        "email": null,
        "email_verified": false,
        "external_customer_id": null,
        "first_message_sent_at": "2020-07-09T12:18:05.220985Z",
        "gender": null,
        "id": 5882,
        "is_blocked": false,
        "is_mobile_number_verified": false,
        "last_message_sent_at": "2020-07-09T12:18:39.825908Z",
        "loc_lat": 51.6017,
        "loc_lon": 7.2183,
        "locale": "en_US",
        "mobile_number": null,
        "name": null,
        "needs_register": true,
        "phone_number": null,
        "position": null,
        "read_permission": true,
        "salutation": null,
        "street": null,
        "url_facebook": null,
        "url_linkedin": null,
        "url_profile_picture": null,
        "url_twitter": null,
        "verified": false,
        "write_permission": true
    },
    "contact_channel": {
        "state": "valid",
        "type": "web"
    },
    "contact_first_message_sent_at": "2020-07-09T12:18:05.220985Z",
    "contact_last_message_sent_at": "2020-07-09T12:18:39.825908Z"
    "contact_last_update_at": "2020-07-09T12:19:15.212681Z",
    "conversation_contact_uuid": "099bc06d-a5ff-4830-b404-d91095352f77",
    "conversation_part_set": [
        {
            "browser": {
                "name": "Chrome",
                "os": "Mac OS X",
                "version": "83"
            },
            "created_at": "2020-07-09T12:17:57.849820Z",
            "duration": "00:00:42",
            "ended_at": "2020-07-09T12:18:39.825000Z",
            "id": 12509,
            "location": {
                "city": "Recklinghausen",
                "country": "Germany",
                "lat": 51.6017,
                "lon": 7.2183
            },
            "name_friendly": "Conversation Part",
            "part_type": "ChatMeta",
            "read_permission": true,
            "referrer": null,
            "write_permission": true
        }
    ],
    "created_at": "2020-07-09T12:17:57.490194Z",
    "custom": {
        "basket": {
            "item01": {
                "desc": "33X Optical Zoom Camcorder Mini DV",
                "id": "2acefe58-91e5-11e1-beba-000c2979313a",
                "price": 139.99,
                "url": "http://www.shop.com/en/electronics/34-camcorder.html"
            },
            "item02": {
                "desc": "Home Theater System",
                "id": "31aca2f2-91e5-11e1-beba-000c2979313a",
                "long": "Lorem ipsum dolor sit amet",
                "price": 499.99,
                "url": "https://www.shop.com/en/electronics/39-home-theater.html"
            }
        },
        "id": "428614f0-91e5-11e1-beba-000c2979313a",
        "ref": "3efd5462e"
    },
    "customer_id": 5,
    "data_privacy": false,
    "expiry_state": 0,
    "feedback_message": "I'm loving Userlike! Really awesome product seriously.",
    "id": 199,
    "language_name": "English (US)",
    "last_message": {
        "body": "Great, thanks!",
        "conversation": {
            "id": 199
        },
        "conversation_id": 199,
        "display_name": "Contact",
        "event": null,
        "id": "199.12509.48084",
        "marked_read_contact": true,
        "marked_read_operator": true,
        "msgid": "199.12509.48084",
        "name": "Contact",
        "operator_display_name": "",
        "operator_id": null,
        "operator_name": "",
        "part_id": 12509,
        "reference": null,
        "sender": {
            "id": 5882,
            "type": "contact"
        },
        "sent_at": "2020-07-09T12:18:39.825908Z",
        "sent_at_time": "12:18:39.825908",
        "state": {
            "error_code": null,
            "message": "Read by user",
            "type": 4
        },
        "type": "message",
        "url": null
    },
    "last_message_sent_at": "2020-07-09T12:19:18.669619Z",
    "locale": "en_US",
    "marked_read_contact": true,
    "marked_read_operator": true,
    "operator_assigned_to": 63,
    "organization_id": 8,
    "page_impressions": 1.0,
    "post_survey_option": null,
    "pre_survey_option": null,
    "rate": 5,
    "read_permission": true,
    "slot_reserved": false,
    "status": "ended",
    "status_description": "Ended",
    "subject": null,
    "topics": [
        {
            "id": 24,
            "organization_id": 8,
            "read_permission": true,
            "text": "Support",
            "write_permission": true
        }
    ],
    "um_widget": {
        "id": 35,
        "language_name": "English (US)",
        "name": "Test"
    },
    "um_widget_goals": [],
    "unread_messages_operator": [],
    "updated_at": "2020-07-09T12:22:43.199704Z",
    "visits": null,
    "write_permission": true
}

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.

Conversation single endpoint - DELETE

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

javascript
# delete conversation 199
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --request DELETE \
     "https://api.userlike.com/api/um/v3/conversations/199/"

# no result data - expected response status
HTTP/1.1 204 No Content

Conversation messages endpoint - GET

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.

javascript
# GET messages of conversation with ID 2017
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/conversations/2017/messages/?limit=3"

{
    "next": "https://api.userlike.com/api/um/v3/conversations/2017/messages/?cursor=2017.2522.14137&limit=3",
    "previous": null,
    "results": [
        {
            "id": "2017.2522.14139",
            "conversation_id": 2017,
            "part_id": 2522,
            "sent_at": "2021-07-29T08:49:16.891668Z",
            "operator_id": 2674,
            "reference": null,
            "type": "message",
            "event": null,
            "body": "Hi there! How do I install this?",
            "state": {
                "type": 1,
                "error_code": null,
                "message": "Submitted"
            },
            "url": null,
            "sent_at_time": "08:49:16.891668",
            "operator_display_name": "David Voswinkel",
            "operator_name": "David Voswinkel",
            "operator_is_bot": false,
            "marked_read_operator": false,
            "marked_read_contact": false,
            "msgid": "2017.2522.14139",
            "name": "David Voswinkel",
            "display_name": "David Voswinkel",
            "sender": {
                "type": "operator",
                "id": 2674
            },
            "conversation": {
                "id": 2017
            }
        },
        {
            "id": "2017.2522.14138",
            "conversation_id": 2017,
            "part_id": 2522,
            "sent_at": "2021-07-29T08:49:16.852722Z",
            "operator_id": null,
            "reference": null,
            "type": "message",
            "event": null,
            "body": "Hello, you're talking to David Voswinkel. How can I help?",
            "state": {
                "type": 3,
                "error_code": null,
                "message": "Delivered to contact"
            },
            "url": null,
            "sent_at_time": "08:49:16.852722",
            "operator_display_name": "",
            "operator_name": "",
            "operator_is_bot": false,
            "marked_read_operator": false,
            "marked_read_contact": false,
            "msgid": "2017.2522.14138",
            "name": "Jane Dough",
            "display_name": "Jane Dough",
            "sender": {
                "type": "contact",
                "id": 1833
            },
            "conversation": {
                "id": 2017
            }
        },
        {
            "id": "2017.2522.14137",
            "conversation_id": 2017,
            "part_id": 2522,
            "sent_at": "2021-07-29T08:49:16.822231Z",
            "operator_id": 2674,
            "reference": null,
            "type": "message",
            "event": null,
            "body": "Very easy, just follow this tutorial: https://www.userlike.com/tutorial/intro",
            "state": {
                "type": 1,
                "error_code": null,
                "message": "Submitted"
            },
            "url": null,
            "sent_at_time": "08:49:16.822231",
            "operator_display_name": "David Voswinkel",
            "operator_name": "David Voswinkel",
            "operator_is_bot": false,
            "marked_read_operator": false,
            "marked_read_contact": false,
            "msgid": "2017.2522.14137",
            "name": "David Voswinkel",
            "display_name": "David Voswinkel",
            "sender": {
                "type": "operator",
                "id": 2674
            },
            "conversation": {
                "id": 2017
            }
        }
    ]
}

Retrieve uploaded files

Messages of type upload and their attached media file provide an url field to which you can make a GET request.

As a response, you will get a JSON object with detailed meta data of this media file, including the actual URL to retrieve the binary data:

javascript
# GET medial details
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/media/download/3-0ee5f3d95a4d89e2a6e28fbb7c8f9d3a.png"

{
    "mime_type": "image/png",
    "title": "car_front_image.png",
    "url": "https://example-file-download.url"  # url for the binary data
}

Use the new url for another GET request to retrieve the binary data.

Conversation messages endpoint filters

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

Field	Sample value	Description
`type`	`notification`	Get all messages of a specific type
`sender_type`	`contact`	Get all messages from a specific sender type
`event`	`welcome_message`	Get all messages from a specific event

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

The following values can be used to filter by type:

Value	Description
`notification`	Get all messages of type notification
`upload`	Get all messages of type upload
`co`	Get all messages sent by contact
`ct`	Get all messages sent to contact
`link`	Get all messages of type link (eg. a link was sent in the conversation)
`call_event`	Get all messages relating to audio/video call events (eg. "call finished")
`call_offer`	Get all messages relating to audio/video call offers (a call was offered to the contact by an operator)

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

Conversation messages endpoint paginations

The conversation messages endpoint uses cursor based pagination with a maximum page size of 100 messages. For more information see pagination details

javascript
# get messages after message with reference "2015.2508.14032"
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/conversation/123/messages/?ordering=id&cursor=2015.2508.14032&limit=50"

# JSON data with results array and pagination info
# you will automatically get a link to access the 50 messages that come after the latest results in
# "next" and a link to access the 50 results that come before the first result in "previous"
{
    "next": "https://api.userlike.com/api/um/v3/conversation/123/messages/?cursor=2015.2508.14082&limit=50",
    "previous": "https://api.userlike.com/api/um/v3/conversation/123/messages/?cursor=-2015.2508.13900&limit=50",
    "results": [...]
}

Conversation messages endpoint ordering

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

Field	Value	Description
`ordering`	`id`	Order the conversation messages according to their ID, in ascending order (oldest first).
`ordering`	`-id`	Order the conversation messages according to their ID, in descending order (latest first).

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

Note resource

Resource endpoints	Description	Allowed methods
`https://api.userlike.com/api/um/v3/notes/https://api.userlike.com/api/um/v3/notes/{id}/`	List of notesSingle note	GET \| POSTGET \| DELETE

Note list endpoint - GET

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.

javascript
# GET list endpoint
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/notes/"


# JSON data with results array and pagination info
{
    "count": 12,
    "next": https://api.userlike.com/api/um/v3/notes/?limit=10&offset=10,
    "previous": null,
    "results": [
        {
            "id": 2344,
            "conversation_id": 5882,
            "contact_identity_id": null,
            "message_id": 1542,
            "operator_id": 65,
            "body": "This issue has been reported before.",
            "msgid": "218.274.1542",
            "created_at": "2021-08-09T15:10:22.687027Z"
        },
        {
            "id": 2343,
            "conversation_id": 8982,
            "contact_identity_id": null,
            "message_id": 1575,
            "operator_id": 64,
            "body": "Already fixed in ticket #4711",
            "msgid": "218.274.1542",
            "created_at": "2021-08-09T11:33:12.046284Z"
        },
        {8 more note objects}
    ]
}

Note list endpoint filters

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

Field	Sample value	Description
`conversation_id`	`42`	Get all notes you added to a specific conversation
`contact_identity_id`	`23`	Get all notes you added to a specific contact

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

javascript
# filter all notes for a certain conversation
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/notes/?conversation_id=5882"

# filtered results 1-10 that match conversation_id, pagination links have filter set
{
    "count": 12,
    "next": "https://api.userlike.com/api/um/v3/notes/?conversation_id=58828&limit=10&offset=10",
    "previous": null,
    "results": [
        {note object},
        ...
    ]
}

# filter all notes for a certain contact
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/notes/?contact_identity_id=23"

# filtered results 1-10 that match contact_identity_id, pagination links have filter set
{
    "count": 23,
    "next": "https://api.userlike.com/api/um/v3/notes/?contact_identity_id=23&limit=10&offset=10",
    "previous": null,
    "results": [
        {note object},
        ...
    ]
}

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

Note list endpoint ordering

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

javascript
# GET list endpoint
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/notes/"


# JSON data with results array and pagination info
{
    "count": 12,
    "next": https://api.userlike.com/api/um/v3/notes/?limit=10&offset=10,
    "previous": null,
    "results": [
        {
            "id": 2344,
            "conversation_id": 5882,
            "contact_identity_id": null,
            "message_id": 1542,
            "operator_id": 65,
            "body": "This issue has been reported before.",
            "msgid": "218.274.1542",
            "created_at": "2021-08-09T15:10:22.687027Z"
        },
        {
            "id": 2343,
            "conversation_id": 8982,
            "contact_identity_id": null,
            "message_id": 1575,
            "operator_id": 64,
            "body": "Already fixed in ticket #4711",
            "msgid": "218.274.1542",
            "created_at": "2021-08-09T11:33:12.046284Z"
        },
        {8 more note objects}
    ]
}

Note list endpoint - POST

To create a note for either of the two types, conversation or contact, one of those fields needs to be included in the request body data: conversation_id or contact_identity_id. Passing both fields in one request will result in an error response. On success, a JSON object with the newly created note will be returned.

The request body data for conversation notes allows the following fields:

Field	Sample value	Description
`conversation_id`	`50670`	Conversation ID
`body`	`My new note`	Note content
`msgid`	`2017.2522.14138`	Optional reference to a message. If given, the note will appear below that message inside the conversation transcript. Otherwise it will only be shown in the note list on the side.

The request body data for contact notes should contain the following fields:

Field	Sample value	Description
`contact_identity_id`	`981164`	ID of the contact the note refers to
`body`	`My new note`	Note content

javascript
# Create a single note in a conversation
curl --request POST \
     --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --header "Content-Type: application/json" \
     "https://api.userlike.com/api/um/v3/notes/" \
     --data '{"conversation_id": 5882, "body": "This issue has been reported before", "msgid": "5882.8944.143346"}'


# resulting JSON data

{
    "id": 2344,
    "conversation_id": 5882,
    "contact_identity_id": null,
    "message_id": 1542,
    "operator_id": 64,
    "body": "This issue has been reported before.",
    "msgid": "5882.8944.143346",
    "created_at": "2021-08-09T15:10:22.687027Z"
}

# Create a single note for a contact
curl --request POST \
     --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --header "Content-Type: application/json" \
     "https://api.userlike.com/api/um/v3/notes/" \
     --data '{"contact_identity_id": 50670, "body": "Is highly interested in our new product."}'


# resulting JSON data

{
    "id": 2345,
    "conversation_id": null,
    "contact_identity_id": 50670,
    "message_id": null,
    "operator_id": 64,
    "body": "Is highly interested in our new product.",
    "msgid": null,
    "created_at": "2021-08-09T15:10:22.687027Z"
}

Note single endpoint - GET

Fetch a specific note by providing its ID.

javascript
# GET single note with ID 2344
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/notes/2344/"


# resulting JSON data

{
    "id": 2344,
    "conversation_id": 5882,
    "contact_identity_id": null,
    "message_id": 1542,
    "operator_id": 64,
    "body": "This issue has been reported before.",
    "msgid": "218.274.1542",
    "created_at": "2021-08-09T15:10:22.687027Z"
}

Note single endpoint - DELETE

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

javascript
# delete note 2344
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --request DELETE \
     "https://api.userlike.com/api/um/v3/notes/2344/"

# no result data - expected response status
HTTP/1.1 204 No Content

Navigation event resource

Resource endpoints	Description	Allowed methods
`https://api.userlike.com/api/um/v3/navigation/`	List of navigations	GET

Navigation events endpoint - GET

Fetch all navigation events that a contact triggered. You can either use the conversation_idquery 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.

javascript
# GET navigations that happened during conversation with ID 2013
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/navigation/?conversation_id=2013"

# GET navigations of contact with ID 1345
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/navigation/?contact_identity_id=1831"


# This is what the result could look like:
{
    "count_earlier": 0,
    "count_later": 0,
    "results": [
        {
            "contact_identity_id": 1831,
            "read_permission": true,
            "title": "Userlike Test Page",
            "url": "https://userlike.com/",
            "created_at": "2021-07-28T15:13:27.813938Z",
            "write_permission": true,
            "organization_id": 3,
            "conversation_id": 2013,
            "customer_id": 2,
            "id": 67
        },
        {
            "contact_identity_id": 1831,
            "read_permission": true,
            "title": "Userlike Test Page",
            "url": "https://userlike.com/product",
            "created_at": "2021-07-28T15:13:21.837302Z",
            "write_permission": true,
            "organization_id": 3,
            "conversation_id": 2013,
            "customer_id": 2,
            "id": 66
        },
        {
            "contact_identity_id": 1831,
            "read_permission": true,
            "title": "Userlike Test Page",
            "url": "https://userlike.com/register",
            "created_at": "2021-07-28T15:13:15.770674Z",
            "write_permission": true,
            "organization_id": 3,
            "conversation_id": 2013,
            "customer_id": 2,
            "id": 65
        },
    ]
}

Navigation events endpoint filters

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

Field	Sample value	Description
`type`	`id__lt`	Get navigation events withs ids less than the given value
`type`	`id__gt`	Get navigation events withs ids greater than the given value
`type`	`created_at__lt`	Get navigation events that were created before the given date
`type`	`created_at__gt`	Get navigation events that were created after the given date
`type`	`created_at__lte`	Get navigation events that were created before the given date or exactly on the given date
`type`	`created_at__gte`	Get navigation events that were created after the given date or exactly on the given date

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

Navigation events endpoint pagination

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_earlierand 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 orderingquery parameter.

javascript
# get next 100 navigations after navigation with id 1000 for conversation 123
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/navigation/?conversation_id=123&id__gt=1000&page_size=100"

# get previous 100 navigations before navigation with id 1000 for conversation 123
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/navigation/?conversation_id=123&id__lt=1000&page_size=100"

# the response could look like this
# count_earlier and count_later tells you whether you have all events, or if
# there are still some left to be fetched. In this case there are 100 navigation
# events left to fetch that come after the last result:
{
    "count_earlier": 0,
    "count_later": 100,
    "results": [...],
}

Navigation events endpoint ordering

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

Field	Value	Description
`ordering`	`id`	Order the navigation events according to their ID, in ascending order (oldest first).
`ordering`	`-id`	Order the navigation events according to their ID, in descending order (latest first).

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

Contact resource

Resource endpoints	Description	Allowed methods
`https://api.userlike.com/api/um/v3/contact_identities/` `https://api.userlike.com/api/um/v3/contact_identities/all/` `https://api.userlike.com/api/um/v3/contact_identities/{id}/`	List of contacts List of all contacts Single contact	GET \| DELETEGETGET \| PATCH \| DELETE

Contact list endpoint - GET

Fetch a list of contacts. Returns a JSON object with a results array, by default containing the last 10 contacts that have been created. This endpoint uses offset pagination. Results are limited to a maximum of 10,000. You can use this endpoint to get recently created or updated contacts. If you need to access all of your organization’s contacts, please use the all contacts endpoint. The response JSON further contains pagination details.

javascript
# GET list endpoint
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/contact_identities/"


# JSON data with results array and pagination info
{
    "count": 53,
    "next": "https://api.userlike.com/api/um/v3/contact_identities/?limit=10&offset=10",
    "previous": null,
    "results": [
        {
            "city": "Cologne",
            "company": null,
            "contact_by_email": true,
            "contact_by_phone": false,
            "contact_by_userlike_channels": true,
            "contact_by_userlike_messenger": true,
            "contact_uuids": [
                "099bc06d-a5ff-4830-b404-d91095352f77"
            ],
            "conversation_count": 1,
            "country": "DE",
            "created_at": "2020-07-09T12:17:56.725918Z",
            "email": "test@userlike.com",
            "email_verified": false,
            "external_customer_id": null,
            "first_message_sent_at": "2020-07-09T12:18:05.220985Z",
            "gender": "f",
            "id": 53,
            "is_blocked": false,
            "is_mobile_number_verified": false,
            "last_message_sent_at": "2020-07-09T12:18:39.825908Z",
            "loc_lat": 51.6017,
            "loc_lon": 7.2183,
            "locale": "en_US",
            "mobile_number": null,
            "name": "Jane Doe",
            "needs_register": false,
            "phone_number": null,
            "position": null,
            "read_permission": true,
            "salutation": "ms",
            "street": null,
            "url_facebook": null,
            "url_linkedin": null,
            "url_profile_picture": null,
            "url_twitter": null,
            "verified": false,
            "write_permission": true
        },
        {9 more contact objects}
    ]
}

Contact all list endpoint - GET

Contacts in this endpoint have the same format as contacts from the normal contact list endpoint, but this endpoint has cursor-based pagination and allows access to all contacts in your organization with an unlimited number of results. This endpoint only allows id ordering and has the same filter options as the normal contact list endpoint. The contact id is used as a cursor.

javascript
# GET list all endpoint
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/contact_identities/all/?cursor=123&limit=100&ordering=id"


# JSON data with results array and pagination info
{
    "count": 53,
    "next": "https://api.userlike.com/api/um/v3/contact_identities/?cursor=223&limit=100&ordering=id",
    "previous": "https://api.userlike.com/api/um/v3/contact_identities/?cursor=-124&limit=100&ordering=id",
    "results": [
        {contact object},
        ...
    ]
}

Contact list endpoint - DELETE

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

javascript
# bulk delete 10 (by default) contacts
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --request DELETE \
     "https://api.userlike.com/api/um/v3/contact_identities/"

# no result data - expected response status
HTTP/1.1 204 No Content

⚠️

Making a DELETE request to the contact list endpoint can potentially bulk delete a number of contacts: 10 by default, 100 being the maximum allowed limit.

Contact list endpoint filters

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

Field	Sample value	Description
`id`	`23`	Get the contact matching the given ID
`email`	`david@userlike.com`	Get the contact with the specified email
`name`	`David Voswinkel`	Get all contacts matching a specific name
`to_date_time`	`2018-09-22T14:01:54.9571247Z`	Get all contacts that were active before a specific time
`from_date_time`	`2018-07-22T14:01:54.9571247Z`	Get all contacts that were active after a specific time
`verified`	`true`	Get all contacts that have a verified email or mobile number
`locale`	`en_US`	Get all contacts that match the given locale

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

javascript
# filter all contacts for a certain email
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/contact_identities/?email=test@userlike.com"

# filtered results that match a contact with given email
{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {conversation object},
    ]
}

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

⚠️

Making a filtered DELETE request to the contact list endpoint can potentially bulk delete a number of contacts: 10 by default, 100 being the maximum allowed limit.

javascript
# delete all contacts with a certain name
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --request DELETE \
     "https://api.userlike.com/api/um/v3/contact_identities/?name=Userlike%20Support"

# no result data - expected response status
HTTP/1.1 204 No Content

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

Contact list endpoint searching

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:

Field	Ranking	Description
`Contact's name`	`A`	Get all conversations whose contact’s name matches the keyword
`Contact's email`	`A`	Get all conversations whose contact’s email matches the keyword
`Contact's street`	`A`	Get all conversations whose contact’s street name matches the keyword
`Contact's city`	`A`	Get all conversations whose contact’s city matches the keyword
`Contact's country`	`A`	Get all conversations whose contact’s country matches the keyword
`Contact's notes`	`B`	Get all conversations where your notes about the contact matches the keyword

An example contact search:

javascript
# search all contacts for the term "userlike"
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/contact_identities/?search_query=userlike"

# results 1-10, ordered by search ranking, with pagination applied
{
    "count": 14,
    "next": "https://api.userlike.com/api/um/v3/contact_identities/?limit=10&offset=10&search_query=userlike",
    "previous": null,
    "results": [
        {conversation object},
        ...
    ]
}

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

⚠️

Making a search DELETE request to the contact list endpoint will irrevocably bulk delete the matched contacts: 10 by default, 100 being the maximum allowed limit.

javascript
# search and delete all contacts matching the term "userlike"
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --request DELETE \
     "https://api.userlike.com/api/um/v3/contact_identities/?search_query=userlike"

 # no result data - expected response status
 HTTP/1.1 204 No Content

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

Contact list endpoint ordering

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

Field	Value	Description
`ordering`	`created_at`	Order the contacts according to when they were created, in ascending order (oldest first).
`ordering`	`-created_at`	Order the contacts according to when they were created, in descending order (latest first).
`ordering`	`name`	Order the contacts by their names, in ascending order (A-Z).
`ordering`	`-name`	Order the contacts by their names, in descending order (Z-A).
`ordering`	`email`	Order the contacts by their email, in ascending order (A-Z).
`ordering`	`-email`	Order the contacts by their email, in descending order (Z-A).

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

Contact single endpoint - GET

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

javascript
# GET single contact with ID 42
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/contact_identities/42/"


# resulting JSON data with additional data
{
    "city": "Cologne",
    "company": null,
    "contact_by_email": true,
    "contact_by_phone": false,
    "contact_by_userlike_channels": true,
    "contact_by_userlike_messenger": true,
    "contact_uuids": [
        "099bc06d-a5ff-4830-b404-d91095352f77"
    ],
    "conversation_count": 1,
    "country": "DE",
    "created_at": "2020-07-09T12:17:56.725918Z",
    "email": "test@userlike.com",
    "email_verified": false,
    "external_customer_id": null,
    "first_message_sent_at": "2020-07-09T12:18:05.220985Z",
    "gender": "f",
    "id": 42,
    "is_blocked": false,
    "is_mobile_number_verified": false,
    "last_message_sent_at": "2020-07-09T12:18:39.825908Z",
    "loc_lat": 51.6017,
    "loc_lon": 7.2183,
    "locale": "en_US",
    "mobile_number": null,
    "name": "Jane Doe",
    "needs_register": false,
    "phone_number": null,
    "position": null,
    "read_permission": true,
    "salutation": "ms",
    "street": null,
    "url_facebook": null,
    "url_linkedin": null,
    "url_profile_picture": null,
    "url_twitter": null,
    "verified": false,
    "write_permission": true
}

Contact single endpoint - PATCH

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

The following fields can be updated:

Field	Sample value	Description
`email`	`my.contact@customer.com`	Update the contact’s email address
`name`	`"Jane Doe"`	Update the contact’s name
`salutation`	`"mrs"`	Update how the contact whishes to be saluted
`gender`	`"f"`	Update the contact’s gender
`street`	`"Sunset Blvd"`	Update the contact’s street
`city`	`"Cologne"`	Update the contact’s city
`country`	`"DE"`	Update the contact’s country, providing a valid two-digit iso code.
`phone_number`	`"+49521234567"`	Update the contact’s phone number
`mobile_number`	`"+49521234567"`	Update the contact’s mobile number
`contact_by_phone`	`True`	Update if the contact wants to be contacted via phone
`contact_by_email`	`True`	Update if the contact wants to be contacted via email
`contact_by_userlike_messenger`	`True`	Update if the contact wants to be contacted via the Website Messenger
`contact_by_userlike_channels`	`True`	Update if the contact wants to be contacted via channels
`url_facebook`	`"https://facebook.com/xy"`	Update the contact’s Facebook URL
`url_twitter`	`"https://twitter.com/xy"`	Update the contact’s Twitter URL
`url_linkedin`	`"https://linkedin.com/xy"`	Update the contact’s Linkedin URL
`url_profile_picture`	`"https://url_profile_picture.com/xy"`	Update the contact’s profile picture URL
`external_customer_id`	`"123"`	Update the contact’s external id

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

javascript
# update how a contact wants to be saluted
curl --request PATCH \
     --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --header "Content-Type: application/json" \
     "https://api.userlike.com/api/um/v3/contact_identities/3126/" \
     --data '{"salutation":"prof"}'

 # result is the updated resource item
 {patched resource item}

# update status, operator and subject of a certain conversation at once
curl --request PATCH \
     --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --header "Content-Type: application/json" \
     "https://api.userlike.com/api/um/v3/contact_identities/3126/" \
     --data '{"gender": "m", "contact_by_email": true, "city": "Cologne", "country": "DE"}'

 # result is the updated resource item
 {patched resource item}

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.

Contact single endpoint - DELETE

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

javascript
# delete contact 42
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --request DELETE \
     "https://api.userlike.com/api/um/v3/contact_identities/42/"

# no result data - expected response status
HTTP/1.1 204 No Content

Operator resource

Resource endpoints	Description	Allowed methods
`https://api.userlike.com/api/um/v3/operators/` `https://api.userlike.com/api/um/v3/operators/{id}/` `https://api.userlike.com/api/um/v3/operators/{id}/slots/` `https://api.userlike.com/api/um/v3/operators/{id}/away/`	List of operators Single operator Single operator’s slot data Single operator’s away status	GET GET \| PATCH \| DELETE GET PATCH

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.

Operator list endpoint - GET

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.

javascript
# GET list endpoint
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/operators/"


# JSON data with results array and pagination info
{
    "count": 20,
    "next": "https://api.userlike.com/api/um/v3/operators/?limit=10&offset=10",
    "previous": null,
    "results": [
        {
            "about_me": "",
            "account_type": "normal",
            "created_at": "2020-07-03T09:48:27.292124Z",
            "created_at_timezone": "Atlantic/Reykjavik",
            "created_at_utc": "2020-07-03 09:48:27",
            "display_name": "David Voswinkel",
            "email": "test@userlike.com",
            "enabled": true,
            "first_name": "David",
            "id": 21,
            "inactivity_repeat_timeout": 0,
            "inactivity_sound": false,
            "inactivity_sound_file": "inactivity",
            "inactivity_sound_volume": 1.0,
            "inactivity_timeout": 30000,
            "is_active": true,
            "is_locked": false,
            "is_locked_or_is_disabled": false,
            "is_role_admin": false,
            "is_role_agent": false,
            "is_role_staff": false,
            "job_title": "",
            "lang": "en",
            "last_login_at": null,
            "last_login_at_timezone": null,
            "last_login_at_utc": null,
            "last_name": "Voswinkel",
            "locale": "en_US",
            "name": "David Voswinkel",
            "notification_mute": false,
            "operator_group": {
                "id": 25,
                "name": "Testing David Voswinkel",
                "read_permission": true,
                "write_permission": true
            },
            "organization": {
                "id": 8,
                "name": "Testing"
            },
            "out_of_office": false,
            "read_permission": true,
            "role": "m",
            "role_name": "Manager",
            "skills": [],
            "sound_connect": true,
            "sound_disconnect": true,
            "sound_message_new": true,
            "sound_operator_off": false,
            "sound_operator_on": false,
            "timezone": "Atlantic/Reykjavik",
            "timezone_offset": 0,
            "um_away": false,
            "um_email_profile": "unread",
            "um_notification_addon_created": true,
            "um_notification_addon_updated": true,
            "um_notification_chat_session_forward": true,
            "um_notification_chat_session_forward_new": true,
            "um_notification_chat_session_start_other": true,
            "um_notification_chat_session_start_own": true,
            "um_notification_conversation_end": true,
            "um_notification_conversation_feedback": true,
            "um_notification_conversation_goal": true,
            "um_notification_conversation_post_survey": true,
            "um_notification_conversation_rating": true,
            "um_notification_message_receive": false,
            "um_notification_message_sent": false,
            "um_notification_widget_config": false,
            "um_notification_conversation_new_offline": true,
            "um_notification_conversation_not_live": true,
            "um_notification_conversation_end_own": true,
            "um_notification_conversation_feedback_own": true,
            "um_notification_conversation_goal_own": true,
            "um_notification_conversation_new_unassigned": true,
            "um_notification_conversation_new_relevant": true,
            "um_notification_conversation_post_survey_own": true,
            "um_notification_conversation_rating_own": true,
            "um_notification_operator_availability": true,
            "um_slots": {
                "availability": "offline",
                "available": false,
                "connected": false,
                "free": 0,
                "total": 5,
                "used": 0
            },
            "umc_settings": {},
            "url_image": "https://www.userlike.com/profile.jpg",
            "username": "testingdavidvoswinkel",
            "write_permission": true
        },
        {9 more operator objects}
    ]
}

Operator list endpoint filters

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

Field	Sample value	Description
`id`	`23`	Get the operator matching the given ID
`email`	`david@userlike.com`	Get the operator with the specified email
`name`	`David Voswinkel`	Get all operators matching a specific name
`operator_group_id`	`132`	Get all operators belongig to a specific operator group

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

javascript
# filter all operator for a certain operator group
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/operators/?operator_group_id=132"

# filtered results of operators belongig to the given operator group
{
    "count": 15,
    "next": "https://api.userlike.com/api/um/v3/operators/?limit=10&offset=10&operator_group_id=132",
    "previous": null,
    "results": [
        {operator objects},
    ]
}

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

Operator list endpoint ordering

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

Field	Value	Description
`ordering`	`created_at`	Order the operators according to when they were created, in ascending order (oldest first).
`ordering`	`-created_at`	Order the operators according to when they were created, in descending order (latest first).
`ordering`	`name`	Order the operators by their names, in ascending order (A-Z).
`ordering`	`-name`	Order the operators by their names, in descending order (Z-A).
`ordering`	`email`	Order the operators by their email, in ascending order (A-Z).
`ordering`	`-email`	Order the operators by their email, in descending order (Z-A).

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

Operator single endpoint - GET

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

javascript
# GET single operator with ID 144
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/operators/144/"


# resulting JSON data with additional data
{
    "about_me": "",
    "account_type": "normal",
    "created_at": "2020-07-03T09:48:27.292124Z",
    "created_at_timezone": "Atlantic/Reykjavik",
    "created_at_utc": "2020-07-03 09:48:27",
    "display_name": "David Voswinkel",
    "email": "test@userlike.com",
    "enabled": true,
    "first_name": "David",
    "id": 144,
    "inactivity_repeat_timeout": 0,
    "inactivity_sound": false,
    "inactivity_sound_file": "inactivity",
    "inactivity_sound_volume": 1.0,
    "inactivity_timeout": 30000,
    "is_active": true,
    "is_locked": false,
    "is_locked_or_is_disabled": false,
    "is_role_admin": false,
    "is_role_agent": false,
    "is_role_staff": false,
    "job_title": "",
    "lang": "en",
    "last_login_at": null,
    "last_login_at_timezone": null,
    "last_login_at_utc": null,
    "last_name": "Voswinkel",
    "locale": "en_US",
    "name": "David Voswinkel",
    "notification_mute": false,
    "operator_group": {
        "id": 25,
        "name": "Testing David Voswinkel",
        "read_permission": true,
        "write_permission": true
    },
    "organization": {
        "id": 8,
        "name": "Testing"
    },
    "out_of_office": false,
    "read_permission": true,
    "role": "m",
    "role_name": "Manager",
    "skills": [],
    "sound_connect": true,
    "sound_disconnect": true,
    "sound_message_new": true,
    "sound_operator_off": false,
    "sound_operator_on": false,
    "timezone": "Atlantic/Reykjavik",
    "timezone_offset": 0,
    "um_away": false,
    "um_email_profile": "unread",
    "um_notification_addon_created": true,
    "um_notification_addon_updated": true,
    "um_notification_chat_session_forward": true,
    "um_notification_chat_session_forward_new": true,
    "um_notification_chat_session_no_operator": true,
    "um_notification_chat_session_start_other": true,
    "um_notification_chat_session_start_own": true,
    "um_notification_conversation_end": true,
    "um_notification_conversation_feedback": true,
    "um_notification_conversation_goal": true,
    "um_notification_conversation_post_survey": true,
    "um_notification_conversation_rating": true,
    "um_notification_message_receive": false,
    "um_notification_message_sent": false,
    "um_notification_widget_config": false,
    "um_notification_conversation_new_offline": true,
    "um_notification_conversation_not_live": true,
    "um_notification_conversation_end_own": true,
    "um_notification_conversation_feedback_own": true,
    "um_notification_conversation_goal_own": true,
    "um_notification_conversation_new_unassigned": true,
    "um_notification_conversation_new_relevant": true,
    "um_notification_conversation_post_survey_own": true,
    "um_notification_conversation_rating_own": true,
    "um_notification_operator_availability": true,
    "um_slots": {
        "availability": "offline",
        "available": false,
        "connected": false,
        "free": 0,
        "total": 5,
        "used": 0
    },
    "umc_settings": {},
    "url_image": "https://www.userlike.com/profile.jpg",
    "username": "testingdavidvoswinkel",
    "write_permission": true
}

Operator single endpoint - patch

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:

Field	Sample value	Description
`um_notification_message_receive`	`true`	Turn browser notification for new messages on or off
`um_notification_chat_session_forward`	`true`	Turn browser notification for reassigned conversations on or off
`um_notification_conversation_rating`	`true`	Turn browser notification for conversation ratings on or off
`um_notification_conversation_feedback`	`true`	Turn browser notification for conversation feedback on or off
`um_notification_conversation_post_survey`	`true`	Turn browser notification for post-conversation surveys on or off
`um_notification_conversation_goal`	`true`	Turn browser notification for reached Widget goals on or off
`um_notification_conversation_end`	`true`	Turn browser notification for ended conversations on or off
`um_notification_conversation_offline_assigned`	`true`	Turn browser notification for assigned offline conversations on or off
`um_notification_conversation_live`	`true`	Turn browser notification for incoming live conversations on or off
`um_notification_conversation_not_live`	`true`	Turn browser notification for timeout being reached in a conversation on or off
`um_notification_conversation_end_own`	`true`	Turn browser notification for own conversation ending on or off
`um_notification_conversation_feedback_own`	`true`	Turn browser notification for feedback in own conversations on or off
`um_notification_conversation_goal_own`	`true`	Turn browser notification for Widget goals reached in own conversations on or off
`um_notification_conversation_offline_unassigned`	`true`	Turn browser notification for unassigned conversations on or off
`um_notification_conversation_started`	`true`	Turn browser notification for conversation started or resumed on or off
`um_notification_conversation_post_survey_own`	`true`	Turn browser notification for post-conversation survey answers in own conversations on or off
`um_notification_conversation_rating_own`	`true`	Turn browser notification for ratings on own conversations on or off
`um_notification_operator_availability`	`true`	Turn browser notification for operator status changes on or off
`sound_connect`	`true`	Turn sound notification for operator connecting to UMC on or off
`sound_disconnect`	`true`	Turn sound notification for operator disconnecting from UMC on or off
`sound_message_new`	`true`	Turn sound notification for new message being received in a conversation on or off
`sound_operator_off`	`true`	Turn sound notification for operator going offline on or off
`sound_operator_on`	`true`	Turn sound notification for operator going online on or off
`sound_conversation_live`	`true`	Turn sound notification for received live conversations on or off
`sound_conversation_offline`	`true`	Turn sound notification for received offline conversations on or off
`notification_mute`	`true`	Mute or unmute all notifications
`out_of_office`	`true`	Turn out of office mode on or off

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

javascript
# update out_of_office of a certain operator
curl --request PATCH \
     --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --header "Content-Type: application/json" \
     "https://api.userlike.com/api/um/v3/operators/{id}/" \
     --data '{"out_of_office": true}'

 # result is the updated resource item
 {patched resource item}

# update out_of_office, notification_mute and sound_operator_on of a certain operator at once
curl --request PATCH \
     --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --header "Content-Type: application/json" \
     "https://api.userlike.com/api/um/v3/operators/{id}/" \
     --data '{"out_of_office": true, "notification_mute": false, "sound_operator_on": true}'

 # result is the updated resource item
 {patched resource item}

Operator single endpoint - Change operator status

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.

javascript
# set a certain operator to away
curl --location --request PATCH 'https://api.userlike.com/api/um/v3/operators/{id}/away/' \
     --header 'Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf' \
     --header 'Content-Type: application/json' \
     --data '{"away": true}'

# resulting JSON response, containing only the Operator's id and slot data
{
    "id": 5,
    "um_slots": {
        "available": false,
        "availability": "unavailable",
        "free": 0,
        "used": 0,
        "total": 5,
        "connected": true
    }
}

Operator single endpoint - DELETE

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

javascript
# delete operator 144
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --request DELETE \
     "https://api.userlike.com/api/um/v3/operators/144/"

# no result data - expected response status
HTTP/1.1 204 No Content

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 accountDelete 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.

javascript
# try deleting the owner
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --request DELETE \
     "https://api.userlike.com/api/um/v3/operators/140/"

# result explaining the 403 Forbidden
{
    "detail":"Cannot delete owner"
}

# try deleting the operator making the call
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     --header "USERLIKE-OPERATOR-ID: 155" \
     --request DELETE \
     "https://api.userlike.com/api/um/v3/operators/155/"

# result explaining the 403 Forbidden status
{
    "detail":"Cannot delete operator making the request"
}

Operator single endpoint - SLOT VIEW

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.

javascript
# GET chat slot utilization for operator 144
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/operators/5/slots/"


# resulting JSON, containing only the Operator's id and slot data
{
    "id": 5,
    "um_slots": {
        "availability": "unavailable",
        "available": false,
        "connected": true,
        "free": 0,
        "total": 5,
        "used": 0
    }
}

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:

Field	Description
`availability`	The operator’s presence status, combined from the fields "available" and "connected". Its value can be "available", "unavailable" or "offline".
`available`	Whether the operator is available to chat
`connected`	Whether the operator is currently connected to the Message Center
`free`	Number of free chat slots
`used`	Number of used chat slots
`total`	Number of the operator’s total chat slots

Fetching conversations that were recently created or updated

Since this is a common use case we wrote this section to explain the best ways to keep conversations in your system in sync with changes on our side.

To get all conversations created or updated in a certain timeframe, use the updated_at_from_date and updated_at_to_date filters. Whenever changes are made to the conversation or a message is sent in it, this timestamp is updated.

# get conversations updated on the 1st January, 2022
curl --header "Authorization: ee6bd15d-c8f7-3c55-b7dd-82e5970418cf" \
     "https://api.userlike.com/api/um/v3/conversations/?updated_at_from_date=2022-01-01T00:00:00&updated_at_to_date=2022-01-02T00:00:00"

Python Examples

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.

Simple example: fetch last conversations

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.

javascript
import requests
import os
import json

API_TOKEN = os.environ.get("API_TOKEN") or "ee6bd15d-c8f7-3c55-b7dd-82e5970418cf"
API_HOST = os.environ.get("API_HOST") or "https://api.userlike.com"
headers = {"Authorization": API_TOKEN}

# make request, using the authorization header we just defined
resp = requests.get(
    "{}/api/um/v3/conversations/".format(API_HOST), headers=headers, verify=False
)

if resp.status_code == 200:
    print(json.dumps(resp.json(), indent=4, sort_keys=True))
else:
    print("Error status=%s" % resp.status_code)

Slightly more complex example: add phone numbers from your CRM to contacts in Userlike

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.

javascript
import requests
import os

API_TOKEN = os.environ.get("API_TOKEN") or "ee6bd15d-c8f7-3c55-b7dd-82e5970418cf"
API_HOST = os.environ.get("API_HOST") or "https://api.userlike.com"
headers = {"Authorization": API_TOKEN}

# Data from your CRM
CUSTOMER_DATA = [
    {"email": "john.doe@example.com", "mobile_number": "+4917123456789"},
    # ...
]

for customer in CUSTOMER_DATA:
    # 1. Get contact data
    filter_params = {"email": customer["email"]}
    resp = requests.get(
        "{}/api/um/v3/contact_identities/".format(API_HOST),
        headers=headers,
        params=filter_params,
        verify=False,
    )

    assert resp.json()["count"] == 1
    contact = resp.json()["results"][0]

    # 2. Update mobile number in contact
    # Using the json parameter in requests automatically sets the 'Content-Type'
    # in the header to 'application/json'. With other libraries, you might have
    # to the the 'Content-Type' header manually for PATCH requests.
    resp = requests.patch(
        "{}/api/um/v3/contact_identities/{}/".format(API_HOST, contact["id"]),
        headers=headers,
        json={"mobile_number": customer["mobile_number"]},
        verify=False,
    )
    assert resp.status_code == 200
    print(f"Updated {customer['email']}")