Usage
Customize
API & Integrations

Chatlio Server API

The Chatlio Server API allows you to interact with the Chatlio servers directly. If you have a need for a server API that is not listed below, please let us know!

The server API endpoints are based on REST. They accept form-encoded request bodies, return JSON-encoded responses, and use standard HTTP authentication, request methods and response codes. All endpoint URLs have the following format:

https://api.chatlio.com/v1/api/[endpoint-/specific/part]

Authentication

Calls to the Server API endpoints are authenticated using your Chatlio API key. Here is where you can find it:

  1. Open the Chatlio dashboard.
  2. Select the widget on which you want to use the Server API.
  3. On the Behavior tab, find the “API Key” field in the “Webhooks and post-chat actions” section (click the eye icon to uncover and copy).

API Key

Your API key should be treated as a password, so be sure to keep it secure. Do not share your API key in publicly accessible resources such as code repos and client-side code. If you believe your API key has been compromized, revoke it by generating a new one with the Regenerate API Key button right below the API Key field.

Your API key is scoped to your Chatlio account. To authenticate a server API call, provide your API key as the basic auth username value.

Example:

curl -u YOUR_API_KEY: https://api.chatlio.com/v1/api/chat_endpoints/all/conversation_summary?visitor_data=true

You can also authenticate via bearer auth by including an Authorization header in the call:

curl -H "Authorization: Bearer YOUR_API_KEY" https://api.chatlio.com/v1/api/chat_endpoints/all/conversation_summary

conversation_summary

Retrieves info about currently ongoing conversations for the widgets (also known as chat endpoints) under your Chatlio account.

Method: GET

URLs:

https://api.chatlio.com/v1/api/chat_endpoints/all/conversation_summary
https://api.chatlio.com/v1/api/chat_endpoints/[widget-id]/conversation_summary

To get the summary for a specific chat endpoint, provide the widget ID instead of all in the URL. Here is how to find your widget’s ID:

  1. Open the Chatlio dashboard.
  2. Select the widget that you want to find its ID.
  3. On the Widget Install tab, locate the <chatlio-widget> element embed code and find the value for the widgetid attribute.

If you want the response to include visitor metadata, pass the following parameter to the API call:

visitor_data=true

Example request:

curl -u YOUR_API_KEY: -G -d visitor_data=true 'https://api.chatlio.com/v1/api/chat_endpoints/all/conversation_summary

Example response:

[
  {
    "data_widget_id": "aac51067-2851-452c-9027-74c6521a5122",
    "slack_channel": "C02ZA71UP8Z",
    "slack_channel_url": "https://acme.slack.com/archives/C02ZA71UP8Z",
    "slack_channel_name": "acme-support",
    "unanswered_conversations": null,
    "inprogress_conversations": [
      {
        "slack_channel_name": "z-frank-doe-3183",
        "slack_channel_id": "C1539ZA5728",
        "slack_channel_url": "https://acme.slack.com/archives/C1539ZA5728",
        "first_message": "Hello there. I have a question about Acme Power W153",
        "visitor": {
          "ip_address": "192.168.1.24",
          "current_page_url": "https://acme.com/store/widgets/power-w153",
          "browser_info": "Firefox 98.0 Windows 10",
          "identify_user_id": "737",
          "location": "Amsterdam, Netherlands",
          "location_url": "https://www.google.com/maps?q=123,123",
          "local_time": "03:57am (CEST)",
          "identify_data": {
            "account": "4245122",
            "email": "[email protected]",
          }
        }
      }
    ]
  }
]

chat_endpoints/:widget-id

Retrieves the status of the widget. Status will return online, offline, or busy.

NOTE: busy is returned when the widget is online but the “Max concurrent chats” (see Presence and widget behavior section on the Chatlio dashboard Behavior tab) is enabled and the threshold has been met.

NOTE: This endpoint’s status metadata reflects the general availability of the chat service, not individual visitor access which may be restricted by country, ban status, or page-specific rules..

Method: GET

URL:

https://api.chatlio.com/v1/api/chat_endpoints/[widget-id]

Here is how to find your widget’s ID:

  1. Open the Chatlio dashboard.
  2. Select the widget that you want to find its ID.
  3. On the Widget Install tab, locate the <chatlio-widget> element embed code and find the value for the widgetid attribute.

Example request:

curl -u YOUR_API_KEY: -G 'https://api.chatlio.com/v1/api/chat_endpoints/[widget-id]'

Example response:

{
  "data_widget_id":"aac51067-2851-452c-9027-74c6521a5122",
  "slack_channel_name":"acme-support",
  "status":"online"
}

chat_endpoints/:widget-id/chat_history

Starts an asynchronous export of chat transcripts for a widget within a date range. The response payload for each conversation matches the format used by the chat transcript webhook.

NOTE: This endpoint requires the “Store chat message content” feature to be enabled for your account. You can enable it from the Chatlio dashboard account page.

NOTE: Only one export job can run at a time per account. If a job is already in progress, wait for it to complete before starting another.

Method: POST

URL:

https://api.chatlio.com/v1/api/chat_endpoints/[widget-id]/chat_history?start_date=[start]&end_date=[end]

Parameters:

Parameter          Required      Description
start_date Yes Start of the date range. Format: YYYY-MM-DD.
end_date Yes End of the date range. Format: YYYY-MM-DD.

The date range must not exceed 1 year. Only archived (completed) conversations that started within the date range are included.

Here is how to find your widget’s ID:

  1. Open the Chatlio dashboard.
  2. Select the widget that you want to find its ID.
  3. On the Widget Install tab, locate the <chatlio-widget> element embed code and find the value for the widgetid attribute.

Example request:

curl -X POST -u YOUR_API_KEY: 'https://api.chatlio.com/v1/api/chat_endpoints/[widget-id]/chat_history?start_date=2025-01-01&end_date=2025-12-31'

Example response:

{
  "job_id": "job_655eff10-096",
  "status": "pending"
}

Use the job_id value to poll for results using the chat_history_jobs endpoint below.

chat_history_jobs/:job_id

Retrieves the status of a chat history export job. When the job is complete, the response includes the full transcript data in the data field. Results are cached for 1 hour after the job completes. If the cache has expired, re-run the export.

Method: GET

URL:

https://api.chatlio.com/v1/api/chat_history_jobs/[job_id]

Example request:

curl -u YOUR_API_KEY: 'https://api.chatlio.com/v1/api/chat_history_jobs/job_655eff10-096'

Example response (in progress):

{
  "job_id": "job_655eff10-096",
  "status": "processing",
  "progress": 42
}

Example response (completed):

{
  "job_id": "job_655eff10-096",
  "status": "completed",
  "progress": 100,
  "completed_at": "2025-06-15T18:30:00Z",
  "data": [
    {
      "conversationUUID": "cab1c933-735b-4e41-7177-76c309f2d246",
      "channelId": "C088HPJ52TA",
      "slackTeamID": "TED6W2ZBM",
      "channelName": "frank-doe-81",
      "startedAt": "2025-06-15T11:40:02-05:00",
      "endedAt": "2025-06-15T11:45:30-05:00",
      "agentEmail": "[email protected]",
      "agentName": "Jane Smith",
      "visitorEmail": "[email protected]",
      "visitorName": "Frank Doe",
      "visitorTraits": "{\"plan\":\"Pro\"}",
      "visitor": {
        "email": "[email protected]",
        "UUID": "b8ed982d-4c4f-4605-afc2-486a43d5c97d",
        "name": "Frank Doe",
        "identUserId": "737",
        "userAgent": "Mozilla/5.0 ...",
        "handle": "frank-doe-81",
        "currentPage": "https://acme.com/support",
        "createdAt": "2025-06-15T16:39:26Z",
        "IPAddress": "192.168.1.24",
        "location": "Amsterdam, Netherlands"
      },
      "visitorQuestionsAndAnswers": [
        {
          "questionGroupUID": "qg-123",
          "questionsAndAnswers": [
            {"question": "What is your account ID?", "answer": "4245122"}
          ]
        }
      ],
      "messages": [
        {
          "text": "Hello, I need help with my account.",
          "ts": "1750002002.873289",
          "sentAt": "2025-06-15T11:40:02-05:00",
          "sentAtInZone": "11:40am (CDT)",
          "userId": "737",
          "username": "Frank Doe",
          "isVisitorMsg": true
        },
        {
          "text": "Hi Frank! I'd be happy to help.",
          "ts": "1750002150.112233",
          "sentAt": "2025-06-15T11:42:30-05:00",
          "sentAtInZone": "11:42am (CDT)",
          "userId": "UED4X3K4L",
          "username": "Jane S.",
          "isVisitorMsg": false
        }
      ],
      "chatRating": "up",
      "chatFeedback": "Very helpful!"
    }
  ]
}

Example response (cache expired):

{
  "job_id": "job_655eff10-096",
  "status": "completed",
  "progress": 100,
  "completed_at": "2025-06-15T18:30:00Z",
  "data_expired": true,
  "message": "result data has expired from cache; please re-run the export"
}
:(
Your browser is out-of-date!

This website is built using latest technogies. Unfortunately your browser doesn't support those. Please update your browser to view this website correctly. Thank you.Update my browser now