API Tutorial

Introduction

Welcome to the Userlike API tutorial. Don't hestitate to leave us a note if you miss certain API calls or features. We prepared CURL based examples. With the help of the the CURL tool you can test drive our API quickly from the command line. This should give you a straightforward understanding how to use our API.

TopicDescription
AuthenticationAccessing the API
Offline MessagesRetrieve a list of offline message
ChatsRetrieve a list of chats
OperatorRetrieve a list of Operators
Operator statusChange Operator status
LimitsAPI limits
ExamplesExamples

Authentication

All API requests must be authenticated with an API token. The API token must be passed as Authorization header with each request.

There is an API token for each organization which only allows access to the data of the respective organization. There also is a company API token which allows access to all data.

Offline Messages

Retrieve a list of messages from your customers when you have been offline. Supported methods are GET and DELETE. The result is an JSON array consisting of objects for each email. If you use the Javascript API to pass your custom data to the chat client it will be included in in the "custom" field as an object.

You can add filters to the query via GET parameters to specify the result set. Supported parameters are:

  • count - Numbers of items to fetch. The default value is 100, upper limit is 1000
  • until - Filter items that are created until given date. Format: %Y-%m-%d
  • after - Filter items that are created after given date. Format: %Y-%m-%d
  • organization - Filter items that belong to a specific organization, specified by the organization ID.

You can fetch individual offline messages using the "id" of the item in the URL.

You can fetch offline messages for specific organizations if your are using a company API token. This parameter has no effect if you are using an organization API token.

You can delete individual offline messages using the HTTP DELETE method.

You can also bulk delete all of your offline messages, or a subset, defined by the filters described above.

Calling the API without a specific offline message ID will irrevocably delete many or all of your offline messages.

Chat List

Fetch a list of all our previous chat session. Supported methods are GET and DELETE. The result is an JSON Array consisting of Objects for each chat session. If you use the Javascript API to pass your custom data to the chat client it will be included in in the "custom" field as an object.

You can add filters to the query via GET parameters to specify the result set. Supported parameters are:

  • count - Numbers of items to fetch. The default value is 100, upper limit is 1000
  • until - Filter items that are created until given date. Format: %Y-%m-%d
  • after - Filter items that are created after given date. Format: %Y-%m-%d
  • organization - Filter items that belong to a specific organization, specified by the organization ID.

You can fetch individual chat sessions using the "id" of the item in the URL.

You can fetch chat sessions for specific organizations if you are using a company API token. This parameter has no effect if you are using an organization API token.

You can delete individual chat sessions using the HTTP DELETE method.

You can also bulk delete all of your chat sessions, or a subset, defined by the filters described above.

Calling the API without a specific chat session ID will irrevocably delete many or all of your chat sessions.

Operator List

We also offer an API to access your team. You can fetch a list of all Operators in your account. You can get details like "username", "email" and primary "id", which can be used in other API calls to manipulate the operator state.

You can add filters to the query via GET parameters to specify the result set. Supported parameters are:

  • organization - Filter operators that belong to a specific organization, specified by the organization ID.

This parameter can only be used with a company API token. This parameter has no effect if you are using an organization API token.

You can fetch individual operators by using their "id" in the URL.

Operator Status

With this API you can look up the current status of an operator. You can read the online status and current chat slot usage.

FieldDescription
onlineIf the operator is availble to chat
offlineIf the operator is not availble to chat
awayIf the operator is set in pause mode and not availble to chat
freeNumber of free chat slots
usedNumber of used chat slots
lastDatetime of the last chat session

Operator Away Status

With this API you can change the away status of an operator. If you set an operator to away he will not receive new chats, but is able to finish chats that are currently running. This state is persisted even if the operator goes offline and online again. The API is usefull to push state from an application which need the full attention of the chat agent.

FieldDescription
onlineIf the operator is availble to chat
offlineIf the operator is not availble to chat
awayIf the operator is set in pause mode and not availble to chat
freeNumber of free chat slots
usedNumber of used chat slots
lastDatetime of the last chat session

API Rate Limits

You can make up to 1500 API requests per 15-min window. This rate limit is applied when you make an API request using your secret and remote IP.

ResourceMethodRequests/15-min window
http://www.userlike.com/api/external/message/offline_message/GET150
http://www.userlike.com/api/external/message/offline_message/DELETE150
http://www.userlike.com/api/external/message/chat_meta/GET150
http://www.userlike.com/api/external/message/chat_meta/DELETE150
http://www.userlike.com/api/external/message/operator/GET150
http://www.userlike.com/api/external/message/operator/slot/PUT300

API Bulk Limit

Request up to 1000 items per request, this is controlled by the "count" GET parameter.

ResourceMethodCount
http://www.userlike.com/api/external/message/offline_message/GET1000
http://www.userlike.com/api/external/message/offline_message/DELETE10
http://www.userlike.com/api/external/message/chat_meta/GET1000
http://www.userlike.com/api/external/message/chat_meta/DELETE10

Python Examples

We prepared a few samples how to access the Userlike API from python. It's pretty straightforward, we use httlib2 for the HTTP request and add the Authorization to the HTTP headers.

Offline Messages

Retrieve a list of messages from your customers when you have been offline.

Chat List

Fetch a list of all our previous chat session including the transcript.

Chat Session Bulk Delete

Fetch a list of all our previous chat session and delete them.

Operator Away Status

Change the away status of an operator.