Create a conversation for an existing user
const url = 'https://optlo.com/api/v1/conversations';const options = { method: 'POST', headers: { 'idempotency-key': 'example', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"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"}}}'};
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 \ --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.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”Show child attributes
Existing user to contact. Supply exactly one of id, email, or externalId. No match returns 404; an email matching multiple users returns 409.
Any of:
id
Show child attributes
ID of an existing user in this workspace.
Show child attributes
User’s email address. Matching is case-insensitive.
externalId
Show child attributes
User identifier in your system. String and numeric IDs are distinct.
Workflow to handle later customer replies. Defaults to the workspace’s default workflow.
First customer-visible message in the conversation. Internal notes cannot start a conversation.
Show child attributes
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.
Response
Section titled “Response”Created
Show child attributes
A conversation with a user.
Show child attributes
Unique identifier for the conversation.
Time the conversation was closed. Null while the conversation is open.
User the conversation belongs to.
Show child attributes
Unique identifier for the user.
Whether the conversation has been escalated to an operator.
Time the conversation was created.
Time the conversation was last updated.
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
{ "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" }}