Update note by ID

put/v1/notes/{id}
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 note based on the unique note ID.

Note

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

Authorization

The org.admin role is required for setting createdAt, createdBy, modifiedAt, and modifiedBy. Otherwise, these attributes are automatically set by the token.

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

Path parameters

idstringrequired

Unique note ID.

Example "57cf1d65079e780006e34f79"

Query parameters

replaceboolean

Set to true to replace the full resource instead of applying patch semantics.

Example true

Request body

application/jsonrequired
conversationstringrequired
externalIdstringnullable
max length 256
bodystringrequired
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

Responses

OK

objectrequired