Conversations

Create a conversation

Creates a conversation. What happens — and what comes back — depends on the channel:

Channel	Behavior	Success status
`telephone`	Queues an outbound call; the dialer places it shortly after.	`202`
`text`	Creates the session and returns the agent’s greeting immediately.	`200`
`email`	Creates the session; the greeting is sent asynchronously.	`200`
`webrtc`	Creates the session and returns a join token for the browser/SDK.	`200`

Choosing the agent. Identify the agent in exactly one way: agent_id, agent_version_id, or agent_config. Providing more than one returns 422. The referenced version must be published.

Per-channel requirements:

telephone — user_id must be a valid +E.164 number; provide agent_number, agent_id, or agent_version_id.
text / webrtc — provide agent_id, agent_version_id, or agent_config.
email — to_address is required, plus one agent reference.

Requires a token with write access.

POST

core

conversations

curl --request POST \
  --url https://api.anyreach.ai/core/conversations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "channel": "text",
  "user_id": "user_42",
  "agent_id": "agent_abc",
  "initial_context": "Customer is a returning VIP."
}
'

{
  "conversation": {
    "id": "<string>",
    "organization_id": "<string>",
    "user_id": "<string>",
    "agent_id": "<string>",
    "agent_version_id": "<string>",
    "agent_number": "<string>",
    "web_widget_id": "<string>",
    "duration": 123,
    "user_turn_count": 123,
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "agent": {
      "id": "<string>",
      "name": "<string>"
    },
    "summary": "<string>",
    "initial_context": "<string>",
    "custom_metadata": {},
    "conversation": {},
    "recording_details": {}
  },
  "starting_message": "<string>"
}

Authorizations

Authorization

string

header

required

Personal access token. See Authentication.

Body

application/json

channel

enum<string>

required

The conversation channel.

Available options:

telephone,

webrtc,

email,

text

user_id

string

required

Your identifier for the end user. For telephone, must be a +E.164 phone number (e.g. +14155551234). For email, the recipient is set via to_address.

agent_id

string

The agent to use. Its latest published version is selected unless version is given.

agent_version_id

string

A specific published agent version to use.

agent_config

object

An inline agent configuration, instead of referencing a stored agent.

version

Used together with agent_id: a version number, or "latest" (the default). The version must be published.

agent_number

string

The agent's phone number, for telephone conversations.

to_address

string

Recipient email address. Required for email.

from_address

string

Sender email address, for email conversations.

subject

string

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

initial_context

string

default:""

Text injected into the agent's prompt at the start of the conversation.

custom_metadata

object

Arbitrary JSON attached to the conversation; returned later and usable as a list filter.

string<uuid>

Optional client-supplied UUID for idempotent creation. If a conversation with this ID already exists, it is returned unchanged.

Response

Conversation created (text, email, or webrtc). The body shape depends on the channel.

Option 1
Option 2

Returned for text and email conversations.

conversation

object

Fields marked sensitive are only returned to tokens whose role grants access to them.

Show child attributes

starting_message

string | null

The agent's opening message. null if the agent waits for the user to speak first, and always null for email (the greeting is sent asynchronously).

Get a conversationRetrieves a single conversation, including its transcript and recording when your token's role allows. Read-only tokens receive a reduced set of fields. Requires a token with read access.

curl --request POST \
  --url https://api.anyreach.ai/core/conversations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "channel": "text",
  "user_id": "user_42",
  "agent_id": "agent_abc",
  "initial_context": "Customer is a returning VIP."
}
'

{
  "conversation": {
    "id": "<string>",
    "organization_id": "<string>",
    "user_id": "<string>",
    "agent_id": "<string>",
    "agent_version_id": "<string>",
    "agent_number": "<string>",
    "web_widget_id": "<string>",
    "duration": 123,
    "user_turn_count": 123,
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "agent": {
      "id": "<string>",
      "name": "<string>"
    },
    "summary": "<string>",
    "initial_context": "<string>",
    "custom_metadata": {},
    "conversation": {},
    "recording_details": {}
  },
  "starting_message": "<string>"
}