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

# Send Message

> Sends an inbound customer message into the chat engine and returns the agent's reply synchronously.

`session_id` is optional. If omitted, the engine resolves the customer's active session for this agent (creating or resuming as needed), so a typical integration only needs `agent_uuid`, `customer_id`, and `content`.



## OpenAPI

````yaml POST /v1/chat/inbound
openapi: 3.1.0
info:
  title: OSVI AI API
  description: REST API for the OSVI AI voice and chat platform
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.osvi.ai
security:
  - ApiToken: []
paths:
  /v1/chat/inbound:
    post:
      summary: Send a chat message
      description: >-
        Sends an inbound customer message into the chat engine and returns the
        agent's reply synchronously.


        `session_id` is optional. If omitted, the engine resolves the customer's
        active session for this agent (creating or resuming as needed), so a
        typical integration only needs `agent_uuid`, `customer_id`, and
        `content`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - agent_uuid
                - customer_id
                - content
              properties:
                agent_uuid:
                  type: string
                  description: Unique identifier of the agent handling the conversation.
                  example: agent_IsZ3Q6Sf_60Eh26XQMGbz-R_og
                customer_id:
                  type: string
                  description: >-
                    Your identifier for the customer sending the message. Used
                    to resolve the active session when `session_id` is omitted.
                  example: '+15551112222'
                content:
                  type: string
                  description: The customer's message text.
                  example: Hi, I need help.
                session_id:
                  type: string
                  description: >-
                    Optional session UUID to route the message to. If omitted,
                    the engine resolves the active/new session for the customer
                    + agent.
                  example: 4718a326-417b-4dda-90d0-21fd65a11cb8
      responses:
        '200':
          description: Message processed and agent reply returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      session_id:
                        type: string
                        description: UUID of the session the message was routed to.
                        example: 4718a326-417b-4dda-90d0-21fd65a11cb8
                      reply:
                        type: string
                        nullable: true
                        description: >-
                          The agent's reply. `null` when the agent could not
                          produce a response (e.g. while a human has taken over
                          the session).
                        example: Sure — I can help with that. What's your order number?
                      state:
                        type: string
                        description: >-
                          Current state name after this turn. For multi-prompt
                          agents this reflects the active state; single-prompt
                          agents report a default state.
                        example: default
                      mode:
                        type: string
                        enum:
                          - ai
                          - support
                        description: >-
                          `ai` while the agent is responding, `support` when a
                          human operator has taken over.
                        example: ai
                      help_requested:
                        type: boolean
                        description: >-
                          `true` if the agent has escalated the conversation and
                          is requesting a human operator.
                        example: false
        '400':
          description: >-
            A required parameter (`agent_uuid`, `customer_id`, or `content`) is
            missing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatV1Error'
        '401':
          description: Invalid or missing API token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatV1Error'
        '404':
          description: >-
            The agent does not exist or is not associated with the authenticated
            account (`agent_not_found`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatV1Error'
        '422':
          description: >-
            The agent is archived (`agent_archived`) or not active
            (`agent_inactive`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatV1Error'
        '502':
          description: The chat engine could not be reached or returned an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatV1EngineError'
components:
  schemas:
    ChatV1Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          description: Machine-readable error code or message.
          example: agent_not_found
    ChatV1EngineError:
      type: object
      description: >-
        Returned when the upstream chat engine rejects or fails a proxied
        request.
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Python engine returned 422 for POST /v1/chat/session/{id}/support
        upstream_body:
          type: object
          nullable: true
          description: Parsed error body returned by the chat engine, when available.
          example:
            state: rejected
            reason: tell_not_allowed_during_takeover
  securitySchemes:
    ApiToken:
      type: apiKey
      in: header
      name: API-Token
      description: >-
        16-character API token associated with your OSVI account. Find it in
        your dashboard under Settings → API.

````