asyncapi: 3.0.0
info:
  title: SLNG Gateway API - Cognigy Bridges
  version: 0.1.0
  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
    - name: Unmute STT Bridge
      description: SLNG native WebSocket STT protocol bridge.
    - name: Unmute TTS Bridge
      description: SLNG native WebSocket TTS protocol bridge.
servers:
  production:
    host: api.slng.ai
    protocol: wss
    description: Production
    security:
      - $ref: "#/components/securitySchemes/bearer"
  staging:
    host: stageapi.slng.ai
    protocol: wss
    description: Staging
    security:
      - $ref: "#/components/securitySchemes/bearer"
channels:
  /v1/bridges/cognigy/stt/{model_variant}:
    address: /v1/bridges/cognigy/stt/{model_variant}
    title: Cognigy STT Bridge
    summary: Cognigy STT Bridge
    description: Stream live audio to SLNG over the Cognigy Voice Gateway WebSocket protocol and receive real-time STT transcripts from any supported model.
    tags:
      - name: Cognigy STT Bridge
    servers:
      - $ref: "#/servers/production"
      - $ref: "#/servers/staging"
    messages:
      CognigyStartMessage:
        $ref: "#/components/messages/CognigyStartMessage"
      CognigyStopMessage:
        $ref: "#/components/messages/CognigyStopMessage"
      CognigyTranscription:
        $ref: "#/components/messages/CognigyTranscription"
      CognigySTTErrorResponse:
        $ref: "#/components/messages/CognigySTTErrorResponse"
      KeepaliveMessage:
        $ref: "#/components/messages/KeepaliveMessage"
    bindings:
      ws:
        method: GET
        headers:
          $ref: "#/components/schemas/WebsocketHeaders"
        query:
          $ref: "#/components/schemas/WebsocketQueryParams"
  /v1/bridges/cognigy/tts/{model_variant}:
    address: /v1/bridges/cognigy/tts/{model_variant}
    title: Cognigy TTS Bridge
    summary: Cognigy TTS Bridge
    description: Stream synthesized speech from SLNG over the Cognigy Voice Gateway WebSocket protocol using any supported text-to-speech model and voice.
    tags:
      - name: Cognigy TTS Bridge
    servers:
      - $ref: "#/servers/production"
      - $ref: "#/servers/staging"
    messages:
      CognigyStreamMessage:
        $ref: "#/components/messages/CognigyStreamMessage"
      CognigyFlushMessage:
        $ref: "#/components/messages/CognigyFlushMessage"
      CognigyTtsStopMessage:
        $ref: "#/components/messages/CognigyTtsStopMessage"
      CognigyConnectMessage:
        $ref: "#/components/messages/CognigyConnectMessage"
      CognigyTTSErrorResponse:
        $ref: "#/components/messages/CognigyTTSErrorResponse"
      KeepaliveMessage:
        $ref: "#/components/messages/KeepaliveMessage"
    bindings:
      ws:
        method: GET
        headers:
          $ref: "#/components/schemas/WebsocketHeaders"
        query:
          $ref: "#/components/schemas/WebsocketQueryParams"
operations:
  cognigySttBridgeReceiveStart:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1bridges~1cognigy~1stt~1%7Bmodel_variant%7D"
    summary: Start session on Cognigy STT Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1cognigy~1stt~1%7Bmodel_variant%7D/messages/CognigyStartMessage"
    description: Start session on Cognigy STT Bridge
    tags: []
  cognigySttBridgeReceiveStop:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1bridges~1cognigy~1stt~1%7Bmodel_variant%7D"
    summary: Stop session on Cognigy STT Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1cognigy~1stt~1%7Bmodel_variant%7D/messages/CognigyStopMessage"
    description: Stop session on Cognigy STT Bridge
    tags: []
  cognigySttBridgeReceiveKeepalive:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1bridges~1cognigy~1stt~1%7Bmodel_variant%7D"
    summary: Send keepalive on Cognigy STT Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1cognigy~1stt~1%7Bmodel_variant%7D/messages/KeepaliveMessage"
    description: Send keepalive on Cognigy STT Bridge
    tags: []
  cognigySttBridgeSendTranscription:
    action: send
    channel:
      $ref: "#/channels/~1v1~1bridges~1cognigy~1stt~1%7Bmodel_variant%7D"
    summary: Receive transcription from Cognigy STT Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1cognigy~1stt~1%7Bmodel_variant%7D/messages/CognigyTranscription"
    description: Receive transcription from Cognigy STT Bridge
    tags: []
  cognigySttBridgeSendError:
    action: send
    channel:
      $ref: "#/channels/~1v1~1bridges~1cognigy~1stt~1%7Bmodel_variant%7D"
    summary: Receive error from Cognigy STT Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1cognigy~1stt~1%7Bmodel_variant%7D/messages/CognigySTTErrorResponse"
    description: Receive error from Cognigy STT Bridge
    tags: []
  cognigyTtsBridgeReceiveStream:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1bridges~1cognigy~1tts~1%7Bmodel_variant%7D"
    summary: Stream data to Cognigy TTS Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1cognigy~1tts~1%7Bmodel_variant%7D/messages/CognigyStreamMessage"
    description: Stream data to Cognigy TTS Bridge
    tags: []
  cognigyTtsBridgeReceiveFlush:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1bridges~1cognigy~1tts~1%7Bmodel_variant%7D"
    summary: Flush buffered output on Cognigy TTS Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1cognigy~1tts~1%7Bmodel_variant%7D/messages/CognigyFlushMessage"
    description: Flush buffered output on Cognigy TTS Bridge
    tags: []
  cognigyTtsBridgeReceiveStop:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1bridges~1cognigy~1tts~1%7Bmodel_variant%7D"
    summary: Stop session on Cognigy TTS Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1cognigy~1tts~1%7Bmodel_variant%7D/messages/CognigyTtsStopMessage"
    description: Stop session on Cognigy TTS Bridge
    tags: []
  cognigyTtsBridgeReceiveKeepalive:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1bridges~1cognigy~1tts~1%7Bmodel_variant%7D"
    summary: Send keepalive on Cognigy TTS Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1cognigy~1tts~1%7Bmodel_variant%7D/messages/KeepaliveMessage"
    description: Send keepalive on Cognigy TTS Bridge
    tags: []
  cognigyTtsBridgeSendConnect:
    action: send
    channel:
      $ref: "#/channels/~1v1~1bridges~1cognigy~1tts~1%7Bmodel_variant%7D"
    summary: Receive connect signal from Cognigy TTS Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1cognigy~1tts~1%7Bmodel_variant%7D/messages/CognigyConnectMessage"
    description: Receive connect signal from Cognigy TTS Bridge
    tags: []
  cognigyTtsBridgeSendError:
    action: send
    channel:
      $ref: "#/channels/~1v1~1bridges~1cognigy~1tts~1%7Bmodel_variant%7D"
    summary: Receive error from Cognigy TTS Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1cognigy~1tts~1%7Bmodel_variant%7D/messages/CognigyTTSErrorResponse"
    description: Receive error from Cognigy TTS Bridge
    tags: []
components:
  messages:
    CognigyTTSErrorResponse:
      name: CognigyTTSErrorResponse
      title: Error Response (Cognigy TTS)
      summary: Error occurred during Cognigy TTS synthesis.
      contentType: application/json
      payload:
        type: object
        description: Error occurred during synthesis.
        required:
          - type
          - message
        properties:
          type:
            type: string
            const: error
          error:
            type: string
            description: Error code. May be omitted when the upstream provider does not surface a discrete error code.
          message:
            type: string
            description: Human-readable error description
      examples:
        - name: cognigyTTSError
          summary: Cognigy TTS error
          payload:
            type: error
            error: provider_error
            message: TTS provider returned an error
    CognigyConnectMessage:
      name: CognigyConnectMessage
      title: Connect Message
      summary: Connection established with audio format information.
      contentType: application/json
      payload:
        type: object
        description: Connection established with audio format information.
        required:
          - type
          - data
        properties:
          type:
            type: string
            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
      examples:
        - name: cognigyConnect
          summary: Cognigy TTS connection established
          payload:
            type: connect
            data:
              sample_rate: 16000
              base64_encoding: true
    CognigyTtsStopMessage:
      name: CognigyTtsStopMessage
      title: Stop Message (Cognigy TTS)
      summary: Stop synthesis and close the Cognigy TTS session.
      contentType: application/json
      payload:
        type: object
        description: Stop synthesis and close the session.
        required:
          - type
        properties:
          type:
            type: string
            const: stop
      examples:
        - name: cognigyTtsStop
          summary: Stop Cognigy TTS session
          payload:
            type: stop
    CognigyFlushMessage:
      name: CognigyFlushMessage
      title: Flush Message (Cognigy)
      summary: Flush any buffered audio to the Cognigy client.
      contentType: application/json
      payload:
        type: object
        description: Flush any buffered audio to the client.
        required:
          - type
        properties:
          type:
            type: string
            const: flush
      examples:
        - name: cognigyFlush
          summary: Flush buffered audio
          payload:
            type: flush
    CognigyStreamMessage:
      name: CognigyStreamMessage
      title: Stream Message
      summary: Send text to synthesize into audio for Cognigy TTS.
      contentType: application/json
      payload:
        type: object
        description: Send text to synthesize into audio.
        required:
          - type
          - text
        properties:
          type:
            type: string
            const: stream
          text:
            type: string
            description: Text to synthesize
          pronunciation:
            type: object
            description: Optional pronunciation hint applied to this text chunk. Forwarded to providers that support pronunciation dictionaries (e.g. IPA or SSML overrides).
            properties:
              mode:
                type: string
                description: Pronunciation override mode (e.g. `ipa`, `ssml`).
              name:
                type: string
                description: Identifier of the term whose pronunciation is being overridden.
              dictionary_id:
                type: string
                description: Pronunciation dictionary identifier.
      examples:
        - name: cognigyStream
          summary: Stream text for synthesis
          payload:
            type: stream
            text: Hello from Cognigy TTS bridge.
    KeepaliveMessage:
      name: KeepaliveMessage
      title: Keepalive Message
      summary: Keep the WebSocket connection alive during silence.
      contentType: application/json
      payload:
        type: object
        description: Prevents the connection from being closed due to inactivity. Send periodically during silence to maintain the session.
        required:
          - type
        properties:
          type:
            type: string
            const: keepalive
      examples:
        - name: keepalive
          summary: Send keepalive
          payload:
            type: keepalive
    CognigySTTErrorResponse:
      name: CognigySTTErrorResponse
      title: Error Response (Cognigy STT)
      summary: Error occurred during Cognigy STT recognition.
      contentType: application/json
      payload:
        type: object
        description: Error occurred during recognition.
        required:
          - type
          - message
        properties:
          type:
            type: string
            const: error
          error:
            type: string
            description: Error code. May be omitted when the upstream provider does not surface a discrete error code.
          message:
            type: string
            description: Human-readable error description
      examples:
        - name: cognigySTTError
          summary: Cognigy STT error
          payload:
            type: error
            error: config_error
            message: Invalid language code
    CognigyTranscription:
      name: CognigyTranscription
      title: Transcription
      summary: Transcription result with alternatives and metadata.
      contentType: application/json
      payload:
        type: object
        description: Transcription result with alternatives and metadata.
        required:
          - type
          - is_final
          - alternatives
        properties:
          type:
            type: string
            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:
            $ref: "#/components/schemas/LanguageCode"
      examples:
        - name: cognigyTranscription
          summary: Cognigy transcription result
          payload:
            type: transcription
            is_final: true
            alternatives:
              - confidence: 0.95
                transcript: Hello world
            language: en
    CognigyStopMessage:
      name: CognigyStopMessage
      title: Stop Message
      summary: End the Cognigy STT session and finalize transcription.
      contentType: application/json
      payload:
        type: object
        description: End the STT session and finalize transcription.
        required:
          - type
        properties:
          type:
            type: string
            const: stop
      examples:
        - name: cognigyStop
          summary: Stop Cognigy STT session
          payload:
            type: stop
    CognigyStartMessage:
      name: CognigyStartMessage
      title: Start Message
      summary: Initialize Cognigy STT session with language and sample rate.
      contentType: application/json
      payload:
        type: object
        description: Initialize STT session with language and sample rate configuration.
        required:
          - type
        properties:
          type:
            type: string
            const: start
          language:
            $ref: "#/components/schemas/LanguageCode"
          sample_rate:
            type: number
            description: Audio sample rate in Hz.
            enum:
              - 8000
              - 16000
              - 22050
              - 24000
              - 32000
              - 48000
      examples:
        - name: cognigyStart
          summary: Start Cognigy STT session
          payload:
            type: start
            language: en
            sample_rate: 16000
  schemas:
    SampleRate:
      type: integer
      description: Audio sample rate in Hz.
      enum:
        - 8000
        - 16000
        - 22050
        - 24000
        - 32000
        - 44100
        - 48000
    WebsocketHeaders:
      type: object
      properties:
        X-Region-Override:
          type: string
          description: Target region override. Auto-selected if not provided.
        X-World-Part-Override:
          type: string
          description: Target world part override. Auto-selected if not provided.
    WebsocketQueryParams:
      type: object
      properties:
        region:
          type: string
          description: Target region override as a query parameter. Auto-selected if not provided. Equivalent to the `X-Region-Override` header; the header takes precedence when both are set.
          enum:
            - ap-southeast-2
            - eu-north-1
            - us-east-1
        world-part:
          type: string
          description: Target world part override as a query parameter. Auto-selected if not provided. Equivalent to the `X-World-Part-Override` header; the header takes precedence when both are set.
          enum:
            - ap
            - eu
            - na
    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
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: |
        API key issued by SLNG. Pass as `Authorization: Bearer <token>` in the WebSocket upgrade request headers.