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

For a customer answering an interactive message the agent sent, see [Interactive messages](/api-reference/endpoint/chat/interactive_messages). For fire-and-forget delivery instead of waiting on this response, use [Send Message (Async)](/api-reference/endpoint/chat/inbound_async).



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


        For a customer answering an interactive message the agent sent, see
        [Interactive
        messages](/api-reference/endpoint/chat/interactive_messages). For
        fire-and-forget delivery instead of waiting on this response, use [Send
        Message (Async)](/api-reference/endpoint/chat/inbound_async).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - agent_uuid
                - customer_id
              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. Required unless `type` is
                    `interaction_response`.
                  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
                idempotency_key:
                  type: string
                  description: >-
                    Your identifier for this exact turn. A retry with the same
                    key returns the original result instead of running the turn
                    twice. Can also be sent as an `Idempotency-Key` header
                    instead of a body field.
                  example: wh-2f8a1c-attempt-1
                input_fields:
                  type: object
                  additionalProperties: true
                  description: >-
                    Arbitrary key-value object made available to the agent at
                    runtime (e.g. name, account tier). Only applied when this
                    request creates a new session.
                  example:
                    first_name: Alex
                state_fields:
                  type: object
                  additionalProperties: true
                  description: >-
                    Initial values for the agent's configured state fields —
                    structured values the agent's prompt and tools can read and
                    update as the conversation continues. Only applied when this
                    request creates a new session.
                  example: {}
                context:
                  type: array
                  items:
                    type: string
                  description: >-
                    Free-text context entries for a newly created session. Only
                    the most recent 5 non-empty strings are retained. Only
                    applied when this request creates a new session — use
                    [Inject
                    Context](/api-reference/endpoint/chat/inject_context) to add
                    context to an existing one.
                  example:
                    - Customer called in about a refund yesterday.
                type:
                  type: string
                  enum:
                    - message
                    - interaction_response
                  default: message
                  description: >-
                    `message` for a normal text message (default).
                    `interaction_response` to answer an interactive message the
                    agent sent — see [Interactive
                    messages](/api-reference/endpoint/chat/interactive_messages).
                  example: message
                interaction_id:
                  type: string
                  format: uuid
                  description: >-
                    Required when `type` is `interaction_response`. The
                    `interaction_id` of the interactive message being answered.
                  example: b6a3e6c2-2d61-4a4b-9c9a-5a2d9f6a2b10
                option_id:
                  type: string
                  description: >-
                    Shorthand answer for a simple option tap — the `id` of the
                    selected option. Send this or `response`, not both. See
                    [Interactive
                    messages](/api-reference/endpoint/chat/interactive_messages).
                  example: opt_confirm
                response:
                  type: object
                  description: >-
                    Structured answer to a pending interactive message. Send
                    this or `option_id`, never both. See [Interactive
                    messages](/api-reference/endpoint/chat/interactive_messages).
                  properties:
                    kind:
                      type: string
                      enum:
                        - selection
                        - text
                        - date
                        - date_range
                      example: selection
                    value:
                      description: >-
                        A string for `selection`/`text`/`date`. An object
                        `{start_date, end_date}` for `date_range`.
                      example: opt_confirm
                supported_interactions:
                  type: array
                  description: >-
                    Declares which interactive message types your client can
                    render, so the agent only offers ones you can display. See
                    [Interactive
                    messages](/api-reference/endpoint/chat/interactive_messages).
                  items:
                    type: object
                    properties:
                      tool_type:
                        type: string
                        enum:
                          - ui_buttons
                          - ui_carousel
                          - ui_date_picker
                        example: ui_buttons
                      schema_version:
                        type: integer
                        example: 2
                  example:
                    - tool_type: ui_buttons
                      schema_version: 2
      responses:
        '200':
          description: >-
            Message processed and agent reply returned. `data.state` can also be
            `merged` when your message was folded into another turn already in
            flight for the session — in that case `reply` is `null` and no
            separate reply is produced for this request.
          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
        '202':
          description: >-
            Only returned when this turn ran past its synchronous budget **and**
            the agent has a delivery URL configured: rather than time out, the
            turn is handed to the [chat delivery
            webhook](/api-reference/endpoint/chat/delivery_webhook), which
            delivers the reply once it's ready.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  accepted:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      state:
                        type: string
                        enum:
                          - accepted
                        example: accepted
                      turn_id:
                        type: string
                        example: turn_9f3d2a1b
                      session_id:
                        type: string
                        example: 4718a326-417b-4dda-90d0-21fd65a11cb8
                      idempotency_key:
                        type: string
                        nullable: true
                        example: wh-2f8a1c-attempt-1
        '400':
          description: >-
            A required parameter is missing — `agent_uuid`/`customer_id` always,
            `content` unless `type` is `interaction_response`, or
            `interaction_id`/(`option_id` or `response`) when it is.
          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'
        '409':
          description: >-
            An idempotency conflict: `idempotency_key_reused` (the same key was
            already used with different content) or
            `idempotency_key_mode_conflict` / `idempotency_key_rail_conflict`
            (the key was already accepted under a different delivery mode, e.g.
            previously sent to the async endpoint or over the WebSocket).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatV1TurnError'
        '422':
          description: >-
            The agent is archived (`agent_archived`) or not active
            (`agent_inactive`); or a `response` on an `interaction_response`
            failed validation — a `selection` not among the message's
            options/items, or a value outside what it allows (e.g. a date
            outside `min_date`/`max_date`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatV1TurnError'
        '502':
          description: >-
            The chat engine could not be reached, or returned an error other
            than the ones listed above — including an overloaded engine, which
            surfaces here rather than as a `503`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatV1EngineError'
        '504':
          description: >-
            The turn ran past its synchronous budget and the agent has **no**
            delivery URL configured, so there was nowhere to deliver a late
            reply (`sync_budget_exceeded`). The turn keeps running; retry with
            the same `idempotency_key` once it's done to get the stored reply.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatV1TurnError'
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
    ChatV1TurnError:
      type: object
      description: >-
        A turn-level conflict or refusal from the chat engine, passed through
        with the status code the engine gave it.
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          description: Machine-readable error code.
          example: idempotency_key_reused
        data:
          type: object
          nullable: true
          description: Extra context when available — typically `turn_id` and `session_id`.
          example:
            state: error
            turn_id: turn_9f3d2a1b
            session_id: 4718a326-417b-4dda-90d0-21fd65a11cb8
    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.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.