PAT authorisation and list_archives

This guide will present the example method of the Personal Access Token generation in order to use the list_archives API method. We will also explain how to apply some of the filters.

Video guide on PAT generating and list_archives method

The following video presents the Personal Access Token generation and calling list_archives endpoint with Postman. Those steps are also described below.

PAT generating

To generate PAT, you will need to have the developers account. You should be able to log int to the Developer Console using your LiveChat or HelpDesk account credentials.

Once you are logged in, head to the Tools section and choose Personal Access Token

The list_archives method requires the chats--all:ro and chats--access:ro scopes. You can think about scopes as access permissions given to the token. Without them the token will not be able to authorise your API call.

In your Personal Access Token section, you need to select the mention scopes.

The name you give to your PAT is not relevent and does not affect the authorisation.

Once you click Create token you need to copy and save it along with the Account ID. Copy and save the token now! You won't be able to see it after page reloads.

Calling list_archives without filters

1. Open your Postman, set your request type to POST, and copy and paste the list_archives endpoint URL

https://api.livechatinc.com/v3.5/agent/action/list_archives

Remember to use the saved Token, not the Base64 Encoded Token.

2. Go to the Headers section and add the KEY Content-Type and its VALUE application/json.

3. Open the Body section and choose raw. Next, you should add {} to your request body. The body of your API request can not be completely "empty" - brackets are needed there.

Once you are ready hit Send. The chats payload should be available to you in the API call response. The most common mistakes are:

• typos (URL, headers, body, authorisation)
• invisible characters (added to URL, headers, body, authorisation)
• empty body (missing {})
• not sufficient scopes
• missing brackets
• missing commas

Example cURL (where XXXXX is your Base64 Encoded Token):

curl --location --request POST 'https://api.livechatinc.com/v3.5/agent/action/list_archives' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic XXXXX' \
--data-raw '{}'

More chats in the response - incresing the response limit

By default each list_archives response contain the payload of 10 chats. If you would like more or fewer chats to be included in each response, you can add the limit parameter to the body of your response. The mnimum value is 1 and the maximum is 100.

Example cURL (where XXXXX is your Base64 Encoded Token):

curl --location --request POST 'https://api.livechatinc.com/v3.5/agent/action/list_archives' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic XXXXX' \
--data-raw '{
    "limit": 100
}'

Pagination - how to see next/previous chats pages (page_id)

At the bottom of the response body you should be able to find the next_page_id or previous_page_id flag and its value. Using that ID you are able to request the next bulk of chats. Each next page contains the number of chats set with the limit as described above.

Our servers remember all the additional parameters and filters used with the initial list_archives call. All further calls only need to contain page_id in their request bodies as the other apply automatically.

Example cURL (where XXXXX is your Base64 Encoded Token and YYYYY is next or previous page ID):

curl --location --request POST 'https://api.livechatinc.com/v3.5/agent/action/list_archives' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic XXXXX=' \
--data-raw '{
 "page_id": "YYYYY"
}'

Setting the order of chats in responses (sort_order)

By adding the sort_order parameter to the request you can choose if the chats should be listed from the newest to oldest (desc) or from the oldest to the newest (asc). The default value of the parameter if not set is desc.

Example cURL (where XXXXX is your Base64 Encoded Token):

curl --location --request POST 'https://api.livechatinc.com/v3.5/agent/action/list_archives' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic XXXXX=' \
--data-raw '{
 "sort_order":"asc"
}'

Filters

By adding filters to your request body you can obtain only some chat payloads with set required parameters. Browsing through next or previous response pages does not require adding the filters again. Only the page ID parameter is needed.

filters.query

The query filter checks if the chat payload contains the provided string. It can be used to search for chats with a specific customer name, email, or message. The query filter is not case sensitive.

Example cURL (where XXXXX is your Base64 Encoded Token):

curl --location 'https://api.livechatinc.com/v3.5/agent/action/list_archives' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic XXXXX' \
--data-raw '{
   "filters":{
       "query":"j.smith@test.com"
   }
}'

highlights (pre-tag, post-tag)

The highlights filter allows you to highlight the provided string in the chat payload. It is highlighted with the some pre-tag and post-tag. The default tags are <em> and </em>.

Example cURL (where XXXXX is your Base64 Encoded Token):

curl --location 'https://api.livechatinc.com/v3.5/agent/action/list_archives' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic XXXXX' \
--data '{
    "highlights":{},
    "filters":{
       "query":"hello"
    }
}'

You can set custom highlight tags change them by adding the pre_tag and post_tag parameters to your request body. The tags can be set to any string. In our example we used <A> and <B>.

Example cURL (where XXXXX is your Base64 Encoded Token):

curl --location 'https://api.livechatinc.com/v3.5/agent/action/list_archives' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic XXXXX' \
--data '{
    "highlights":{
        "pre_tag":"<A>",
        "post_tag":"<B>"
    },
    "filters":{
       "query":"hello"
    }
}'

filters.from and filters.to

You could add a filter to your request body to obtain only the chats that were created after, before or between certain dates. The dates should be provided in the YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM format where +HH:MM is the timezone offset.

Example cURL (where XXXXX is your Base64 Encoded Token):

curl --location 'https://api.livechatinc.com/v3.5/agent/action/list_archives' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic XXXXX' \
--data '{
    "filters":{
       "from": "2023-07-20T08:45:00.000000+02:00",
       "to": "2023-07-27T08:45:00.000000+02:00"
    }
}'

If you have any questions, let us know!

Yours, LiveChat Team <3