> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyreach.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.



## OpenAPI

````yaml /openapi.json post /core/conversations
openapi: 3.0.3
info:
  title: AnyReach API
  version: 1.0.0
  description: REST API for the AnyReach platform.
servers:
  - url: https://api.anyreach.ai
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Conversations
    description: >-
      Create, list, retrieve, and message conversations between your users and
      AnyReach agents.
paths:
  /core/conversations:
    post:
      tags:
        - Conversations
      summary: Create a conversation
      description: >-
        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.
      operationId: createConversation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationCreateRequest'
            examples:
              text:
                summary: Text conversation
                value:
                  channel: text
                  user_id: user_42
                  agent_id: agent_abc
                  initial_context: Customer is a returning VIP.
              telephone:
                summary: Outbound call
                value:
                  channel: telephone
                  user_id: '+14155551234'
                  agent_number: '+18885550000'
              webrtc:
                summary: WebRTC session
                value:
                  channel: webrtc
                  user_id: user_42
                  agent_id: agent_abc
              email:
                summary: Outbound email
                value:
                  channel: email
                  user_id: user_42
                  to_address: customer@example.com
                  agent_id: agent_abc
      responses:
        '200':
          description: >-
            Conversation created (text, email, or webrtc). The body shape
            depends on the channel.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/TextEmailCreateResponse'
                  - $ref: '#/components/schemas/WebRtcCreateResponse'
        '202':
          description: Outbound call queued (telephone). The call is placed asynchronously.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelephoneCreateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    ConversationCreateRequest:
      type: object
      required:
        - channel
        - user_id
      properties:
        channel:
          $ref: '#/components/schemas/Channel'
        user_id:
          type: string
          description: >-
            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:
          type: string
          description: >-
            The agent to use. Its latest published version is selected unless
            version is given.
        agent_version_id:
          type: string
          description: A specific published agent version to use.
        agent_config:
          type: object
          additionalProperties: true
          description: >-
            An inline agent configuration, instead of referencing a stored
            agent.
        version:
          oneOf:
            - type: integer
            - type: string
          description: >-
            Used together with agent_id: a version number, or "latest" (the
            default). The version must be published.
        agent_number:
          type: string
          description: The agent's phone number, for telephone conversations.
        to_address:
          type: string
          description: Recipient email address. Required for email.
        from_address:
          type: string
          description: Sender email address, for email conversations.
        subject:
          type: string
          description: >-
            Subject line for an outbound-initiated email. If omitted, the
            agent's configured email default_subject is used.
        initial_context:
          type: string
          default: ''
          description: >-
            Text injected into the agent's prompt at the start of the
            conversation.
        custom_metadata:
          type: object
          additionalProperties: true
          description: >-
            Arbitrary JSON attached to the conversation; returned later and
            usable as a list filter.
        id:
          type: string
          format: uuid
          description: >-
            Optional client-supplied UUID for idempotent creation. If a
            conversation with this ID already exists, it is returned unchanged.
    TextEmailCreateResponse:
      type: object
      description: Returned for text and email conversations.
      properties:
        conversation:
          $ref: '#/components/schemas/Conversation'
        starting_message:
          type: string
          nullable: true
          description: >-
            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).
    WebRtcCreateResponse:
      type: object
      description: Returned for webrtc conversations.
      properties:
        conversation:
          $ref: '#/components/schemas/Conversation'
        connection_details:
          type: object
          description: The join token for your client.
          properties:
            url:
              type: string
              description: WebSocket URL to connect to.
            token:
              type: string
              description: Access token for the session.
        capabilities:
          type: object
          description: What the session supports.
          properties:
            supportsVideoInput:
              type: boolean
            supportsScreenShare:
              type: boolean
    TelephoneCreateResponse:
      type: object
      description: Returned for telephone conversations (HTTP 202).
      properties:
        contact_id:
          type: string
          description: Identifier for the queued outbound call.
    Channel:
      type: string
      enum:
        - telephone
        - webrtc
        - email
        - text
      description: The conversation channel.
    Conversation:
      type: object
      description: >-
        Fields marked sensitive are only returned to tokens whose role grants
        access to them.
      properties:
        id:
          type: string
          description: Unique conversation ID.
        organization_id:
          type: string
          description: Your organization ID.
        direction:
          $ref: '#/components/schemas/Direction'
        channel:
          $ref: '#/components/schemas/Channel'
        status:
          $ref: '#/components/schemas/Status'
        user_id:
          type: string
          description: The end user's identifier (a phone number for telephony).
        agent_id:
          type: string
          description: The agent handling the conversation.
        agent_version_id:
          type: string
          description: The specific agent version in use.
        agent_number:
          type: string
          description: The agent's phone number (telephony).
        web_widget_id:
          type: string
          nullable: true
          description: The web widget that originated the conversation, if any.
        duration:
          type: integer
          nullable: true
          description: Conversation length in seconds.
        user_turn_count:
          type: integer
          nullable: true
          description: Number of user turns.
        created_at:
          type: string
          format: date-time
          description: Creation timestamp.
        updated_at:
          type: string
          format: date-time
          description: Last-update timestamp.
        agent:
          type: object
          description: Sensitive. The handling agent.
          properties:
            id:
              type: string
            name:
              type: string
        summary:
          type: string
          description: Sensitive. Generated conversation summary.
        initial_context:
          type: string
          description: >-
            Sensitive. Context injected into the agent at the start of the
            conversation.
        custom_metadata:
          type: object
          additionalProperties: true
          nullable: true
          description: Sensitive. Metadata you attached when creating the conversation.
        conversation:
          type: object
          additionalProperties: true
          nullable: true
          description: Sensitive. The transcript.
        recording_details:
          type: object
          additionalProperties: true
          nullable: true
          description: >-
            Sensitive. Recording information, including a time-limited
            recording_url.
    Error:
      type: object
      properties:
        detail:
          type: string
          description: A human-readable description of the error.
          example: Conversation not found
    Direction:
      type: string
      enum:
        - inbound
        - outbound
      description: Who initiated the conversation.
    Status:
      type: string
      enum:
        - token_created
        - triggered
        - ringing
        - in_progress
        - completed
        - failed
        - cancelled
        - transferred
        - unanswered
      description: Current state of the conversation.
  responses:
    BadRequest:
      description: >-
        The request was understood but could not be fulfilled (e.g. a referenced
        agent version is not published, or a usage limit was reached).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The token's role doesn't grant access to this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: The request body or parameters failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Personal access token. See Authentication.

````