Get conversations by customer
/v1/customers/{id}/conversationsorg.permission.conversation.readorg.user.conversation.readThe API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.
Retrieves a paginated list of conversations using the unique Customer ID.
When an SLA is attached, attributes.sla.metrics.nextReply may include lifetime
cycle tallies onTimeCount and lateCount (see Get conversation by ID).
Conversations
A conversation is one support thread with one customer, such as an email exchange, a chat session or a phone call. It holds the work state agents manage, including status, assignment, priority and tags, and contains the thread's messages and notes.
Every conversation belongs to exactly one customer and appears on that customer's timeline in the agent desktop. Inside it are messages exchanged with the customer and internal notes from your team. Kustomer creates a conversation when a new inbound email, chat or call arrives, and workflows, agents and integrations can create them too. The conversation is the unit of work: it's what gets routed to a queue, assigned to an agent, measured against an SLA and eventually marked done. A customer can have many conversations over time, open or closed.
Status
status |
Meaning |
|---|---|
open |
Needs attention. Counts toward queues and SLAs. |
snoozed |
Parked until a time or event, set with a snooze object. The conversation reopens when the snooze ends or the customer replies. |
done |
Resolved. A new inbound message normally reopens it. |
You can create a conversation as open or done; snoozing is an update. subStatus adds org-defined detail inside a status, such as "Waiting on warehouse", using an ID from sub-statuses.
Assignment and other work fields
assignedUsers and assignedTeams each hold up to 10 IDs. queue is the routing queue, for orgs that use queues and routing. priority runs from 1 (lowest) to 5 (highest). direction is in when the customer started the thread and out when your team did, for example with a proactive email. name is the subject agents see, and custom holds custom attributes.
Kustomer keeps a set of read-only fields up to date as the thread changes: channels (every channel used in it), messageCount, noteCount, outboundMessageCount, firstResponse, lastMessageIn, sla and satisfaction. To see what changed and when, read the conversation's events, which record each update with before and after values.
Tags
tags is a list of tag IDs. Sending tags in an update replaces the whole list. The tag endpoints instead add or remove specific tags, up to 20 per request, and accept tag names or IDs; a name that doesn't exist yet is created as a new tag. Adding a tag the conversation already has is a no-op.
Which endpoint to use
| To | Call |
|---|---|
| Start a conversation for a customer | POST /v1/customers/{id}/conversations, or POST /v1/conversations with customer in the body |
| Read, update or delete a conversation | GET, PUT, PATCH or DELETE /v1/conversations/{id} |
| Find the conversation for one of your threads | GET /v1/conversations/externalId={externalId} |
| List a customer's conversations | GET /v1/customers/{id}/conversations |
| Page through all conversations | GET /v1/conversations |
| Add or remove tags | POST or DELETE /v1/conversations/{id}/tags |
| See every file shared in the thread | GET /v1/conversations/{id}/attachments |
| Read the change history | GET /v1/conversations/{id}/events |
| Import, update or delete up to 100 conversations per request | POST, PUT or DELETE /v1/conversations/bulk |
Creating a conversation doesn't send anything to the customer; add messages to it, or send a reply with a draft. Set externalId to your own thread ID so later messages land in the same conversation. A client can create 120 conversations per customer per minute, unless the records carry importedAt, and one conversation can be updated 100 times in 10 minutes (see Rate limits). PUT merges your changes unless you add replace=true. PATCH with Content-Type: application/json-patch+json takes JSON Patch operations, and rev makes the write depend on the revision you last read. For filtered queries, such as open conversations in a queue, use search.
Path parameters
Customer ID.
"5f8efdd5d3de932f344ca367"Responses
OK