Chat Conversations API

Beta. This read-only conversations API is rolling out. To get access — including your endpoint base URL and API credentials — contact the Chatty support team from your dashboard.

ⓘ

Who can use this feature?

Available to all plans (during beta, on request).
Read-only — it returns conversation data; it does not send messages or modify anything.

Overview

The Chat Conversations API lets you read your store's live chat history — conversations, their messages, counts, and related threads — so you can mirror them into your own helpdesk, build a custom inbox view, or run reporting.

Every request is scoped to your store: your API key identifies the shop, and the API only ever returns that shop's data.

Authentication

Authenticate with your Chatty API key (generate one under Settings > API — see the API overview). The key represents your store, so every request is automatically limited to your own conversations.

ⓘ

The exact request header and endpoint base URL are provided when the beta is enabled for your store. Keep your key private — never expose it in front-end code.

Rate limits

Limit	Value
Per IP address	300 requests/min
Per API key	120 requests/min

Exceeding a limit returns 429 Too Many Requests. Other error responses follow standard HTTP codes: 400 (bad request), 401 (unauthenticated), 404 (not found). For privacy, requesting a conversation that isn't yours returns the same 404 as one that doesn't exist.

Endpoints

All endpoints are GET and read-only.

Endpoint	Returns
`/chat/conversations`	List of conversations (filterable, paginated).
`/chat/conversations/{id}`	A single conversation.
`/chat/conversations/{id}/messages`	Messages in a conversation (paginated).
`/chat/conversations/{id}/messages/{messageId}`	A single message.
`/chat/conversations/{id}/related`	Other conversations from the same customer.
`/chat/conversations/count`	Conversation counts (open / unread / unassigned).
`/chat/customers/{customerUuid}/conversations`	All conversations for one customer.

List conversations

GET /chat/conversations

Query param	Example	Description
`status`	`open`	Filter by conversation status.
`tag`	`pre-sale`	Filter by tag.
`email`	`[email protected]`	Filter by customer email.
`assigneeId`	`unassigned`	Filter by assigned agent, or `unassigned`.
`channel`	`whatsapp`	Filter by channel.
`limit`	`20`	Page size.

{
  "data": [
    {
      "id": "...",
      "customerName": "...",
      "status": "open",
      "messageCount": 6,
      "lastMessage": { "text": "...", "senderType": "customer" },
      "tags": ["pre-sale"]
    }
  ],
  "paging": { "nextCursor": "...", "hasMore": true },
  "meta": { "source": "postgresql" }
}

Get a single message

GET /chat/conversations/{id}/messages/{messageId}

Returns one message. Deleted messages return "isDeleted": true rather than a 404, so you can reconcile your own copy.

{
  "data": {
    "id": "518edc4e-dc1b-4a0c-a9bd-ef00f3e67fd7",
    "senderType": "customer",
    "text": "Hi, do you have the Daris Tee in size M?"
  },
  "meta": { "source": "postgresql" }
}

Conversation counts

GET /chat/conversations/count

{
  "data": { "open": 280, "unread": 3, "unassigned": 278 }
}

Counts are cached briefly (about 30 seconds), so they're fast but may lag real time by a few seconds.

Response format

Every endpoint returns the same envelope:

{
  "data": "...",
  "paging": { "nextCursor": "...", "hasMore": true },
  "meta": { "source": "postgresql" }
}

data — the conversation(s) or message(s).
paging — present on list endpoints. To get the next page, pass nextCursor back on your next request; stop when hasMore is false.
meta.source — which backend served the data. You can ignore it; it's informational.

Need help?

To join the beta or troubleshoot a request, contact the Chatty support team from your dashboard. For reading customer/contact data instead of conversations, see the GraphQL Customer API.

GraphQL Customer API Webhooks