Conversations
The list of conversations, one conversation, closing it. Fields of the conversation object.
The list of conversations #
GET /api/v1/conversations conversations:read
| Field | Type | Req. | Description |
|---|---|---|---|
| status | string | no | open, pending, resolved or closed |
| since | RFC 3339 | no | only the ones changed after this time |
| cursor | RFC 3339 | no | continuation of the previous page |
| limit | int | no | 1…100, 25 by default |
curl -s "https://api.widgetchat.ru/api/v1/conversations?status=open&since=2026-08-22T00:00:00Z" -H "Authorization: Bearer wck_…"{"data": [ /* conversation objects */ ], "nextCursor": "…", "hasMore": true}One conversation #
GET /api/v1/conversations/{id} conversations:read
The conversation id is a UUID. Another site's conversation answers 404 rather than 403: the existence of someone else's ids is information too.
The conversation object #
| Field | Type | Req. | Description |
|---|---|---|---|
| id | uuid | yes | conversation id |
| status | string | yes | open, pending, resolved, closed |
| channel | string | yes | always app: the message comes from the widget |
| visitor.id | string | yes | the visitor's permanent id |
| visitor.name | string | no | the name, if the site passed it |
| visitor.email | string | no | the email, if the site passed it |
| visitor.organization | string | no | the organization from the signed token |
| visitor.accountId | string | no | your customer id from the signed token |
| visitor.role | string | no | the visitor's role from the signed token |
| source | string | no | where the message came from |
| createdAt | RFC 3339 | yes | when it was created |
| lastMessageAt | RFC 3339|null | no | time of the last message |
| lastReadAt | RFC 3339|null | no | how far the visitor has read |
The visitor object carries only what the site itself passed with a signed token. Internal marks of the conversation — the Telegram topic id, the open channel chat — are never served outside.
Close a conversation #
POST /api/v1/conversations/{id}/close conversations:write
A closed conversation stops taking replies: the visitor's next message starts a new one. Closing it again is not an error and produces no event.
{"data": {"id": "6c82f8e2-…", "status": "closed"}}