POST
Create Conversation Item

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

The agent fields make that agent answer this person; omit them to continue whatever runs.

to
PostTarget · object
required

The conversation, or your number and theirs to reach a person with no conversation yet.

type
enum<string>
required

template and agent_text are delivered; note is never delivered; instruct has the agent write and send a message.

Available options:
template,
agent_text,
note,
instruct
agent
AgentConfig · object | null

A complete agent definition, run for this call and stored nowhere. Mutually exclusive with agent_id.

agent_id
string<uuid> | null

An agent in this workspace. Mutually exclusive with agent.

agent_override
AgentOverride · object | null

Changes layered on top of whichever base was named. Absent keys keep the base value, an explicit null clears the field, objects deep-merge and lists replace.

agent_team
AgentTeam · object | null

Run several agents on this call, defined here. Mutually exclusive with agent_id / agent / agent_version / agent_override.

agent_version

Which version of agent_id to run. Omit for the published one. "draft" runs the unpublished working copy — validated and tool-pinned at request time, and refused with the publish errors if it does not hold together.

author
ItemAuthor · object | null

Who at your business posted this; shown in transcripts, never sent to the person or shown to the agent.

idempotency_key
string | null
Required string length: 1 - 255
on_window_closed
default:fail

fail refuses free text outside WhatsApp's 24h window; an opener sends that template and holds the message until they reply.

Allowed value: "fail"
secrets
Secrets · object | null

Secrets for this session only, read by tools as {{secrets.NAME}}; a name here overrides the workspace secret. Never shown to the model or returned.

template
TemplateSend · object | null

For template only.

text
string | null

For the other three types.

Required string length: 1 - 4096
userdata
Userdata · object | null

Merged into the person's userdata and given to the agent that answers their reply.

vars
Vars · object | null

Values for the variables the agents on this session declare, read as {{vars.name}} in a prompt, a greeting and a tool. They override each agent's declared default and reach every agent the session runs, including a handoff target. Unlike userdata, which describes the PERSON and is kept on their contact record, these describe THIS session and are gone with it. Strings only; an empty string is a deliberate blank, not a request for the default. The model can see them, so credentials go in secrets (this session's own, where the request takes them) or a workspace secret, read as {{secrets.NAME}} by a tool.

Response

Idempotent replay.

agent_id
string<uuid> | null
required
agent_version
required
attachments
(ConversationImage · object | ConversationDocument · object | ConversationAudio · object | ConversationContact · object | ConversationFile · object)[]
required

A photo the person sent, with a short-lived link to it.

attachments_not_kept
AttachmentNotKept · object[]
required

Files the person sent that could not be stored.

author
ItemAuthor · object | null
required

Who at your business posted this.

channel
enum<string> | null
required

How this item reached us or the person; null for notes and instructions.

Available options:
phone_call,
whatsapp_call,
whatsapp_message,
web_call,
chat,
telegram,
stream,
copilot
client_message_id
string | null
required
content
InboundContent · object | null
required

What the person sent besides text; null for plain text.

conversation_id
string<uuid>
required
created_at
string<date-time>
required
delivery_error
DeliveryError · object | null
required

Outbound delivery failure detail (provider HTTP / shadow-mode skips).

Writers always store {"message": ...}, plus the provider's code when it gave one (see services.messaging.delivery).

delivery_status
enum<string>
required
Available options:
not_applicable,
pending,
held,
sending,
queued,
sent,
delivered,
read,
undelivered,
failed,
skipped,
expired
direction
enum<string>
required
Available options:
inbound,
outbound,
internal
elapsed
string | null
required
id
string<uuid>
required
idempotency_key
string | null
required
latency
ReplyLatency · object | null
required

How long the caller waited for this reply, in the order it was spent.

metadata
Metadata · object
required
metrics
TurnMetrics · object | null
required

LiveKit MetricsReport samples for one transcript row, in seconds.

Every field is optional and unknown keys are kept: LiveKit owns this bag, so a version of it that reports something new must not fail a transcript write. What is named here is what the platform reads — the rest rides along verbatim.

Which fields are present depends on the row: transcription_delay and end_of_turn_delay are measured on the caller's message, the rest on the reply that closed the turn.

origin
enum<string> | null
required
Available options:
speech,
typed,
keypad
post_type
enum<string> | null
required

What was posted through the API; null for everything else.

Available options:
template,
agent_text,
note,
instruction
provider_message_id
string | null
required
raw_payload
Raw Payload · object | null
required
role
enum<string> | null
required
Available options:
developer,
system,
user,
assistant,
tool
scope
enum<string>
required
Available options:
conversation,
turn
session_id
string<uuid> | null
required
text
string | null
required
trigger_item_id
string<uuid> | null
required
turn_error
string | null
required
turn_status
enum<string> | null
required
Available options:
running,
done,
error,
canceled
type
enum<string>
required
Available options:
message,
function_call,
function_call_output,
agent_handoff,
agent_config_update
updated_at
string<date-time>
required
visibility
enum<string>
required
Available options:
customer_visible,
internal