asyncapi: 3.0.0
info:
  title: SLNG Gateway API - Cognigy (WebSocket)
  version: 0.0.6
  description: SLNG Gateway API
  contact:
    name: SLNG Support
    url: https://slng.ai
    email: support@slng.ai
  license:
    name: Proprietary
  tags:
    - name: STT
      description: Speech-to-Text services
servers:
  production:
    host: api.slng.ai
    protocol: wss
    description: Production
  staging:
    host: stageapi.slng.ai
    protocol: wss
    description: Staging
channels:
  /v1/bridges/cognigy/stt/{model_variant}:
    address: /v1/bridges/cognigy/stt/{model_variant}
    title: Cognigy STT Bridge WebSocket
    summary: Cognigy STT Bridge - websocket
    description: |
      WebSocket protocol bridge for Cognigy Voice Gateway STT integration.
      Accepts Cognigy's native websocket messages (start, stop, binary audio)
      and translates them to SLNG's standard STT websocket protocol.
      The model_variant path parameter specifies the target STT model.
    tags:
      - name: Cognigy STT Bridge
    servers:
      - $ref: "#/servers/production"
      - $ref: "#/servers/staging"
    messages:
      request:
        $ref: "#/components/messages/CognigySTTWebsocketRequest"
      response:
        $ref: "#/components/messages/CognigySTTWebsocketResponse"
    bindings:
      ws:
        method: GET
        headers:
          $ref: "#/components/schemas/WebsocketHeaders"
  /v1/bridges/cognigy/tts/{model_variant}:
    address: /v1/bridges/cognigy/tts/{model_variant}
    title: Cognigy TTS Bridge WebSocket
    summary: Cognigy TTS Bridge - websocket
    description: |
      WebSocket protocol bridge for Cognigy Voice Gateway TTS integration.
      Accepts Cognigy's native websocket messages (stream, flush, stop)
      and translates them to SLNG's standard TTS websocket protocol.
      The model_variant path parameter specifies the target TTS model.
    tags:
      - name: Cognigy TTS Bridge
    servers:
      - $ref: "#/servers/production"
      - $ref: "#/servers/staging"
    messages:
      request:
        $ref: "#/components/messages/CognigyTTSWebsocketRequest"
      response:
        $ref: "#/components/messages/CognigyTTSWebsocketResponse"
    bindings:
      ws:
        method: GET
        headers:
          $ref: "#/components/schemas/WebsocketHeaders"
operations:
  cognigySttBridgeSend:
    action: send
    channel:
      $ref: "#/channels/~1v1~1bridges~1cognigy~1stt~1%7Bmodel_variant%7D"
    summary: Send audio to Cognigy STT Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1cognigy~1stt~1%7Bmodel_variant%7D/messages/request"
    description: Send start/stop messages and audio frames to Cognigy STT Bridge
  cognigySttBridgeReceive:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1bridges~1cognigy~1stt~1%7Bmodel_variant%7D"
    summary: Receive transcriptions from Cognigy STT Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1cognigy~1stt~1%7Bmodel_variant%7D/messages/response"
    description: Receive transcription events from Cognigy STT Bridge
  cognigyTtsBridgeSend:
    action: send
    channel:
      $ref: "#/channels/~1v1~1bridges~1cognigy~1tts~1%7Bmodel_variant%7D"
    summary: Send text to Cognigy TTS Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1cognigy~1tts~1%7Bmodel_variant%7D/messages/request"
    description: Send stream/flush/stop messages to Cognigy TTS Bridge
  cognigyTtsBridgeReceive:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1bridges~1cognigy~1tts~1%7Bmodel_variant%7D"
    summary: Receive audio from Cognigy TTS Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1cognigy~1tts~1%7Bmodel_variant%7D/messages/response"
    description: Receive connect events and audio chunks from Cognigy TTS Bridge
components:
  messages:
    CognigyTTSWebsocketResponse:
      name: CognigyTTSWebsocketResponse
      title: Cognigy TTS WebSocket Response
      payload:
        $ref: "#/components/schemas/CognigyTTSWebsocketServerMessage"
    CognigyTTSWebsocketRequest:
      name: CognigyTTSWebsocketRequest
      title: Cognigy TTS WebSocket Request
      payload:
        $ref: "#/components/schemas/CognigyTTSWebsocketClientMessage"
    CognigySTTWebsocketResponse:
      name: CognigySTTWebsocketResponse
      title: Cognigy STT WebSocket Response
      payload:
        $ref: "#/components/schemas/CognigySTTWebsocketServerMessage"
    CognigySTTWebsocketRequest:
      name: CognigySTTWebsocketRequest
      title: Cognigy STT WebSocket Request
      payload:
        $ref: "#/components/schemas/CognigySTTWebsocketClientMessage"
  schemas:
    CognigyTTSWebsocketServerMessage:
      oneOf:
        - title: Connect Message
          type: object
          description: Connection established with audio format information.
          required:
            - type
            - data
          properties:
            type:
              const: connect
            data:
              type: object
              description: Audio format configuration
              properties:
                sample_rate:
                  $ref: "#/components/schemas/SampleRate"
                base64_encoding:
                  type: boolean
                  description: Whether audio chunks are base64 encoded
        - title: Error Message
          type: object
          description: Error occurred during synthesis.
          required:
            - type
            - error
            - message
          properties:
            type:
              const: error
            error:
              type: string
              description: Error code
            message:
              type: string
              description: Human-readable error description
    SampleRate:
      type: integer
      description: Audio sample rate in Hz.
      enum:
        - 8000
        - 16000
        - 22050
        - 24000
        - 32000
        - 44100
        - 48000
    CognigyTTSWebsocketClientMessage:
      oneOf:
        - title: Stream Message
          type: object
          description: Send text to synthesize into audio.
          required:
            - type
            - text
          properties:
            type:
              const: stream
            text:
              type: string
              description: Text to synthesize
        - title: Flush Message
          type: object
          description: Flush any buffered audio to the client.
          required:
            - type
          properties:
            type:
              const: flush
        - title: Stop Message
          type: object
          description: Stop synthesis and close the session.
          required:
            - type
          properties:
            type:
              const: stop
    WebsocketHeaders:
      type: object
      properties:
        X-Region-Override:
          type: string
          description: Optional. Specify a target region for this model. If not provided, the system will automatically select an appropriate region.
        Upgrade:
          type: string
          enum:
            - websocket
        Connection:
          type: string
          enum:
            - Upgrade
    CognigySTTWebsocketServerMessage:
      oneOf:
        - title: Transcription Message
          type: object
          description: Transcription result with alternatives and metadata.
          required:
            - type
            - is_final
            - alternatives
          properties:
            type:
              const: transcription
            is_final:
              type: boolean
              description: Whether this is a final (not interim) transcription
            alternatives:
              type: array
              description: List of transcription alternatives ranked by confidence
              items:
                type: object
                properties:
                  confidence:
                    type: number
                    description: Confidence score (0-1)
                  transcript:
                    type: string
                    description: Transcribed text
            channel:
              type: integer
              description: Audio channel number
            language:
              allOf:
                - $ref: "#/components/schemas/LanguageCode"
                - description: Detected language code.
        - title: Error Message
          type: object
          description: Error occurred during recognition.
          required:
            - type
            - error
            - message
          properties:
            type:
              const: error
            error:
              type: string
              description: Error code
            message:
              type: string
              description: Human-readable error description
    LanguageCode:
      type: string
      description: ISO-639-1 language code.
      enum:
        - en
        - ja
        - zh
        - de
        - hi
        - fr
        - ko
        - pt
        - it
        - es
        - id
        - nl
        - tr
        - fil
        - pl
        - sv
        - bg
        - ro
        - ar
        - cs
        - el
        - fi
        - hr
        - ms
        - sk
        - da
        - ta
        - uk
        - ru
        - hu
        - no
        - vi
    CognigySTTWebsocketClientMessage:
      oneOf:
        - title: Start Message
          type: object
          description: Initialize STT session with language and sample rate configuration.
          required:
            - type
          properties:
            type:
              const: start
            language:
              allOf:
                - $ref: "#/components/schemas/LanguageCode"
                - description: Language code for recognition.
            sample_rate:
              type: number
              description: Audio sample rate in Hz.
              enum:
                - 8000
                - 16000
                - 22050
                - 24000
                - 32000
                - 48000
        - title: Stop Message
          type: object
          description: End the STT session and finalize transcription.
          required:
            - type
          properties:
            type:
              const: stop