dialogbrain-com Voice API

openapi: 3.2.0
info:
  title: DialogBrain v2 API Gateway Voice API
  description: Clean refactored API gateway with minimal vertical slice
  version: 0.1.0
tags:
- name: Voice
paths:
  /api/voice/session:
    post:
      tags:
      - Voice
      summary: Start Voice Session
      description: Mint a LiveKit room + JWT for an in-app voice call.
      operationId: start_voice_session_api_voice_session_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartSessionRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartSessionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/voice/user-call:
    post:
      tags:
      - Voice
      summary: Start User Call
      description: 'Mint a LiveKit room and dispatch the channel leg for a user-initiated

        1:1 call. Browser publishes mic into the room; the channel bridge

        (pytgcalls for Telegram, SIP participant for Twilio) joins as the other

        publisher. Worker runs STT-only and persists transcript turns to the

        per-call thread.'
      operationId: start_user_call_api_voice_user_call_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartUserCallRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartUserCallResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/voice/quality-stats:
    get:
      tags:
      - Voice
      summary: Get Voice Quality Stats
      description: 'Aggregate voice-call quality for one agent over a window.


        Sources: voice_sessions rows (all calls) + metadata.analysis written by

        the post-call analyzer (voice_call_analysis agents). Score/success

        aggregates cover only analyzed calls; the counts expose how much of the

        traffic that actually is, so a 9.5 average over 2 analyzed calls can''t

        masquerade as a fleet-wide grade.'
      operationId: get_voice_quality_stats_api_voice_quality_stats_get
      parameters:
      - name: agent_id
        in: query
        required: true
        schema:
          type: integer
          title: Agent Id
      - name: days
        in: query
        required: false
        schema:
          type: integer
          default: 30
          title: Days
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/voice/call/{call_id}:
    get:
      tags:
      - Voice
      summary: Get Call Detail
      description: 'Everything the call-detail dialog needs in one request: session

        facts, chronological transcript, post-call analysis (when the agent

        has voice_call_analysis on), and a presigned recording URL (when the

        agent has voice_record_calls on and the upload landed).'
      operationId: get_call_detail_api_voice_call__call_id__get
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/voice/recording/{call_id}:
    get:
      tags:
      - Voice
      summary: Get Call Recording
      description: 'Presigned playback URL for a recorded call (voice_record_calls).


        404 when the call doesn''t belong to the workspace or has no stored

        recording — the UI treats both the same (no player shown).'
      operationId: get_call_recording_api_voice_recording__call_id__get
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/voice/tts/providers:
    get:
      tags:
      - Voice
      summary: Tts Provider Availability
      description: 'Which TTS providers the pickers must not offer on this deployment.


        Every vendor provider is always offered (a missing key is the picker''s own

        business). A self-hosted one is listed here while its server does not

        answer from this deployment.'
      operationId: tts_provider_availability_api_voice_tts_providers_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Tts Provider Availability Api Voice Tts Providers Get
  /api/voice/tts/preview:
    post:
      tags:
      - Voice
      summary: Tts Preview
      description: 'Synthesize a short voice sample for the agent-settings voice picker.


        Resolution order for the sample text:

        1. Explicit `text` field (if provided — for ad-hoc previews)

        2. `agent.execution_config.voice_greeting` when `agent_id` is set

        3. Fallback phrase looked up by voice → language map'
      operationId: tts_preview_api_voice_tts_preview_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TTSPreviewRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    TTSPreviewRequest:
      properties:
        provider:
          type: string
          title: Provider
        voice:
          type: string
          maxLength: 128
          minLength: 1
          title: Voice
        speed:
          type: number
          maximum: 4.0
          minimum: 0.25
          title: Speed
          default: 1.0
        agent_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Agent Id
        language:
          anyOf:
          - type: string
            maxLength: 16
          - type: 'null'
          title: Language
        text:
          anyOf:
          - type: string
            maxLength: 280
          - type: 'null'
          title: Text
      type: object
      required:
      - provider
      - voice
      title: TTSPreviewRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    StartSessionRequest:
      properties:
        agent_id:
          type: integer
          title: Agent Id
      type: object
      required:
      - agent_id
      title: StartSessionRequest
    StartSessionResponse:
      properties:
        url:
          type: string
          title: Url
        token:
          type: string
          title: Token
        room:
          type: string
          title: Room
        call_id:
          type: string
          title: Call Id
      type: object
      required:
      - url
      - token
      - room
      - call_id
      title: StartSessionResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    StartUserCallRequest:
      properties:
        channel:
          type: string
          enum:
          - telegram
          - twilio
          - whatsapp
          - telnyx
          - viber
          - whatsapp_business
          title: Channel
        channel_account_id:
          type: integer
          title: Channel Account Id
        target:
          type: string
          title: Target
        contact_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Contact Id
        tab_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Tab Id
        permission_request_text:
          anyOf:
          - type: string
            maxLength: 1024
          - type: 'null'
          title: Permission Request Text
      type: object
      required:
      - channel
      - channel_account_id
      - target
      title: StartUserCallRequest
    StartUserCallResponse:
      properties:
        url:
          type: string
          title: Url
        token:
          type: string
          title: Token
        room:
          type: string
          title: Room
        call_id:
          type: string
          title: Call Id
      type: object
      required:
      - url
      - token
      - room
      - call_id
      title: StartUserCallResponse