Send a message or create an internal note
const url = 'https://optlo.com/api/v1/conversations/example/messages';const options = { method: 'POST', headers: { 'idempotency-key': 'example', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"kind":"message","content":"Hi Sam, your workspace is ready. Can I help you get started?","sender":{"id":"acc_tQ8nL4zR6mB2xP7k","role":"operator"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Unique identifier for the conversation.
Request Bodyrequired
Section titled “Request Bodyrequired”One of:
message
Show child attributes
Send a customer-visible message.
Markdown text of the message or internal note.
Operator or assistant whose name appears on the message.
Show child attributes
Send as an operator or an assistant.
ID of an active workspace operator or a workspace assistant, matching role.
note
Show child attributes
Create an internal note, visible only to your team.
Markdown text of the message or internal note.
Active workspace operator whose name appears on the note.
Show child attributes
Internal notes must be attributed to an operator.
ID of an active workspace operator or a workspace assistant, matching role.
Response
Section titled “Response”Created
A customer-visible message or internal note.
Show child attributes
Unique identifier for the message or note.
ID of the conversation containing this message.
Whether this is a customer-visible message or an internal note.
Markdown text of the message or note. Literal characters typed by users are backslash-escaped.
Participant who sent the message.
Show child attributes
Unique identifier for the sender.
Type of participant who sent the message.
Time the message was created.
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"}