List chat sessions

get/v2.1/chat/sessions

Requires any one of these rolesAbout roles

org.permission.conversation.read

The API key or user must hold at least one of them.

List chat sessions for a customer and/or tracking id using an API token.

Identity is supplied via query parameters (customerId, trackingId), not via a /c/ tracking JWT. At least one of customerId or trackingId is required (400 if neither is provided). When both are present, sessions matching either identity are returned (SDK-style $or union).

Optional active and brandId match Chat SDK GET /c/v1/chat/sessions filter semantics. Results are sorted by lastMessageAt descending and paginated.

This is distinct from the private GET /v1/customers/{customerId}/chat/sessions route (customer path only; not documented here).

About this resource

Chat conversations

The server-side chat API lets your backend take part in Kustomer chat with a regular API key. It can open chat sessions for a customer, post messages as the customer, an agent or an assistant, show typing, import bot conversations and record satisfaction ratings.

A chat session is a Kustomer conversation on the chat channel, seen from the chat side. Its ID is the conversation ID, so the same conversation appears in the agent desktop and in the customer's chat widget or app, and you can read it with the conversations API too. Sessions are usually created by the chat SDKs when a customer starts a chat. These v2.1 endpoints do the same jobs from your server, for custom chat front ends, messaging bridges and bots that answer before a human does. Anything you post is delivered in realtime to the customer's open chat on every device.

A session stays active until the chat is ended or deleted. Listing with active=true returns only active sessions that have at least one message.

Identity: customerId and trackingId

These endpoints never use a chat key or a customer's chat login token. Every request names the customer in customerId, and Kustomer checks it against the session: a mismatch fails with 403. trackingId is the chat SDK's ID for a visitor's browser or device. It's optional, but when a session has one, any trackingId you send must match. Creating a session without one reuses the tracking ID from the customer's latest chat session, if there is one; handoff imports never set one.

Use a server-side API key with the roles each endpoint lists, never a chat key, which must hold only org.tracking.

Who a message is from

Endpoint	Appears as
`POST /v2.1/chat/messages`	The customer (`direction: in`). Returns `202 Accepted`; the message is processed asynchronously.
`POST /v2.1/chat/assistant/messages`	The customer, replying inside an assistant (bot) flow, so the assistant continues from where it is.
`POST /v2.1/chat/outbound/messages`	An agent: `from` is the Kustomer user ID. Add `auto: true` for bot or AI replies so they don't count as a human first response.
`POST /v2.1/chat/outbound/assistant/messages`	An assistant line, attributed to `from`. Send exactly one of `body`, `meta.template` or `attachments`.

Message bodies are up to 10,240 characters. Typing indicators are ephemeral and never stored. Your service owns their lifecycle: sending a message doesn't hide one, so send typing: false when you're done, and resend typing: true about every three seconds for long answers.

Which endpoint to use

To	Call
Open a chat for a customer, optionally starting an assistant	`POST /v2.1/chat/sessions`
Import a conversation your own bot already had	`POST /v2.1/chat/handoff`
List a customer's or visitor's chats	`GET /v2.1/chat/sessions`
Read a chat's messages	`GET /v2.1/chat/sessions/{id}/messages`
Post as the customer	`POST /v2.1/chat/messages` or, in an assistant flow, `POST /v2.1/chat/assistant/messages`
Post as an agent or bot	`POST /v2.1/chat/outbound/messages`
Post as an assistant	`POST /v2.1/chat/outbound/assistant/messages`
Show or hide typing	`POST /v2.1/chat/outbound/typing`
Record a CSAT rating or comment	`PUT /v2.1/chat/satisfaction-responses/{id}`

A handoff takes 2 to 100 messages, including at least one inbound and one outbound, and sorts them by date; active: false creates the conversation already closed. When you pass assistant on session create, Kustomer posts the assistant's greeting, and if that fails the session is still created. Session lists are paginated, newest first by lastMessageAt, and don't include messages. The CSAT response must already exist, created by Kustomer for the chat's survey; this call fills it in, and sending answers marks it commented rather than rated.

Query parameters

customerIdstring

Kustomer customer ID. Required if trackingId is omitted.

trackingIdstring

Chat tracking ID. Required if customerId is omitted.

activeboolean

When set, only return sessions whose lock/deleted state matches (SDK parity). Active sessions must also have lastMessageAt.

brandIdstring

Filter sessions by brand.

pageinteger

Page number for pagination.

pageSizeinteger

Page size for pagination.

Responses

Paginated list of chat sessions.

array<object>

metaobject

Pagination metadata

linksobject

Pagination links when present

Open in the API console

curl --request GET \
  --url 'https://api.kustomerapp.com/v2.1/chat/sessions' \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"

{
  "data": [
    {
      "type": "chat_session",
      "id": "5679792fbc351e1d007a2993",
      "attributes": {
        "trackingId": "55d7998f2d3f9f8800099aef",
        "createdAt": "2026-07-15T13:30:00.000Z"
      },
      "relationships": {
        "org": {
          "data": {
            "type": "org",
            "id": "55d7998f2d3f9f8800099aed"
          }
        },
        "customer": {
          "data": {
            "type": "customer",
            "id": "55d7998f2d3f9f8800099aee"
          }
        }
      },
      "links": {
        "self": "/c/v1/chat/sessions/5679792fbc351e1d007a2993"
      }
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 100
  }
}