Bulk create conversations

post/v1/conversations/bulk
Requires any one of these rolesAbout roles
org.permission.conversation.create
Legacyorg.user.conversation.write

The API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.

Create conversations in bulk.

_clientRef support: You can include an optional _clientRef string on each item for per-item result correlation. See Bulk create customers for full documentation of rules, the async poll flow, and the results[] response shape.

About this resource

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.

RelatedConversations and messagesMessagesNotesSnoozes

Request body

application/jsonrequired

array<object>

idstring<object-id>
customerstring<object-id>required
externalIdstring
max length 256
namestring
max length 256
statusstring
One of"open""done"
priorityinteger
≥ 1 · ≤ 5
createdAtstring<date-time>
importedAtstring<date-time>
directionstring
One of"in""out"
replyChannelstringnullable
max length 256
tagsarray<tag_name>
max items 20 · unique items
assignedUsersarray<string<object-id>>
max items 10 · unique items
assignedTeamsarray<string<object-id>>
max items 10 · unique items
customobjectcustom_attrs
defaultLangstringlangnullable
max length 100
object
_clientRefstringclient_ref

Optional client-supplied correlation token. Omit the field to rely on the existing objectIds and errors fields. When included, it must be present on every item in the request (all-or-nothing), and must be unique within the request array. See Bulk create customers for full documentation of rules, the async poll flow, and the results[] response shape.

min length 1 · max length 255

Responses

Created

objectrequired