Skip to content

Send a message or create an internal note

POST
/conversations/{conversationId}/messages
curl --request POST \
--url https://optlo.com/api/v1/conversations/example/messages \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'idempotency-key: example' \
--data '{ "kind": "message", "content": "Hi Sam, your workspace is ready. Can I help you get started?", "sender": { "id": "acc_tQ8nL4zR6mB2xP7k", "role": "operator" } }'

Requires messages:write for operator messages, assistants:write for caller-authored assistant messages, or notes:write for internal notes. Operators must be active workspace members; assistants must belong to the workspace. Notes require an operator sender. Accepts messages on open or closed conversations and preserves closed state; greeting-only conversations are unavailable. Customer-visible messages schedule customer notifications without triggering assistant generation. Operator messages activate the operator; assistant messages do not assign an operator. Caller-authored messages are accepted independently of any assistant reply already generating and do not cancel it. Notes remain internal and do not activate operators or create billable activity. Customer-visible message requests, including idempotent retries, return 402 while the workspace is paused; notes remain available. Conversation usage is counted asynchronously. Each new API message or note consumes one daily message allowance at admission; a later failure retains that admission. Exhaustion returns 429 daily_limit_exceeded; retained retries consume no additional capacity. Each user accepts at most 30 messages and notes per minute across their conversations and 10 per minute from one sender; beyond that the request returns 429 rate_limited after admission, so retry with the same Idempotency-Key. Idempotency-Key is required and retained for 24 hours; conflicting reuse returns 409. The created message is returned without requiring read scopes. API attribution is server-owned.

conversationId
required
string

Unique identifier for the conversation.

Media typeapplication/json
dictionary

One of:

message
Show child attributesHide child attributes
kind
required

Send a customer-visible message.

Allowed value: message
content
required

Markdown text of the message or internal note.

string
sender
required

Operator or assistant whose name appears on the message.

dictionary
Show child attributesHide child attributes
role
required

Send as an operator or an assistant.

string
Allowed values: operator assistant
id
required

ID of an active workspace operator or a workspace assistant, matching role.

string
>= 1 characters
note
Show child attributesHide child attributes
kind
required

Create an internal note, visible only to your team.

Allowed value: note
content
required

Markdown text of the message or internal note.

string
sender
required

Active workspace operator whose name appears on the note.

dictionary
Show child attributesHide child attributes
role
required

Internal notes must be attributed to an operator.

Allowed value: operator
id
required

ID of an active workspace operator or a workspace assistant, matching role.

string
>= 1 characters

Created

Media typeapplication/json

A customer-visible message or internal note.

Show child attributesHide child attributes
id
required

Unique identifier for the message or note.

string
conversationId
required

ID of the conversation containing this message.

string
kind
required

Whether this is a customer-visible message or an internal note.

string
Allowed values: message note
content
required

Markdown text of the message or note. Literal characters typed by users are backslash-escaped.

string
sender
required

Participant who sent the message.

dictionary
Show child attributesHide child attributes
id
required

Unique identifier for the sender.

string
role
required

Type of participant who sent the message.

string
Allowed values: user operator assistant
createdAt
required

Time the message was created.

string format: date-time

Example

{
"id": "msg_h7m4k2r9p6x8n3q5v1z0bcdf",
"conversationId": "conv_B8kN4pR6xZ2_kR7mP3xB9nQ2vL5z",
"kind": "message",
"content": "Hi Sam, your workspace is ready. Can I help you get started?",
"sender": {
"id": "acc_tQ8nL4zR6mB2xP7k",
"role": "operator"
},
"createdAt": "2026-10-13T09:10:00.000Z"
}