Skip to content

Create a conversation for an existing user

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

Requires conversations:write plus messages:write for an operator sender or assistants:write for an assistant sender. Supply exactly one user selector: id, email, or externalId. Resolves existing workspace users only; no match returns 404 and multiple email matches return 409. Email matching is case-insensitive; numeric and string external IDs are distinct. Identity resolution never creates or updates users. users:read and users:write are not required. Operators must be active workspace members and assistants must belong to the workspace. The initial message must be customer-visible; notes cannot start conversations. workflowId selects the workflow for later customer replies; omission uses the workspace default. Retries retain the resolved user and reserved workflow even if the selector or workspace default later resolves differently; deletion of the resolved user or workflow returns 404. Creation schedules customer notifications without generating an automatic reply. Admission consumes one daily conversation and one daily message allowance together; exhaustion returns 429 daily_limit_exceeded without consuming either. A later failure retains the admission, and retained retries consume no additional capacity. The initial message counts toward the user’s limit of 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. Returns 402 while the workspace is paused, including on retries. Idempotency-Key is required and retained for 24 hours; retries return the original conversation and message, while conflicting reuse, including a different user, returns 409. API attribution is server-owned.

Media typeapplication/json
Show child attributesHide child attributes
user
required

Existing user to contact. Supply exactly one of id, email, or externalId. No match returns 404; an email matching multiple users returns 409.

dictionary

Any of:

id
Show child attributesHide child attributes
id
required

ID of an existing user in this workspace.

string
>= 1 characters
email
Show child attributesHide child attributes
email
required

User’s email address. Matching is case-insensitive.

string format: email
<= 254 characters
externalId
Show child attributesHide child attributes
externalId
required

User identifier in your system. String and numeric IDs are distinct.

string
>= 1 characters <= 256 characters
or
number
workflowId

Workflow to handle later customer replies. Defaults to the workspace’s default workflow.

string
>= 1 characters
message
required

First customer-visible message in the conversation. Internal notes cannot start a conversation.

dictionary
Show child attributesHide child attributes
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

Created

Media typeapplication/json
Show child attributesHide child attributes
conversation
required

A conversation with a user.

dictionary
Show child attributesHide child attributes
id
required

Unique identifier for the conversation.

string
closedAt
required

Time the conversation was closed. Null while the conversation is open.

nullable string format: date-time
user
required

User the conversation belongs to.

dictionary
Show child attributesHide child attributes
id
required

Unique identifier for the user.

string
escalated
required

Whether the conversation has been escalated to an operator.

boolean
createdAt
required

Time the conversation was created.

string format: date-time
updatedAt
required

Time the conversation was last updated.

string format: date-time
message
required

A customer-visible message or internal note.

dictionary
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

{
"conversation": {
"id": "conv_B8kN4pR6xZ2_kR7mP3xB9nQ2vL5z",
"user": {
"id": "user_kR7mP3xB9nQ2vL5z"
},
"closedAt": null,
"escalated": false,
"createdAt": "2026-10-13T09:10:00.000Z",
"updatedAt": "2026-10-13T09:10:00.000Z"
},
"message": {
"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"
}
}