Update conversation attributes

patch/v1/conversations/{id}
Requires any one of these rolesAbout roles
org.permission.conversation.update
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.

Updates the data attributes of a conversation based the unique conversation ID.

Note

This endpoint is subject to Object Rate Limiting, which limits how many updates a single user can make to a single company attribute. To learn more, see Rate limiting.

Custom Attributes

Custom attributes are optional and allow you to specify custom key-value pairs.

Kustomer uses a naming convention for custom attributes to specify the field data type with a name suffix:

Naming Suffix

  • Num number or null
  • At date-time or null
  • Str string or null, length: [ 0 .. 1024 ] characters
  • Txt string or null, length: [ 0 .. 1024 ] characters
  • Bool boolean or null
  • Url string or null, format: uri
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

Path parameters

idstringrequired

Conversation ID.

Example "5faaf4a6ea0cb48cd0801bbf"

Query parameters

revinteger

Expected resource revision for optimistic concurrency checks.

Example 1

Request body

application/json-patch+jsonrequired
One of
externalIdstringnullable
max length 256
namestringnullable
max length 256
directionstring
One of"in""out"
priorityinteger
≥ 1 · ≤ 5
satisfactionnumbernullable
≥ -1 · ≤ 1
objectconversation_satisfaction
array<object>
statusstring
One of"open""snoozed""done"
replyChannelstringnullable
max length 256
subStatusstring<object-id>
object
tagsarray<tag_name>
max items 20 · unique items
array<object>
max items 20 · unique items
objectsentiment
assignedUsersarray<string<object-id>>
max items 10 · unique items
assignedTeamsarray<string<object-id>>
max items 10 · unique items
customobjectcustom_attrs
deletedbooleannullable
endedboolean
endedAtstring<date-time>
endedReasonstring
max length 128
endedBystring<object-id>
endedByTypestring
One of"user""customer"
lockedboolean
revnumber
defaultLangstringlangnullable
max length 100
oneOf

Responses

Success

objectrequired