Skip to main content
POST
Create a conversation

Headers

x-anyreach-org
string | null

Organization ID for user PATs (pat_ prefix tokens)

Body

application/json

Schema for API requests to create a new conversation.

channel
enum<string>
required

Channel type: telephone, webrtc, or text

Available options:
telephone,
webrtc,
email,
text
user_id
string
required

User ID (must be +E.164 phone number for telephony)

id
string<uuid> | null

Optional conversation ID for idempotent creation. If provided and a conversation with this ID already exists, the existing conversation is returned.

custom_metadata
Custom Metadata · object | null

Optional custom metadata

agent_config
AgentConfig · object | null

Agent configuration (conditional)

agent_version_id
string | null

Agent version ID (for webrtc)

agent_id
string | null

Parent agent ID (resolves latest published version)

version

Agent version (used with agent_id): a version number, or the tag 'latest' for the highest published version (same as omitting it)

initial_context
string
default:""

Context to inject into the agent's system prompt at conversation start

agent_number
string | null

Agent number (required for telephony)

to_address
string | null

Recipient address (email outbound-initiated)

from_address
string | null

Sender address (email outbound-initiated)

subject
string | null

Subject line for an outbound-initiated email. If omitted, the agent's configured email default_subject is used.

Response

Successful Response

The response is of type Response Create Conversation Core Conversations Post · object.