Skip to main content
GET
List chats
  • Credential: an API key. A trial key returns 401 unauthorized.
  • Line-scoped keys: a line-scoped key gets only the chats of the lines of its list.
  • Events: none.
  • Personal data: contact_handle is a phone number or an email address, and it stays after the messages are deleted. Request it only when needed, do not copy it into logs, tickets or other tools, and refer to a contact by an id of your own.
  • Line owner: a chat belongs to its line: after a line changes owner, the account that owns the line lists its chats, those of earlier owners included. See A chat is never deleted.
  • Pagination: a cursor, not tied to the filters. A chat that has a new message during a walk moves to the front of the list, before the cursor, and the walk does not return it. A message that the device reports late can move a chat back, and the walk can then return it twice. Deduplicate on the chat id, then list again with since set earlier than the start of your walk by the reporting delay that you accept. See Cursors.
  • Counters: message_count does not go down when iSnap deletes messages, and unread_count counts every inbound message ever received. See Chats.

Errors

The errors that every operation shares are in Errors.

Authorizations

Authorization
string
header
required

An API key created in the iSnap dashboard, or a trial key, sent as Authorization: Bearer <key>. An API key starts with isnap_live_ or isnap_test_; both act on the same account, lines and billing. A trial key acts on its trial only.

Query Parameters

line_id
string

Only the chats of this line (line_ followed by 25 letters or digits).

Pattern: ^line_[0-9A-Za-z]{25}$
limit
integer
default:20

Number of chats per page, 1 to 100. The default is 20.

Required range: 1 <= x <= 100
cursor
string

The next_cursor of the previous page. Omit it for the first page. Send it with the same filters as the request that returned it.

since
string<date-time>

Inclusive lower bound on last_message_at: an ISO 8601 timestamp with a UTC offset, for example 2026-01-15T14:00:00Z.

until
string<date-time>

Inclusive upper bound on last_message_at: an ISO 8601 timestamp with a UTC offset, for example 2026-01-15T15:00:00Z.

Response

One page of chats.

success
enum<boolean>
required

Always true on a success response.

Available options:
true
data
object
required

One page of chats.

trace_id
string
required

Trace id of the request that produced this response: 32 lowercase hexadecimal characters. Quote it when you report a problem to iSnap.

request_id
string
required

Id of the request that produced this response: req_ followed by 25 letters or digits.