Conversations

Conversations capture every back-and-forth your agents have with people — chat sessions on your site, phone calls, SMS threads, inbound emails, and form submissions. Each conversation belongs to an agent (bot_id) and may be linked to a Contact and/or an anonymous Visitor. You can read transcripts, update inbox state (assignment, archive, takeover, internal notes), and soft-delete conversations from the API. Creating conversations is not supported — they originate from real channel events (the chat widget, voice/SMS webhooks, inbound email, form submissions) so that routing, billing, and analytics stay accurate.

Looking for the full transcript of a single conversation? Fetch the conversation, then call List messages with order=asc.

The Conversation object

string

Unique conversation identifier.

bot_id

string

The agent this conversation belongs to.

contact_id

string | null

The CRM contact linked to this conversation, if one has been resolved.

type

integer

Channel the conversation happened on. See Conversation types below.

string | null

Best-known email for the participant (may be null for anonymous chats).

phone_number

string | null

E.164 phone number for the participant on voice / text conversations.

human

string | null

Display name of the human, when known.

human_takeover

boolean

true when a human teammate has taken over the conversation from the agent.

assigned_to

string | null

User ID of the teammate the conversation is assigned to.

assigned_at

string | null

ISO 8601 timestamp of the most recent assignment.

active

boolean

true while the conversation is in progress; flips to false after a period of inactivity.

archived

boolean | null

archived_at

string | null

deleted

boolean | null

Soft-delete flag. Deleted conversations are excluded from list responses unless you pass include_deleted=true.

deleted_at

string | null

internal

boolean

true for conversations between teammates (e.g. asking your internal agent), false for customer-facing conversations.

internal_notes

string | null

Free-text notes added by your team. Never shared with the participant.

last_message

string | null

Snippet of the most recent message — useful for inbox-style list views.

last_message_at

string | null

ISO 8601 timestamp of the most recent message.

last_active_at

string | null

ISO 8601 timestamp of the participant’s most recent activity (typing, page change, etc.).

sentiment_positive

boolean | null

true if Clarky’s sentiment analysis judged the conversation as net-positive, false if negative, null if not yet analyzed.

sentiment_score

number | null

Sentiment score in the range [-1, 1].

sentiment_summary

string | null

One-sentence summary of the participant’s mood and intent.

audio_url

string | null

Storage path for the call recording on voice conversations. Use the dashboard or a workspace-authenticated session to download.

minutes

number | null

Duration of voice / phone calls, in minutes.

visitor_id

string | null

Linked anonymous Visitor, when the conversation came from an unauthenticated chat.

created_at

string

ISO 8601 timestamp.

Conversation types

The type field is a numeric ID. The list endpoint also accepts the names below as a convenience.

`type`	Name	Channel
`1`	`chat`	Web chat widget
`2`	`phone` (or `voice`, `call`)	Inbound or outbound voice calls
`3`	`text` (or `sms`)	SMS / text-message threads
`4`	`email`	Inbound email threads
`5`	`form`	Form submissions

The Message object

string

conversation_id

string

role

string

Who sent the message. Common roles: user (participant), assistant (the agent), system, tool, human (a human teammate during takeover).

content

string

The text payload of the message. May be empty for tool-only messages.

content_type

string | null

MIME hint for the content (e.g. text/plain, text/markdown).

status

string | null

Delivery status, when available — e.g. sent, delivered, failed.

tool_used

string | null

Name of the tool the assistant called, when this message represents a tool invocation.

tool_arguments

object | null

JSON arguments passed to the tool.

created_at

string

ISO 8601 timestamp.

List conversations

method

GET

GET /api/v1/conversations

Returns a paginated list of conversations across all agents in your workspace. Sorted by created_at descending by default.

Query parameters

Param	Type	Description
`bot_id`	string	Filter to a single agent
`contact_id`	string	Filter to conversations linked to a specific contact
`visitor_id`	string	Filter to conversations linked to a specific anonymous visitor
`assigned_to`	string	Filter by the user ID of the assigned teammate
`type`	string \| integer	Filter by channel — `chat`, `phone`, `text`, `email`, `form`, or numeric `1`–`5`
`active`	boolean	`true` for in-progress conversations, `false` for inactive
`archived`	boolean	Filter on the archived flag (omit to include both)
`human_takeover`	boolean	`true` for conversations currently being handled by a human
`include_deleted`	boolean	Pass `true` to include soft-deleted conversations
`created_after`	string (ISO 8601)	Created at or after this timestamp
`created_before`	string (ISO 8601)	Created at or before this timestamp
`last_message_after`	string (ISO 8601)	Most-recent message at or after this timestamp
`last_message_before`	string (ISO 8601)	Most-recent message at or before this timestamp
`search`	string	Substring match against the latest message snippet, email, phone, or human name
`sort`	string	`created_at` (default) or `last_message_at`
`order`	string	`desc` (default) or `asc`
`page`	integer	See Pagination
`page_size`	integer	See Pagination

Example

curl "https://clarky.ai/api/v1/conversations?type=chat&active=true&page_size=10" \
  -H "Authorization: Bearer ck_live_example"

{
  "data": [
    {
      "id": "conv_01HXYZ...",
      "bot_id": "b_01HDEF...",
      "contact_id": "c_01HABC...",
      "type": 1,
      "email": "ada@example.com",
      "phone_number": null,
      "human": "Ada Lovelace",
      "human_takeover": false,
      "assigned_to": null,
      "assigned_at": null,
      "active": true,
      "archived": false,
      "archived_at": null,
      "deleted": false,
      "deleted_at": null,
      "internal": false,
      "internal_notes": null,
      "last_message": "Sounds good, talk soon!",
      "last_message_at": "2026-04-30T14:21:00.000Z",
      "last_active_at": "2026-04-30T14:21:30.000Z",
      "sentiment_positive": true,
      "sentiment_score": 0.74,
      "sentiment_summary": "Customer is excited about the upcoming demo.",
      "audio_url": null,
      "minutes": null,
      "visitor_id": "v_01HVIS...",
      "created_at": "2026-04-30T14:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 10, "total": 1, "total_pages": 1 }
}

Get a conversation

method

GET

GET /api/v1/conversations/{id}

Fetches a single conversation by ID. Returns 404 not_found if the conversation does not exist or belongs to another workspace.

Example

curl https://clarky.ai/api/v1/conversations/conv_01HXYZ \
  -H "Authorization: Bearer ck_live_example"

{
  "data": {
    "id": "conv_01HXYZ...",
    "bot_id": "b_01HDEF...",
    "contact_id": "c_01HABC...",
    "type": 1,
    "human": "Ada Lovelace",
    "human_takeover": false,
    "active": true,
    "last_message": "Sounds good, talk soon!",
    "last_message_at": "2026-04-30T14:21:00.000Z",
    "sentiment_positive": true,
    "sentiment_score": 0.74,
    "created_at": "2026-04-30T14:00:00.000Z"
  }
}

Update a conversation

method

PATCH

PATCH /api/v1/conversations/{id}

Requires a key with the write scope. Updates the listed fields and leaves everything else untouched. Use this to manage inbox state — assigning conversations to teammates, archiving, taking over from the agent, or adding private notes.

Body fields

Field	Type	Description
`internal_notes`	string \| null	Private notes for your team. Never shared with the participant.
`assigned_to`	string \| null	User ID of the teammate who should own this conversation. Pass `null` to unassign.
`archived`	boolean	`true` to archive, `false` to unarchive.
`human_takeover`	boolean	`true` to mute the agent and let a human reply.
`active`	boolean	Mark the conversation in-progress (`true`) or closed (`false`).

Setting assigned_to automatically updates assigned_at. Setting archived automatically updates archived_at. You don’t need to send those fields yourself.

Example: assign a conversation

curl -X PATCH https://clarky.ai/api/v1/conversations/conv_01HXYZ \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{
    "assigned_to": "u_01HUSER",
    "internal_notes": "Hot lead — follow up by EOD."
  }'

{
  "data": {
    "id": "conv_01HXYZ...",
    "bot_id": "b_01HDEF...",
    "contact_id": "c_01HABC...",
    "assigned_to": "u_01HUSER...",
    "assigned_at": "2026-04-30T19:10:00.000Z",
    "internal_notes": "Hot lead — follow up by EOD.",
    "archived": false,
    "active": true,
    "created_at": "2026-04-30T14:00:00.000Z"
  }
}

Example: archive

curl -X PATCH https://clarky.ai/api/v1/conversations/conv_01HXYZ \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'

Example: take over from the agent

curl -X PATCH https://clarky.ai/api/v1/conversations/conv_01HXYZ \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{ "human_takeover": true }'

Updating human_takeover only flips the flag — sending the actual reply still happens through the agent’s channel (chat widget, SMS, etc.). Use takeover to silence the agent while a human responds in the dashboard.

Delete a conversation

method

DELETE

DELETE /api/v1/conversations/{id}

Requires a key with the write scope. Returns 204 No Content with an empty body on success. This is a soft delete — the conversation is hidden from list responses (and from the dashboard inbox) but transcripts, recordings, and analytics are preserved. Pass include_deleted=true on List conversations to surface deleted records, and PATCH with deleted: false is not supported via the API; restoration is dashboard-only.

Example

curl -X DELETE https://clarky.ai/api/v1/conversations/conv_01HXYZ \
  -H "Authorization: Bearer ck_live_example"

Deleting a conversation removes it from your inbox and all dashboard views. The underlying transcript is retained for compliance and analytics, but cannot be re-surfaced through the public API.

List messages in a conversation

method

GET

GET /api/v1/conversations/{id}/messages

Returns the messages in a single conversation, paginated. Defaults to chronological order (order=asc) — the natural read order for a transcript.

Query parameters

Param	Type	Description
`role`	string	Filter to messages from a single role — e.g. `user`, `assistant`, `human`, `tool`
`created_after`	string (ISO 8601)	Created at or after this timestamp
`created_before`	string (ISO 8601)	Created at or before this timestamp
`order`	string	`asc` (default) or `desc`
`page`	integer	See Pagination
`page_size`	integer	See Pagination

Example

curl "https://clarky.ai/api/v1/conversations/conv_01HXYZ/messages?page_size=50" \
  -H "Authorization: Bearer ck_live_example"

{
  "data": [
    {
      "id": "msg_01HMSG1...",
      "conversation_id": "conv_01HXYZ...",
      "role": "user",
      "content": "Hi! Do you support importing from HubSpot?",
      "content_type": "text/plain",
      "status": null,
      "tool_used": null,
      "tool_arguments": null,
      "created_at": "2026-04-30T14:00:05.000Z"
    },
    {
      "id": "msg_01HMSG2...",
      "conversation_id": "conv_01HXYZ...",
      "role": "assistant",
      "content": "Yes — we have a one-click HubSpot importer. Want me to walk you through it?",
      "content_type": "text/markdown",
      "status": "delivered",
      "tool_used": null,
      "tool_arguments": null,
      "created_at": "2026-04-30T14:00:08.000Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 50, "total": 2, "total_pages": 1 }
}

For long transcripts, page through with page_size=100 (the maximum) to minimize round-trips. The total message count is in pagination.total.

List a contact’s conversations

method

GET

GET /api/v1/contacts/{contact_id}/conversations

Convenience endpoint that returns every conversation linked to a single contact, across all agents and channels.

Query parameters

Param	Type	Description
`include_deleted`	boolean	Pass `true` to include soft-deleted conversations
`page`	integer	See Pagination
`page_size`	integer	See Pagination

Example

curl https://clarky.ai/api/v1/contacts/c_01HABC/conversations \
  -H "Authorization: Bearer ck_live_example"

{
  "data": [
    {
      "id": "conv_01HXYZ...",
      "bot_id": "b_01HDEF...",
      "contact_id": "c_01HABC...",
      "type": 1,
      "last_message": "Sounds good, talk soon!",
      "last_message_at": "2026-04-30T14:21:00.000Z",
      "created_at": "2026-04-30T14:00:00.000Z"
    },
    {
      "id": "conv_01HOLD...",
      "bot_id": "b_01HDEF...",
      "contact_id": "c_01HABC...",
      "type": 2,
      "minutes": 12,
      "last_message_at": "2026-04-15T10:05:00.000Z",
      "created_at": "2026-04-15T09:53:00.000Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 25, "total": 2, "total_pages": 1 }
}

Common patterns

Sync new conversations to a data warehouse

Poll for conversations that have started since your last sync.

curl "https://clarky.ai/api/v1/conversations?created_after=2026-04-30T00:00:00Z&sort=created_at&order=asc" \
  -H "Authorization: Bearer ck_live_example"

Pull a full transcript

# 1. Fetch the conversation (for metadata).
curl https://clarky.ai/api/v1/conversations/conv_01HXYZ \
  -H "Authorization: Bearer ck_live_example"

# 2. Page through its messages in order.
curl "https://clarky.ai/api/v1/conversations/conv_01HXYZ/messages?page_size=100&order=asc" \
  -H "Authorization: Bearer ck_live_example"

Find every chat a customer has had with you

curl https://clarky.ai/api/v1/contacts/c_01HABC/conversations \
  -H "Authorization: Bearer ck_live_example"

Auto-assign new conversations from your CRM

Combine List conversations with Update a conversation to route inbound chats to the right rep. Filter for unassigned, in-progress conversations and PATCH each one with the right assigned_to.

curl "https://clarky.ai/api/v1/conversations?active=true&type=chat" \
  -H "Authorization: Bearer ck_live_example"

curl -X PATCH https://clarky.ai/api/v1/conversations/conv_01HXYZ \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{ "assigned_to": "u_01HUSER" }'

Getting Started

Resources

The Conversation object

Conversation types

The Message object

List conversations

Query parameters

Example

Get a conversation

Example

Update a conversation

Body fields

Example: assign a conversation

Example: archive

Example: take over from the agent

Delete a conversation

Example

List messages in a conversation

Query parameters

Example

List a contact’s conversations

Query parameters

Example

Common patterns

Sync new conversations to a data warehouse

Pull a full transcript

Find every chat a customer has had with you

Auto-assign new conversations from your CRM

Getting Started

Resources

Documentation Index

​The Conversation object

​Conversation types

​The Message object

​List conversations

​Query parameters

​Example

​Get a conversation

​Example

​Update a conversation

​Body fields

​Example: assign a conversation

​Example: archive

​Example: take over from the agent

​Delete a conversation

​Example

​List messages in a conversation

​Query parameters

​Example

​List a contact’s conversations

​Query parameters

​Example

​Common patterns

​Sync new conversations to a data warehouse

​Pull a full transcript

​Find every chat a customer has had with you

​Auto-assign new conversations from your CRM

The Conversation object

Conversation types

The Message object

List conversations

Query parameters

Example

Get a conversation

Example

Update a conversation

Body fields

Example: assign a conversation

Example: archive

Example: take over from the agent

Delete a conversation

Example

List messages in a conversation

Query parameters

Example

List a contact’s conversations

Query parameters

Example

Common patterns

Sync new conversations to a data warehouse

Pull a full transcript

Find every chat a customer has had with you

Auto-assign new conversations from your CRM