Error
A valid request URL is required to generate request examples{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"channel": "email",
"subject": "<string>",
"status": "open",
"created_at": "2023-11-07T05:31:56Z",
"last_message_at": "2023-11-07T05:31:56Z",
"last_read_at": "2023-11-07T05:31:56Z",
"last_message_preview": "<string>",
"last_message_author_kind": "contact"
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Support
Open a support conversation
The chat widget’s door: opens a chat conversation for the contact behind this session, first message included, in one call. Email conversations cannot be opened here — they are born from an inbound email, where the transport itself proves the address; a page claiming “this is an email thread” would be a thread with no email behind it.
Anonymous sessions may open one: the widget runs on pages a visitor has not signed in to, and an anonymous session has nobody to impersonate. A session that claims an identity without having proven it is refused — a support message that arrives as somebody is exactly the assertion the verification gate exists to stop.
The contact support surface carries its own rate-limit budget (1200 requests per hour per session), separate from the rest of /v1/contact/*, so a widget polling an open thread never spends the account surface’s allowance.
POST
/
v1
/
contact
/
conversations
Error
A valid request URL is required to generate request examples{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"channel": "email",
"subject": "<string>",
"status": "open",
"created_at": "2023-11-07T05:31:56Z",
"last_message_at": "2023-11-07T05:31:56Z",
"last_read_at": "2023-11-07T05:31:56Z",
"last_message_preview": "<string>",
"last_message_author_kind": "contact"
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Authorizations
A contact session token, uk_ct_…. Belongs to one of the developer's own users, and reads only that user's data.
Body
application/json
Response
The conversation, as the contact sees it — no assignee, no team-side metadata.
A conversation as the contact sees it: theirs by construction, so no contact id, no assignee, no team-side metadata — who is handling a ticket is the team's business, not the widget's.
Available options:
email, chat Available options:
open, pending, snoozed, resolved How far this contact has read — the unread badge is last_message_at newer than this. Moved by the /read endpoint.
The last public line of the thread, truncated to 240 characters — what a closed widget renders beside the badge, since a sentence is a reason to answer where a number is only a reason to look. An internal note is never it, whatever its timing. Present on the LIST read only, and absent when the conversation has no public message or the preview read failed: the previews are an accessory, and a list that failed over one would take a whole screen down for a line nobody asked to open.
Who wrote the line in last_message_preview. Travels with it because a preview of the contact's own message is not news to the contact.
Available options:
contact, agent, ai, system