asyncapi.yml

asyncapi: 3.0.0
info:
  title: Deepgram Websocket Specification
  version: 1.0.0
  description: >
    Deepgram's voice AI platform provides APIs for speech-to-text,
    text-to-speech, and language understanding. From medical transcription to
    autonomous agents, Deepgram is the go-to choice for developers of voice AI
    experiences.

    The Deepgram API allows you to interact with Deepgram programmatically.

    You can use our Websockets to: - Transcribe speech to text. - Transform text
    to speech. - Build a Voice Agent.
  tags:
    - name: listen
      description: Speech to Text WebSocket API
    - name: speak
      description: Text to Speech WebSocket API
    - name: agent
      description: Voice Agent WebSocket API
  termsOfService: https://deepgram.com/terms/
  contact:
    name: Deepgram Developer Relations
    email: devrel@deepgram.com
    url: https://community.deepgram.com
  license:
    name: Privacy Notice
    url: https://deepgram.com/privacy/
  externalDocs:
    description: Learn more about using Deepgram on our docs.
    url: http://developers.deepgram.com
servers:
  public:
    host: api.deepgram.com
    protocol: wss
channels:
  speak:
    address: /v1/speak
    description: Deepgram Text to Speech WebSocket
    parameters:
      ApiKey:
        description: >-
          API key for authentication. Format should be 'token
          <DEEPGRAM_API_KEY>'
        location: $message.header#/Authorization
        examples:
          - token YOUR_DEEPGRAM_API_KEY
      encoding:
        description: >-
          Encoding allows you to specify the expected encoding of your audio
          output
        location: $message.payload#/encoding
        default: mp3
        enum:
          - linear16
          - mulaw
          - alaw
          - opus
          - mp3
          - flac
          - aac
        examples:
          - linear16
      model:
        description: AI model used to process submitted text
        location: $message.payload#/model
        default: aura-asteria-en
        enum:
          - aura-asteria-en
          - aura-luna-en
          - aura-stella-en
          - aura-athena-en
          - aura-hera-en
          - aura-orion-en
          - aura-arcas-en
          - aura-perseus-en
          - aura-angus-en
          - aura-orpheus-en
          - aura-helios-en
          - aura-zeus-en
        examples:
          - aura-asteria-en
      sample_rate:
        description: >-
          Sample Rate specifies the sample rate for the output audio. Based on
          encoding 8000 or 24000 are possible defaults. For some encodings
          sample rate is not configurable.
        location: $message.payload#/sample_rate
        default: '24000'
        enum:
          - '8000'
          - '16000'
          - '24000'
          - '44100'
          - '48000'
        examples:
          - '24000'
    messages:
      textToSpeechRequest:
        description: Request to convert text to speech
        payload:
          type: object
          properties:
            type:
              type: string
              enum:
                - Speak
              description: Message type indicating a text-to-speech request
            text:
              type: string
              description: The input text to be converted to speech
          required:
            - type
            - text
        examples:
          - payload:
              type: Speak
              text: Hello, world!
          - payload:
              type: Speak
              text: Convert this text to speech
      controlMessagesRequest:
        description: Control messages for managing the Text to Speech WebSocket connection
        payload:
          type: object
          properties:
            type:
              type: string
              enum:
                - Flush
                - Clear
                - Close
          required:
            - type
        examples:
          - payload:
              type: Flush
          - payload:
              type: Clear
          - payload:
              type: Close
      textToSpeechResponse:
        contentType: application/octet-stream
        payload:
          type: string
          format: binary
          description: Audio data in the format specified by the request parameters
      controlMessagesResponse:
        contentType: application/json
        payload:
          type: object
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - flush
                - clear
                - close
              description: The type of control message response
            sequence_id:
              type: integer
              description: The sequence ID of the response
      metadataResponse:
        contentType: application/json
        payload:
          type: object
          description: >-
            Text to Speech Metadata information sent immediately after
            completing the WebSocket handshake
          properties:
            type:
              type: string
              description: Message type identifier
            request_id:
              type: string
              format: uuid
              description: Unique identifier for the request
            model_name:
              type: string
              description: Name of the model being used
            model_version:
              type: string
              description: Version of the model being used
            model_uuid:
              type: string
              format: uuid
              description: Unique identifier for the model
      errorResponse:
        contentType: application/json
        description: Error information for failed requests
        payload:
          type: object
          required:
            - error_code
            - error_message
            - request_id
          properties:
            error_code:
              type: integer
              enum:
                - 400
                - 401
                - 402
                - 403
                - 429
                - 503
              description: HTTP status code equivalent
            error_message:
              type: string
              description: Error message
            request_id:
              type: string
              format: uuid
              description: Unique identifier for the request
      successResponse:
        contentType: application/json
        description: Sent when a request completes successfully
        payload:
          type: object
          required:
            - success_code
            - success_message
            - request_id
          properties:
            success_code:
              type: integer
              enum:
                - 200
              description: HTTP status code equivalent
            success_message:
              type: string
              description: Success message
            request_id:
              type: string
              format: uuid
              description: Unique identifier for the request
      closeFrame:
        payload:
          type: object
          description: >
            When Deepgram encounters an error during streaming text to speech, a
            WebSocket Close frame is sent. The frame contains a status code and
            UTF-8-encoded payload describing the error reason
          required:
            - code
            - payload
          properties:
            code:
              type: integer
              enum:
                - 1000
                - 1003
                - 1008
                - 1009
                - 1011
              description: WebSocket close status code
            payload:
              type: string
              enum:
                - None
                - MESSAGE-0000
                - DATA-0000
                - BIG-0000
                - BIG-0001
                - NET-0000
                - NET-0001
                - NET-0002
                - NET-0003
              description: Error reason code
          examples:
            - code: 1000
              payload: None
              description: Normal closure
            - code: 1003
              payload: MESSAGE-0000
              description: Input message isn't a supported websocket message type
            - code: 1008
              payload: DATA-0000
              description: Input message isn't recognized as a valid command
            - code: 1009
              payload: BIG-0000
              description: Input message is too large
            - code: 1009
              payload: BIG-0001
              description: Input text has too many characters
            - code: 1011
              payload: NET-0000
              description: Internal server error
            - code: 1011
              payload: NET-0001
              description: Failed to receive message
            - code: 1011
              payload: NET-0002
              description: Failed to send message
            - code: 1011
              payload: NET-0003
              description: Time limit exceeded
  listen:
    address: /v1/listen
    description: Deepgram Speech to Text WebSocket
    parameters:
      ApiKey:
        description: >-
          API key for authentication. Format should be 'token
          <DEEPGRAM_API_KEY>'
        location: $message.header#/Authorization
        examples:
          - token YOUR_DEEPGRAM_API_KEY
      callback:
        description: URL to which we'll make the callback request
        location: $message.payload#/callback
        examples:
          - https://example.com
      callback_method:
        description: HTTP method by which the callback request will be made
        location: $message.payload#/callback_method
        default: POST
        enum:
          - POST
          - GET
          - PUT
          - DELETE
        examples:
          - POST
          - GET
          - PUT
          - DELETE
      channels:
        description: The number of channels in the submitted audio
        location: $message.payload#/channels
        default: '1'
        examples:
          - '1'
      diarize:
        description: >-
          Recognize speaker changes. Each word in the transcript will be
          assigned a speaker number starting at 0
        location: $message.payload#/diarize
        default: 'false'
        enum:
          - 'true'
          - 'false'
        examples:
          - 'true'
      diarize_version:
        description: >-
          Version of the diarization feature to use. Only used when the
          diarization feature is enabled (`diarize=true` is passed to the API)
        location: $message.payload#/diarize_version
        default: v2
        examples:
          - v1
          - v2
      dictation:
        description: Identify and extract key entities from content in submitted audio
        location: $message.payload#/dictation
        default: 'false'
        enum:
          - 'true'
          - 'false'
        examples:
          - 'true'
      encoding:
        description: Specify the expected encoding of your submitted audio
        location: $message.payload#/encoding
        enum:
          - linear16
          - flac
          - mulaw
          - amr-nb
          - amr-wb
          - opus
          - speex
          - g729
        examples:
          - linear16
      endpointing:
        description: >-
          Indicates how long Deepgram will wait to detect whether a speaker has
          finished speaking or pauses for a significant period of time. When set
          to a value, the streaming endpoint immediately finalizes the
          transcription for the processed time range and returns the transcript
          with a speech_final parameter set to true. Can also be set to false to
          disable endpointing
        location: $message.payload#/endpointing
        default: '10'
        examples:
          - '300'
          - false"
      extra:
        description: >-
          Arbitrary key-value pairs that are attached to the API response for
          usage in downstream processing
        location: $message.payload#/extra
        examples:
          - key:value
      filler_words:
        description: >-
          Filler Words can help transcribe interruptions in your audio, like
          "uh" and "um"
        location: $message.payload#/filler_words
        default: 'false'
        enum:
          - 'true'
          - 'false'
        examples:
          - 'true'
      interim_results:
        description: >-
          Specifies whether the streaming endpoint should provide ongoing
          transcription updates as more audio is received. When set to true, the
          endpoint sends continuous updates, meaning transcription results may
          evolve over time
        location: $message.payload#/interim_results
        default: 'false'
        enum:
          - 'true'
          - 'false'
        examples:
          - 'true'
      keyterm:
        description: >-
          Key term prompting can boost or suppress specialized terminology and
          brands. Only compatible with Nova-3
        location: $message.payload#/keyterm
        examples:
          - Snuffleupagus
      keywords:
        description: Keywords can boost or suppress specialized terminology and brands
        location: $message.payload#/keywords
        examples:
          - Twilio:2
      language:
        description: >-
          The [BCP-47 language tag](https://tools.ietf.org/html/bcp47) that
          hints at the primary spoken language. Depending on the Model you
          choose only certain languages are available
        location: $message.payload#/language
        default: en
        enum:
          - bg
          - ca
          - cs
          - da
          - da-DK
          - de
          - de-CH
          - el
          - en
          - en-AU
          - en-GB
          - en-IN
          - en-NZ
          - en-US
          - es
          - es-419
          - es-LATAM
          - et
          - fi
          - fr
          - fr-CA
          - hi
          - hi-Latn
          - hu
          - id
          - it
          - ja
          - ko
          - ko-KR
          - lt
          - lv
          - ms
          - nl
          - nl-BE
          - 'no'
          - pl
          - pt
          - pt-BR
          - pt-PT
          - ro
          - ru
          - sk
          - sv
          - sv-SE
          - taq
          - th
          - th-TH
          - tr
          - uk
          - vi
          - zh
          - zh-CN
          - zh-HK
          - zh-Hans
          - zh-Hant
          - zh-TW
        examples:
          - en
      model:
        description: AI model to use for the transcription
        location: $message.payload#/model
        enum:
          - nova-3
          - nova-3-general
          - nova-2
          - nova-2-general
          - nova-2-meeting
          - nova-2-finance
          - nova-2-conversationalai
          - nova-2-voicemail
          - nova-2-video
          - nova-2-medical
          - nova-2-drivethru
          - nova-2-automotive
          - nova
          - nova-general
          - nova-phonecall
          - nova-medical
          - enhanced
          - enhanced-general
          - enhanced-meeting
          - enhanced-phonecall
          - enhanced-finance
          - base
          - meeting
          - phonecall
          - finance
          - conversationalai
          - voicemail
          - video
          - custom
        examples:
          - nova-2
          - custom model name
      multichannel:
        description: Transcribe each audio channel independently
        location: $message.payload#/multichannel
        default: 'false'
        enum:
          - 'true'
          - 'false'
        examples:
          - 'true'
      numerals:
        description: Convert numbers from written format to numerical format
        location: $message.payload#/numerals
        default: 'false'
        enum:
          - 'true'
          - 'false'
        examples:
          - 'true'
      profanity_filter:
        description: >-
          Profanity Filter looks for recognized profanity and converts it to the
          nearest recognized non-profane word or removes it from the transcript
          completely
        location: $message.payload#/profanity_filter
        default: 'false'
        enum:
          - 'true'
          - 'false'
        examples:
          - 'true'
      punctuate:
        description: Add punctuation and capitalization to the transcript
        location: $message.payload#/punctuate
        default: 'false'
        enum:
          - 'true'
          - 'false'
        examples:
          - 'true'
      redact:
        description: Redaction removes sensitive information from your transcripts
        location: $message.payload#/redact
        default: 'false'
        enum:
          - 'true'
          - 'false'
        examples:
          - 'true'
      replace:
        description: Search for terms or phrases in submitted audio and replaces them
        location: $message.payload#/replace
        examples:
          - monika:Monica
      sample_rate:
        description: >-
          Sample rate of submitted audio. Required (and only read) when a value
          is provided for encoding
        location: $message.payload#/sample_rate
        examples:
          - '8000'
      search:
        description: Search for terms or phrases in submitted audio
        location: $message.payload#/search
        examples:
          - Deepgram
          - Text to Speech
      smart_format:
        description: >-
          Apply formatting to transcript output. When set to true, additional
          formatting will be applied to transcripts to improve readability
        location: $message.payload#/smart_format
        default: 'false'
        enum:
          - 'true'
          - 'false'
        examples:
          - 'true'
      tag:
        description: >-
          Label your requests for the purpose of identification during usage
          reporting
        location: $message.payload#/tag
        examples:
          - my-team
          - marketing%20team
      utterance_end:
        description: >-
          Indicates how long Deepgram will wait to send an UtteranceEnd message
          after a word has been transcribed. Use with interim_results
        location: $message.payload#/utterance_end
        examples:
          - '1000'
      vad_events:
        description: >-
          Indicates that speech has started. You'll begin receiving Speech
          Started messages upon speech starting
        location: $message.payload#/vad_events
        default: 'false'
        enum:
          - 'true'
          - 'false'
        examples:
          - 'true'
      version:
        description: Version of an AI model to use
        location: $message.payload#/version
        default: latest
        examples:
          - MODEL_VERSION
    messages:
      transcriptionRequest:
        description: >-
          Request to convert speech to text. Audio data is transmitted as raw
          binary WebSocket messages
        payload:
          type: string
          format: binary
          description: >-
            Raw audio data to be transcribed. Should be sent as a binary
            WebSocket message without base64 encoding
        examples:
          - payload: <binary audio data>
      controlMessagesRequest:
        description: Control messages for managing the Speech to Text WebSocket connection
        payload:
          type: object
          oneOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - Finalize
                  description: >-
                    Used to handle specific scenarios where you need to force
                    the server to process all unprocessed audio data and
                    immediately return the final results
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - CloseStream
                  description: Close the websocket connection
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - KeepAlive
                  description: Used to keep the websocket connection alive
          required:
            - type
        examples:
          - payload:
              type: Finalize
          - payload:
              type: CloseStream
          - payload:
              type: KeepAlive
      transcriptionResponse:
        contentType: application/json
        payload:
          type: object
          properties:
            channel:
              type: object
              properties:
                alternatives:
                  type: array
                  items:
                    type: object
                    properties:
                      transcript:
                        type: string
                        description: Complete transcribed text
                      confidence:
                        type: number
                        format: float
                        description: Overall confidence score
                      words:
                        type: array
                        items:
                          type: object
                          properties:
                            word:
                              type: string
                            start:
                              type: number
                              format: float
                            end:
                              type: number
                              format: float
                            confidence:
                              type: number
                              format: float
                            punctuated_word:
                              type: string
            metadata:
              type: object
              properties:
                model_info:
                  type: object
                  properties:
                    name:
                      type: string
                    version:
                      type: string
                    arch:
                      type: string
                request_id:
                  type: string
                  format: uuid
                model_uuid:
                  type: string
                  format: uuid
            type:
              type: string
            channel_index:
              type: array
              items:
                type: integer
            duration:
              type: number
              format: float
            start:
              type: number
              format: float
            is_final:
              type: boolean
            from_finalize:
              type: boolean
            speech_final:
              type: boolean
      controlMessageResponse:
        contentType: application/json
        payload:
          type: object
          required:
            - type
          oneOf:
            - title: FinalizeResponse
              description: >
                The server will process all remaining audio data and return the
                final results. You may receive a response with the from_finalize
                attribute set to true, indicating that the finalization process
                is complete. This response typically occurs when there is a
                noticeable amount of audio buffered in the server.
              allOf:
                - properties:
                    type:
                      type: string
                      enum:
                        - Finalize
                    channel:
                      type: integer
                      description: The channel number being finalized
                      minimum: 0
                - required:
                    - type
                    - channel
            - title: MetadataResponse
              description: >
                Provides real-time metadata during audio streaming, including
                audio characteristics

                and processing details. This response is sent periodically
                during streaming to

                provide updates about the audio being processed.
              allOf:
                - properties:
                    type:
                      type: string
                      enum:
                        - Metadata
                    transaction_key:
                      type: string
                      description: Deprecated field
                    request_id:
                      type: string
                      format: uuid
                      description: Unique identifier for the request
                    sha256:
                      type: string
                      pattern: ^[a-fA-F0-9]{64}$
                      description: SHA-256 hash of the audio content
                    created:
                      type: string
                      format: date-time
                      description: Timestamp when the response was created
                    duration:
                      type: number
                      format: float
                      description: Duration of the audio in seconds
                    channels:
                      type: integer
                      minimum: 0
                      description: Number of audio channels
                - required:
                    - type
                    - request_id
                    - sha256
                    - created
                    - duration
                    - channels
            - title: CloseStreamResponse
              description: >
                Indicates that the server has closed the WebSocket connection
                and the server will process all remaining audio data.
              allOf:
                - properties:
                    type:
                      type: string
                      enum:
                        - CloseStream
                    transaction_key:
                      type: string
                      description: Deprecated field
                    request_id:
                      type: string
                      format: uuid
                      description: Unique identifier for the request
                    sha256:
                      type: string
                      pattern: ^[a-fA-F0-9]{64}$
                      description: SHA-256 hash of the audio content
                    created:
                      type: string
                      format: date-time
                      description: Timestamp when the response was created
                    duration:
                      type: number
                      format: float
                      description: Duration of the audio in seconds
                    channels:
                      type: integer
                      minimum: 0
                      description: Number of audio channels
                - required:
                    - type
                    - request_id
                    - sha256
                    - created
                    - duration
                    - channels
        examples:
          - payload:
              type: Finalize
              channel: 0
          - payload:
              type: Metadata
              transaction_key: deprecated
              request_id: 8c8ebea9-dbec-45fa-a035-e4632cb05b5f
              sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
              created: '2024-08-29T22:37:55.202Z'
              duration: 0
              channels: 0
          - payload:
              type: CloseStream
              transaction_key: deprecated
              request_id: 8c8ebea9-dbec-45fa-a035-e4632cb05b5f
              sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
              created: '2024-08-29T22:37:55.202Z'
              duration: 0
              channels: 0
      metadataResponse:
        contentType: application/json
        payload:
          type: object
          description: Sent immediately after completing the WebSocket handshake
          properties:
            type:
              type: string
              description: Message type identifier
            request_id:
              type: string
              format: uuid
              description: Unique identifier for the request
            model_name:
              type: string
              description: Name of the model being used
            model_version:
              type: string
              description: Version of the model being used
            model_uuid:
              type: string
              format: uuid
              description: Unique identifier for the model
      errorResponse:
        contentType: application/json
        description: Error information for failed requests
        payload:
          type: object
          required:
            - error_code
            - error_message
            - request_id
          properties:
            error_code:
              type: integer
              enum:
                - 400
                - 401
                - 402
                - 403
                - 429
                - 503
              description: HTTP status code equivalent
            error_message:
              type: string
              description: Error message
            request_id:
              type: string
              format: uuid
              description: Unique identifier for the request
      successResponse:
        contentType: application/json
        description: Sent when a request completes successfully
        payload:
          type: object
          required:
            - success_code
            - success_message
            - request_id
          properties:
            success_code:
              type: integer
              enum:
                - 200
              description: HTTP status code equivalent
            success_message:
              type: string
              description: Success message
            request_id:
              type: string
              format: uuid
              description: Unique identifier for the request
      closeFrame:
        payload:
          type: object
          description: >
            When Deepgram encounters an error during streaming speech to text, a
            WebSocket Close frame is sent. The frame contains a status code and
            UTF-8-encoded payload describing the error reason
          required:
            - code
            - payload
          properties:
            code:
              type: integer
              enum:
                - 1000
                - 1008
                - 1011
              description: WebSocket close status code
            payload:
              type: string
              enum:
                - None
                - DATA-0000
                - NET-0000
                - NET-0001
              description: Error reason code
          examples:
            - code: 1000
              payload: None
              description: Normal closure
            - code: 1008
              payload: DATA-0000
              description: The payload cannot be decoded as audio
            - code: 1011
              payload: NET-0000
              description: Internal server error
            - code: 1011
              payload: NET-0001
              description: Failed to receive message
  agent:
    address: /agent
    description: Deepgram Voice Agent WebSocket
    parameters:
      ApiKey:
        description: >-
          API key for authentication. Format should be 'token
          <DEEPGRAM_API_KEY>'
        location: $message.header#/Authorization
        examples:
          - token YOUR_DEEPGRAM_API_KEY
    messages:
      settingsConfiguration:
        contentType: application/json
        payload:
          type: object
          description: >-
            Configure the voice agent and sets the input and output audio
            formats
          required:
            - type
            - agent
            - think
          properties:
            type:
              type: string
              const: SettingsConfiguration
            audio:
              type: object
              nullable: true
              description: Optional audio configuration settings
              properties:
                input:
                  type: object
                  nullable: true
                  description: Optional audio input configuration settings
                  properties:
                    encoding:
                      type: string
                      default: linear16
                      description: Audio encoding format
                    sample_rate:
                      type: integer
                      default: 24000
                      description: Sample rate in Hz
                output:
                  type: object
                  nullable: true
                  description: Audio output configuration settings
                  properties:
                    encoding:
                      type: string
                    sample_rate:
                      type: integer
                      default: 24000
                      description: Sample rate in Hz
                    bitrate:
                      type: integer
                    container:
                      type: string
            agent:
              type: object
              properties:
                listen:
                  type: object
                  properties:
                    model:
                      type: string
                      default: nova-2
                      description: Model to use for speech recognition
                think:
                  type: object
                  properties:
                    provider:
                      type: object
                      properties:
                        type:
                          type: string
                          description: LLM provider type
                    model:
                      type: string
                      description: LLM model to use
                    instructions:
                      type: string
                      nullable: true
                      description: LLM System prompt
                    functions:
                      type: array
                      nullable: true
                      items:
                        type: object
                        properties:
                          name:
                            type: string
                            description: Function name
                          description:
                            type: string
                            description: Description of function purpose and usage
                          url:
                            type: string
                            description: Function endpoint URL
                          headers:
                            type: array
                            items:
                              type: object
                              properties:
                                key:
                                  type: string
                                value:
                                  type: string
                          method:
                            type: string
                            default: post
                            description: HTTP method for function call
                          parameters:
                            type: object
                            properties:
                              type:
                                type: string
                              properties:
                                type: object
                                additionalProperties:
                                  type: object
                                  properties:
                                    type:
                                      type: string
                                    description:
                                      type: string
                              required:
                                type: array
                                items:
                                  type: string
                speak:
                  type: object
                  nullable: true
                  properties:
                    model:
                      type: string
                      default: aura-asteria-en
                      description: Text-to-speech model
                    provider:
                      type: string
                      enum:
                        - eleven_labs
                        - cartesia
                      description: Alternative TTS provider
                    voice_id:
                      type: string
                      description: Unique voice identifier for the selected provider
            context:
              type: object
              nullable: true
              properties:
                messages:
                  type: array
                  description: LLM message history for conversation restoration
                  items:
                    type: object
                replay:
                  type: boolean
                  default: false
                  description: Whether to replay the last assistant message
        examples:
          - payload:
              type: SettingsConfiguration
              audio:
                input:
                  encoding: linear16
                  sample_rate: 24000
                output:
                  encoding: mp3
                  sample_rate: 24000
                  bitrate: 48000
                  container: none
              agent:
                listen:
                  model: nova-2
                think:
                  provider:
                    type: openai
                  model: gpt-4
                  instructions: You are a helpful AI assistant focused on customer service.
                  functions:
                    - name: check_order_status
                      description: Check the status of a customer order
                      url: https://api.example.com/orders/status
                      headers:
                        - key: authorization
                          value: Bearer {{token}}
                      method: post
                      parameters:
                        type: object
                        properties:
                          order_id:
                            type: string
                            description: The order ID to check
                        required:
                          - order_id
                speak:
                  model: aura-asteria-en
                  provider: eleven_labs
                  voice_id: bIHbv24MWmeRgasZH58o
              context:
                messages: []
                replay: false
      updateInstructions:
        contentType: application/json
        payload:
          type: object
          description: >-
            Send a message to give additional instructions to the Think model in
            the middle of a conversation
          required:
            - type
            - instructions
          properties:
            type:
              type: string
              const: UpdateInstructions
              description: Message type identifier
            instructions:
              type: string
              description: The new instructions to give to the Think model
        examples:
          - payload:
              type: UpdateInstructions
              instructions: >-
                You are a helpful AI assistant. Your role is to help users with
                their questions and tasks. Please be polite, professional, and
                thorough in your responses. If you're unsure about something,
                it's okay to say so. Focus on providing accurate and useful
                information.
      updateSpeak:
        contentType: application/json
        payload:
          type: object
          description: >-
            Send a message to change the Speak model in the middle of a
            conversation
          required:
            - type
            - model
          properties:
            type:
              type: string
              const: UpdateSpeak
              description: Message type identifier for updating the speak model
            model:
              type: string
              description: The new Text-to-Speech model to use
        examples:
          - payload:
              type: UpdateSpeak
              model: aura-asteria-en
      injectAgentMessage:
        contentType: application/json
        payload:
          type: object
          description: >-
            Send a message to change the Speak model in the middle of a
            conversation
          required:
            - type
            - message
          properties:
            type:
              type: string
              const: InjectAgentMessage
              description: Message type identifier for injecting an agent message
            message:
              type: string
              description: The statement that the agent should say
        examples:
          - payload:
              type: InjectAgentMessage
              message: >-
                I apologize, but I need to correct my previous statement. Let me
                provide you with the accurate information.
      injectionRefused:
        contentType: application/json
        payload:
          type: object
          description: Receive injection refused message
          required:
            - type
            - message
          properties:
            type:
              type: string
              const: InjectionRefused
              description: Message type identifier for injection refused
        examples:
          - payload:
              type: InjectionRefused
      functionCallResponse:
        contentType: application/json
        payload:
          type: object
          description: Configure the voice agent and configure the function call response
          required:
            - type
            - function_call_id
            - output
          properties:
            type:
              type: string
              const: FunctionCallResponse
              description: Message type identifier for function call responses
            function_call_id:
              type: string
              description: >-
                The unique identifier matching the original function call
                request
            output:
              type: string
              description: The result of the function call execution
        examples:
          - payload:
              type: FunctionCallResponse
              function_call_id: fc_12345678-90ab-cdef-1234-567890abcdef
              output: >-
                Order #123456 status: Shipped - Expected delivery date:
                2024-03-15
      agentKeepAlive:
        contentType: application/json
        payload:
          type: object
          description: Send messages ensuring uninterrupted communication for your agent
          required:
            - type
          properties:
            type:
              type: string
              const: KeepAlive
              description: Message type identifier for agent keep alive signal
        examples:
          - payload:
              type: KeepAlive
      welcomeMessage:
        contentType: application/json
        payload:
          type: object
          description: >-
            Receive a welcome message from the server to confirm the websocket
            has opened
          required:
            - type
            - session_id
          properties:
            type:
              type: string
              const: Welcome
              description: Message type identifier for welcome message
            session_id:
              type: string
              format: uuid
              description: Unique identifier for the websocket session
        examples:
          - payload:
              type: Welcome
              session_id: fc553ec9-5874-49ca-a47c-b670d525a4b1
      settingsApplied:
        contentType: application/json
        payload:
          type: object
          description: >-
            Confirm the server has successfully received and applied the
            Settings Configuration message
          required:
            - type
          properties:
            type:
              type: string
              const: SettingsApplied
              description: Message type identifier for settings applied confirmation
        examples:
          - payload:
              type: SettingsApplied
      ConversationText:
        contentType: application/json
        payload:
          type: object
          description: >-
            Conversation Text facilitates real-time communication by relaying
            spoken statements from both the user and the assistant
          required:
            - type
            - role
            - content
          properties:
            type:
              type: string
              const: ConversationText
              description: Message type identifier for conversation text
            role:
              type: string
              enum:
                - user
                - assistant
              description: Identifies who spoke the statement
            content:
              type: string
              description: The actual statement that was spoken
        examples:
          - payload:
              type: ConversationText
              role: user
              content: What's the weather like today?
          - payload:
              type: ConversationText
              role: assistant
              content: >-
                Based on the current data, it's sunny with a temperature of 72°F
                (22°C). The forecast shows clear skies throughout the day.
      userStartedSpeaking:
        contentType: application/json
        payload:
          type: object
          description: >-
            User Started Speaking notifies the client that the user has begun
            speaking
          required:
            - type
          properties:
            type:
              type: string
              const: UserStartedSpeaking
              description: >-
                Message type identifier indicating that the user has begun
                speaking
        examples:
          - payload:
              type: UserStartedSpeaking
      agentThinking:
        contentType: application/json
        payload:
          type: object
          description: >-
            Agent Thinking informs the client when the agent is processing
            information
          required:
            - type
            - content
          properties:
            type:
              type: string
              const: AgentThinking
              description: Message type identifier for agent thinking
            content:
              type: string
              description: The text of the agent's thought process
        examples:
          - payload:
              type: AgentThinking
              content: >-
                Analyzing the user's request and preparing a comprehensive
                response about weather patterns.
      functionCallRequest:
        contentType: application/json
        payload:
          type: object
          description: >-
            Request to call a function by sending a Function Call Request
            message
          required:
            - type
            - function_name
            - function_call_id
            - input
          properties:
            type:
              type: string
              const: FunctionCallRequest
              description: Message type identifier for function call requests
            function_name:
              type: string
              description: The name specified in the function definition
            function_call_id:
              type: string
              description: Unique identifier to correlate the response with this request
            input:
              type: object
              description: Parameters defined for this function in the function definition
        examples:
          - payload:
              type: FunctionCallRequest
              function_name: check_order_status
              function_call_id: fc_12345678-90ab-cdef-1234-567890abcdef
              input:
                order_id: ORD-123456
      functionCalling:
        contentType: application/json
        payload:
          type: object
          description: >-
            Provides insights into function call workflows to assist in
            debugging
          required:
            - type
          properties:
            type:
              type: string
              const: FunctionCalling
              description: Message type identifier for function calling status
        examples:
          - payload:
              type: FunctionCalling
      agentStartedSpeaking:
        contentType: application/json
        payload:
          type: object
          description: >-
            Get notified when the server begins streaming an agent's audio
            response for playback
          required:
            - type
            - total_latency
            - tts_latency
            - ttt_latency
          properties:
            type:
              type: string
              const: AgentStartedSpeaking
              description: Message type identifier for agent started speaking
            total_latency:
              type: number
              format: float
              description: >-
                Seconds from receiving the user's utterance to producing the
                agent's reply
            tts_latency:
              type: number
              format: float
              description: The portion of total latency attributable to text-to-speech
            ttt_latency:
              type: number
              format: float
              description: >-
                The portion of total latency attributable to text-to-text
                (usually an LLM)
        examples:
          - payload:
              type: AgentStartedSpeaking
              total_latency: 2.5
              tts_latency: 0.8
              ttt_latency: 1.7
      agentAudioDone:
        contentType: application/json
        payload:
          type: object
          description: >-
            Get signals that the server has finished sending the final audio
            segment to the client
          required:
            - type
          properties:
            type:
              type: string
              const: AgentAudioDone
              description: >-
                Message type identifier indicating the agent has finished
                sending audio
        examples:
          - payload:
              type: AgentAudioDone
      agentErrorResponse:
        contentType: application/json
        payload:
          type: object
          description: Receive an error message from the server when an error occurs
          required:
            - type
            - message
          properties:
            type:
              type: string
              const: Error
              description: Message type identifier for error responses
            message:
              type: string
              description: A description of what went wrong
        examples:
          - payload:
              type: Error
              message: 'Failed to process audio input: Invalid audio format'
operations:
  sendText:
    description: Send text to Deepgram's Text to Speech API
    action: send
    channel:
      $ref: '#/channels/speak'
    messages:
      - $ref: '#/channels/speak/messages/textToSpeechRequest'
  sendSpeakControlMessage:
    action: send
    description: Send control messages to Deepgram's Text to Speech API
    channel:
      $ref: '#/channels/speak'
    messages:
      - $ref: '#/channels/speak/messages/controlMessagesRequest'
  receiveAudio:
    description: Receive audio from Deepgram's Text to Speech API
    action: receive
    channel:
      $ref: '#/channels/speak'
    messages:
      - $ref: '#/channels/speak/messages/textToSpeechResponse'
  receiveSpeakControlResponse:
    description: Receive control messages from Deepgram's Text to Speech API
    action: receive
    channel:
      $ref: '#/channels/speak'
    messages:
      - $ref: '#/channels/speak/messages/controlMessagesResponse'
  sendAudio:
    description: Send audio to Deepgram's Speech to Text API
    action: send
    channel:
      $ref: '#/channels/listen'
    messages:
      - $ref: '#/channels/listen/messages/transcriptionRequest'
  sendListenControlMessage:
    description: Send control messages to Deepgram's Speech to Text API
    action: send
    channel:
      $ref: '#/channels/listen'
    messages:
      - $ref: '#/channels/listen/messages/controlMessagesRequest'
  receiveTranscription:
    description: Receive transcription from Deepgram's Speech to Text API
    action: receive
    channel:
      $ref: '#/channels/listen'
    messages:
      - $ref: '#/channels/listen/messages/transcriptionResponse'
  receiveListenControlResponse:
    description: Receive control messages from Deepgram's Speech to Text API
    action: receive
    channel:
      $ref: '#/channels/listen'
    messages:
      - $ref: '#/channels/listen/messages/controlMessageResponse'
  sendSettingsConfiguration:
    description: Send settings configuration to Deepgram's Voice Agent API
    action: send
    channel:
      $ref: '#/channels/agent'
    messages:
      - $ref: '#/channels/agent/messages/settingsConfiguration'
  sendUpdateInstructions:
    description: Send update instructions to Deepgram's Voice Agent API
    action: send
    channel:
      $ref: '#/channels/agent'
    messages:
      - $ref: '#/channels/agent/messages/updateInstructions'
  sendUpdateSpeak:
    description: Send update speak to Deepgram's Voice Agent API
    action: send
    channel:
      $ref: '#/channels/agent'
    messages:
      - $ref: '#/channels/agent/messages/updateSpeak'
  sendInjectAgentMessage:
    action: send
    description: Send inject agent message to Deepgram's Voice Agent API
    channel:
      $ref: '#/channels/agent'
    messages:
      - $ref: '#/channels/agent/messages/injectAgentMessage'
  receiveInjectionRefused:
    description: Receive injection refused message from Deepgram's Voice Agent API
    action: receive
    channel:
      $ref: '#/channels/agent'
    messages:
      - $ref: '#/channels/agent/messages/injectionRefused'
  sendFunctionCallResponse:
    description: Send function call response to Deepgram's Voice Agent API
    action: send
    channel:
      $ref: '#/channels/agent'
    messages:
      - $ref: '#/channels/agent/messages/functionCallResponse'
  sendKeepAlive:
    description: Send keep alive to Deepgram's Voice Agent API
    action: send
    channel:
      $ref: '#/channels/agent'
    messages:
      - $ref: '#/channels/agent/messages/agentKeepAlive'
  receiveWelcome:
    description: Receive welcome message from Deepgram's Voice Agent API
    action: receive
    channel:
      $ref: '#/channels/agent'
    messages:
      - $ref: '#/channels/agent/messages/welcomeMessage'
  receiveSettingsApplied:
    description: Receive settings applied message from Deepgram's Voice Agent API
    action: receive
    channel:
      $ref: '#/channels/agent'
    messages:
      - $ref: '#/channels/agent/messages/settingsApplied'
  receiveConversationText:
    description: Receive conversation text from Deepgram's Voice Agent API
    action: receive
    channel:
      $ref: '#/channels/agent'
    messages:
      - $ref: '#/channels/agent/messages/ConversationText'
  receiveUserStartedSpeaking:
    description: Receive user started speaking message from Deepgram's Voice Agent API
    action: receive
    channel:
      $ref: '#/channels/agent'
    messages:
      - $ref: '#/channels/agent/messages/userStartedSpeaking'
  receiveAgentThinking:
    description: Receive agent thinking message from Deepgram's Voice Agent API
    action: receive
    channel:
      $ref: '#/channels/agent'
    messages:
      - $ref: '#/channels/agent/messages/agentThinking'
  receiveFunctionCallRequest:
    description: Receive function call request from Deepgram's Voice Agent API
    action: receive
    channel:
      $ref: '#/channels/agent'
    messages:
      - $ref: '#/channels/agent/messages/functionCallRequest'
  receiveFunctionCalling:
    description: Receive function calling message from Deepgram's Voice Agent API
    action: receive
    channel:
      $ref: '#/channels/agent'
    messages:
      - $ref: '#/channels/agent/messages/functionCalling'
  receiveAgentStartedSpeaking:
    description: Receive agent started speaking message from Deepgram's Voice Agent API
    action: receive
    channel:
      $ref: '#/channels/agent'
    messages:
      - $ref: '#/channels/agent/messages/agentStartedSpeaking'
  receiveAgentAudioDone:
    description: Receive agent audio done message from Deepgram's Voice Agent API
    action: receive
    channel:
      $ref: '#/channels/agent'
    messages:
      - $ref: '#/channels/agent/messages/agentAudioDone'
  receiveError:
    description: Receive error response from Deepgram's Voice Agent API
    action: receive
    channel:
      $ref: '#/channels/agent'
    messages:
      - $ref: '#/channels/agent/messages/agentErrorResponse'
components:
  parameters:
    ApiKey:
      description: API key for authentication. Format should be 'token <DEEPGRAM_API_KEY>'
      location: $message.header#/Authorization
      examples:
        - token YOUR_DEEPGRAM_API_KEY