Bulk batch update notes

put/v1/notes/bulk
Requires any one of these rolesAbout roles
org.permission.note.update
Legacyorg.user.note.write

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

Updates a bulk batch of notes.

Use the ids query param to update multiple notes in bulk with the same data.

Note: _clientRef is supported when submitting an array-shaped request body, but is not supported when using the ?ids= query param mode. See Bulk create customers for full _clientRef documentation.

About this resource

Notes

A note is an internal comment that your team leaves on a conversation. Customers never see notes; agents use them to hand off context, record what they checked, and @mention teammates.

In the agent desktop, notes appear in a conversation's thread next to its messages but are styled as internal and are never sent to the customer. Every note belongs to one conversation, and through it to that conversation's customer, so you can read notes per conversation or across everything you know about a customer. Agents write notes by hand; integrations and workflows use them to drop in context such as an order lookup result or a fraud check, without the customer seeing it.

Notes attach to conversations. Internal comments on custom objects, such as a task or an order, are a separate resource called comments.

Key fields

Field Meaning
body The note text, 1 to 10,240 characters. Required.
conversation The conversation the note belongs to. Required when you create a note with POST /v1/notes or in bulk; the customer comes from the conversation.
userMentions Up to 20 { user } or { team } entries. Mentioned users are notified, the same as an @mention typed in the agent desktop.
attachments Files uploaded beforehand with POST /v1/attachments, passed as { _id, name, contentType, contentLength }.
externalId Your own ID for the note, up to 256 characters.

The conversation's noteCount tracks how many notes it has. An unsent note is a different object: a draft with channel: "note", limited to one per conversation.

Which endpoint to use

To Call
Add a note to a conversation POST /v1/conversations/{id}/notes, or POST /v1/notes with conversation in the body
Read, edit or delete a note GET, PUT, PATCH or DELETE /v1/notes/{id}
List a conversation's notes GET /v1/conversations/{id}/notes
List every note about a customer GET /v1/customers/{id}/notes
Page through all notes GET /v1/notes
Import or update up to 100 notes per request POST or PUT /v1/notes/bulk

A client can create 120 notes per customer per minute. Only tokens with the org.admin role can set createdAt, createdBy, modifiedAt and modifiedBy, which you need when importing history so notes keep their original author and time. PUT merges your changes unless you add replace=true, in which case conversation and body are both required. Bulk jobs run asynchronously; see Bulk operations.

RelatedConversationsMessagesComments on custom objectsConversations and messages

Query parameters

idsstring

Comma-separated list of unique note IDs.

Example "id1,id2"

Request body

application/jsonrequired

array<object>

idstringrequired
conversationstring
externalIdstringnullable
max length 256
bodystring
min length 1 · max length 10240
array<object>
deletedbooleannullable
array<attachment>
unique items
createdAtstring<date-time>
modifiedAtstring<date-time>
updatedAtstring<date-time>
createdBystring<object-id>
modifiedBystring<object-id>nullable
langstringlangnullable
max length 100
_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