Delete note by ID
/v1/notes/{id}org.permission.note.deleteorg.user.note.writeThe API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.
Deletes a note based on the unique note ID.
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.
Path parameters
Unique note ID.
"57cf1d65079e780006e34f79"Responses
No Content
No response body.