Documentation navigation
Documentation

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": "frankdoe@acme.com",
          }
        }
      }
    ]
  }
]

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

Exports the message history for a widget over a date range, as an asynchronous job. This endpoint is currently available as a limited beta for selected accounts.

To use it: contact us at support@chatlio.com with your Chatlio account ID so we can enable the beta for your account, then have an account admin turn on Chat History Storage from the dashboard account page. Message content is only stored (and therefore exportable) from the time storage is enabled onward.

Method: POST

URL:

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

Query parameters:

Parameter Required Description
start_date yes Start of the range, YYYY-MM-DD (interpreted in the widget’s timezone) or an RFC3339 timestamp. Inclusive.
end_date yes End of the range, same formats. A date (YYYY-MM-DD) includes that entire day; an RFC3339 timestamp is treated as an exclusive upper bound. Must be after start_date, and the range must not exceed one year.

Starting an export returns a job_id. Poll the chat_history_jobs/:job_id endpoint with that ID to retrieve the result. Only one export can run per account at a time; requesting another while one is active returns the in-progress job.

Example request:

curl -H "Authorization: Bearer YOUR_API_KEY" -X POST \
  'https://api.chatlio.com/v1/api/chat_endpoints/[widget-id]/chat_history?start_date=2026-06-01&end_date=2026-07-01'

Example response:

{
  "job_id": "9f2c1a7e-4b3d-4f21-8c0a-2d6e5b1f7a90",
  "status": "pending"
}

chat_history_jobs/:job_id

Returns the status and, once complete, the exported data for a chat history job started via chat_history.

Method: GET

URL:

https://api.chatlio.com/v1/api/chat_history_jobs/[job-id]

status is one of pending, processing, completed, or failed. Poll until it is completed (the data field is then present) or failed (an error code is then present). Completed results are cached for a limited time; if you poll after they expire, data_expired is true and you should re-run the export.

Example request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.chatlio.com/v1/api/chat_history_jobs/[job-id]

Example response (completed):

{
  "job_id": "9f2c1a7e-4b3d-4f21-8c0a-2d6e5b1f7a90",
  "status": "completed",
  "progress": 100,
  "completed_at": "2026-07-01T18:22:04Z",
  "data": [
    {
      "conversationUUID": "b1d4...",
      "slackTeamID": "T012ABCDEF",
      "channelID": "C012ABCDEF",
      "channelName": "z-alex-1234",
      "startedAt": "2026-06-14T15:02:11Z",
      "endedAt": "2026-06-14T15:19:40Z",
      "agentEmail": "agent@yourcompany.com",
      "agentName": "Sam",
      "visitorEmail": "visitor@example.com",
      "visitorName": "Alex",
      "visitorTraits": "{\"plan\":\"pro\",\"company\":\"Acme\"}",
      "visitorUserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
      "visitorCurrentPage": "https://shop.example.com/cart",
      "visitorReferrer": "https://www.google.com/",
      "visitorLocation": "Austin, TX, United States",
      "visitorQuestionsAndAnswers": [
        {
          "questionGroupUID": "pre-chat",
          "questionsAndAnswers": [
            { "question": "How can we help?", "answer": "Billing question" }
          ]
        }
      ],
      "messages": [
        {
          "text": "Hi, I have a question about my invoice.",
          "ts": "1718377331.000200",
          "sentAt": "2026-06-14T15:02:11Z",
          "sentAtInZone": "2026-06-14T11:02:11-04:00",
          "username": "Alex",
          "isVisitorMsg": true
        }
      ],
      "chatRating": "good",
      "chatFeedback": "Quick and helpful"
    }
  ]
}

The data array contains one object per conversation in the range. Notes on individual fields:

  • slackTeamID, channelID, and channelName identify the Slack workspace and channel the conversation lived in, for correlating exports against your own Slack data.
  • visitorTraits is the raw identity-trait payload you set for the visitor via the widget identify() call (a JSON string).
  • visitorUserAgent, visitorCurrentPage, visitorReferrer, and visitorLocation describe the visitor’s session; any of them may be empty.
  • chatRating and chatFeedback are only present when the visitor left them.
  • Visitor IP address is not included. Contact us if you have a use case for it.
  • Pre-chat and in-chat questionnaire answers are limited to conversations within the requested date range.

Errors from either endpoint use standard HTTP status codes with a JSON body of the form { "error": true, "code": "...", "message": "..." }. Common cases: 400 for missing or malformed dates, 403 (featureDisabled) if Chat History Storage is not enabled for the account, 404 if the widget or job is not found, and 429 (rateLimited) if too many requests are made in a short window.