List a contact's chat sessions

Returns the contact’s visits to the chat widget, oldest first. A session holds what the browser sent: the page, the IP address, the browser and the language. The chat text itself is in the ticket’s messages, see List messages.

GET /v1/contacts/{id}/sessions

Authentication

Bearer token in the Authorization header. A read-only key is enough. See Authentication.

Authorization: Bearer rfl_live_...

Path parameters

string

required

Contact ID, usually prefixed with con_.

Query parameters

integer

default:"20"

Number of sessions per page. Range 1 to 100.

string

Opaque cursor from the previous response’s nextCursor. See Pagination.

Response

Returns a list envelope containing Session objects. The list is empty for a contact who never used the chat widget.

The Session object

string

Unique identifier.

string

Always "session".

string

The contact’s ID.

string

The chat channel the visit was on.

string | null

The page the widget was opened on, if known.

string | null

The visitor’s IP address, if stored.

string | null

The browser’s User-Agent header, if stored.

string | null

The browser’s Accept-Language header, if stored.

string

ISO 8601 UTC timestamp of when the session started.

string

ISO 8601 UTC timestamp of the visitor’s latest activity in the session.

Examples

List a contact’s sessions

curl "https://api.replyful.com/v1/contacts/con_9dKmT3xWq6bYrN8cJfA2e/sessions?limit=100" \
  -H "Authorization: Bearer rfl_live_..."

const res = await fetch(
  "https://api.replyful.com/v1/contacts/con_9dKmT3xWq6bYrN8cJfA2e/sessions?limit=100",
  { headers: { Authorization: `Bearer ${process.env.REPLYFUL_API_KEY}` } },
);
const { data, hasMore, nextCursor } = await res.json();

Response

{
  "object": "list",
  "data": [
    {
      "id": "Vq3nT8xKb2mWf6cR9yJd4",
      "object": "session",
      "contactId": "con_9dKmT3xWq6bYrN8cJfA2e",
      "channelId": "k3v9x2qa",
      "originUrl": "https://shop.example.com/orders/4821",
      "ipAddress": "203.0.113.42",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Safari/605.1.15",
      "acceptLanguage": "sv-SE,sv;q=0.9,en;q=0.8",
      "createdAt": "2026-04-29T14:29:31Z",
      "lastSeenAt": "2026-04-29T14:41:05Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null,
  "url": "/v1/contacts/con_9dKmT3xWq6bYrN8cJfA2e/sessions"
}

Error responses

Status	`error.code`	When
`401`	`missing_api_key`	The `Authorization` header is absent.
`401`	`invalid_api_key`	The token is malformed, unknown, or archived.
`404`	`contact_not_found`	The contact does not exist, belongs to another organization, or has been erased.
`422`	`invalid_path_parameter`	The `id` path parameter is not a valid contact ID.
`422`	`invalid_query_parameter`	A query parameter failed validation.
`422`	`invalid_cursor`	The `startingAfter` cursor could not be decoded.
`429`	`too_many_requests`	Rate limit exceeded. Honor `Retry-After`.

See Errors for the full error envelope reference.

Documentation

Tickets

Channels

Conversations

Contacts

Attachments

Knowledge

List a contact's chat sessions

Authentication

Path parameters

Query parameters

Response

The Session object

Examples

List a contact’s sessions

Error responses

​Authentication

​Path parameters

​Query parameters

​Response

​The Session object

​Examples

​List a contact’s sessions

​Error responses

Authentication

Path parameters

Query parameters

Response

The Session object

Examples

List a contact’s sessions

Error responses