Skip to main content
POST
Create a conversation message

Authorizations

x-api-key
string
header
required

Workspace API key. Current accepted keys use the ando_sk_ prefix.

Headers

Idempotency-Key
string
required

Required idempotency key for safely retrying this write. Idempotency key.

Maximum string length: 255

Path Parameters

conversationId
string
required

Conversation identifier.

Body

application/json

Create a conversation message. The authenticated API-key workspace member is the author; author_id is accepted only for legacy body compatibility and is ignored.

markdown_content
string | null
required

Message markdown content.

app_card
object

A deployment attempt reported by the authenticated publisher. Markdown remains the fallback for clients without native cards.

explicit_context_message_ids
string[]

Message identifiers to include as explicit context.

Message identifier.

image_urls
string<uri>[]

Image URLs to attach to the message.

Image URL.

file_ids
string[]

Ready file identifiers from the Files routes to attach to the message.

File identifier.

URLs to send as plain links: no link preview and no app card.

URL.

initiator_id
string | null

Initiating workspace member identifier.

thread_root_id
string | null

Thread root message identifier.

replied_to_message_id
string | null

Immediate parent message identifier inside an existing thread. For the first reply to a root message, send thread_root_id only; if replied_to_message_id equals thread_root_id, the server normalizes it as the first reply.

call_root_id
string | null

Call root identifier.

optimistic_id
string

Client optimistic identifier.

client_request_id
string | null

Legacy body idempotency value. Public v1 clients should use the Idempotency-Key header.

author_id
string
deprecated

Ignored legacy body author workspace member identifier. Deprecated: the authenticated API-key workspace member is always the author.

send_at
string<date-time>

Send the message later instead of now. An ISO 8601 timestamp with a UTC offset, at least 5 minutes and at most 30 days ahead. The response is then 202 with a scheduled message. Cannot be combined with app_card or initiator_id.

Example:

"2026-10-12T09:00:00Z"

persona
object

A name and avatar to show on this message instead of the API key's member, like a Discord webhook's username and avatar_url. Use it to relay messages from another chat tool under their original authors. The key's member stays the author: Ando tags the message with an App badge and names that member. Cannot be combined with send_at.

Response

Created message.

Create-message response with the standard public data envelope plus legacy compatibility aliases.

data
object
required

Public message result. thread_root_id identifies the thread a reply belongs to; replied_to_message_id is not exposed.

success
boolean
required

Compatibility command flag.

legacy_data
object | null

Legacy extended conversation message. New clients should read the standard data message result.