Skip to main content
POST
Add an internal note to a conversation

Authorizations

Authorization
string
header
required

The id_token from POST /auth/v1/signin, sent as Authorization: Bearer <id_token>. Not the access_token — that one does not carry the identity Cloud Chat authorizes on.

Headers

cloudchat-instance
integer
required

Your Cloud Chat instance ID — an integer, fixed for your company, told at onboarding. The API overview explains how instances work, how to find yours, and the errors a wrong or missing value produces.

Example:

1

Path Parameters

accountId
integer
required

Your Cloud Chat account. It has to be an account your token grants membership on, and it has to live on the instance in the cloudchat-instance header — the two travel together. Account numbers are only unique within an instance, so the same number is a different company on another instance. Usually a mismatched pair fails closed with a 401, because your user does not exist on the other instance — but if your identity happens to exist on both, the call succeeds against the other company's data, silently. Read it and you are looking at the wrong help center; write it and you have stored into the wrong account. Send the two values that were given to you together, and never try a number to see what answers.

Example:

1

conversationId
integer
required

The conversation's display_id — the number shown in the dashboard URL and delivered in webhooks. It is never the internal database id.

Example:

1042

Body

application/json

The internal note to add.

content
string
required

The note text, plain text. It is stored as a private note: the customer never sees it. Blank text is a 422.

Example:

"Customer asked to be called back after 3 pm."

Response

The note as stored.

A single message of a conversation. Attachments and content_attributes are not exposed in this version — only the fields listed below.

id
integer
required

Stable identifier, unique within the instance.

Example:

58211

uuid
string | null
required

The message's canonical id, globally unique. For ClaudIA's reply and for the customer message that started the turn, it is the messageId the ClaudIA API takes in Get a message trace, where the numeric id above does not resolve. null on older messages stored without one.

Example:

"8b0e5f3a-6c2d-4e71-9f4a-2d1c7b9e0a53"

content
string | null
required

The message text. null on some activity or attachment-only messages.

Example:

"Thanks, that solved it!"

message_type
enum<string>
required

Who originated it and how — incoming from the contact, outgoing from an agent or bot, activity a system event (status/assignment change), template an outbound message template (WhatsApp, etc).

Available options:
incoming,
outgoing,
activity,
template
Example:

"outgoing"

content_type
enum<string>
required

How the dashboard renders the message body. text covers the overwhelming majority of messages; the rest are the interactive/bot content types (input_select, cards, form, article, input_csat, and similar).

Available options:
text,
input_text,
input_textarea,
input_email,
input_select,
cards,
form,
article,
incoming_email,
input_csat,
integrations,
sticker,
follow_up,
closing_message
Example:

"text"

private
boolean
required

true for a private note — visible only to agents, never sent to the contact. This endpoint returns private notes like any other message; filter them out client-side if you don't want them.

Example:

false

status
enum<string> | null
required

Delivery status on the channel. null on message types that don't track delivery (e.g. activity).

Available options:
sent,
delivered,
read,
failed
Example:

"delivered"

sender
object | null
required

Who sent the message. null on an activity message (status changes, assignment changes, and the like), which has no author.

A hidden admin — the platform's own support user, occasionally the sender of a system message — reports type: "user" with id: null and a masked name, indistinguishable from any other masking. There is no way to resolve a hidden admin's real id through this API.

created_at
string<date-time>
required

When it was created. ISO 8601, always UTC, milliseconds included.

Example:

"2026-08-13T19:09:51.482Z"