The Speech To Text API

Introduction

The Speech To Text API provides allows your extension to listen in to the speech to text events generated by the Voxtop phone during active phone calls.

The current version of our speech API uses Deepgram Nova3. The response from the model will be included without alteration.

Connecting to the Speech To Text API

The speech API is available at:

window.voxtopAPI.speech

Speech API - Functions

Functions	Purpose
installConfig(config)	Allows you to install one or more configs for the Voxtop Speech to text engine

Function: voxtopAPI.speech.installConfig(config)

The config object is specified in the Speech To Text Config Guide.

Voxtop will automatically add the installationId for the extension as a property of the config.

More information about the Speech To Text Config Options

Example Usage

function installConfig() {
    if (!window.voxtopAPI) {
        console.warn('voxtopAPI not available, skipping config installation')
        return
    }

    window.voxtopAPI.speech.installConfig({         
        configId: 'test',
        editable: false,
        deletable: false,
        displayText: "Your Config",             
        interim_results: false,
        endpointing: "10",
        language: "en-GB",
        detect_language: false,
        punctuate: true,
        smart_format: true,
        numerals: true,
        measurements: true,
        filler_words: true,
        profanity_filter: true,     
        detect_entities: false,
        diarize: false,
        dictation: false,
        mode: "general",        
        search: [],
        replace: [],
        redact: [],
        keyterm: [],                    
    })
}

Speech To Text API - Events

Subscribing

As with all of the voxtopAPI events you subscribe using the onEvent function and pass a callback function to process messages.

    const unsubscribeSpeechEvents = window.voxtopAPI.speech.onEvent(callback)

Unsubscribing

To unsubscribe from receiving events, simply run the function return from the onEvent function call.

unsubscribeSpeechEvents();

Example Usage

    const processMessages = (event) => {
        console.log('Received speech event:', event)
    }

    const unsubscribeSpeechEvents = window.voxtopAPI.speech.onEvent(processMessages)

Speech To Text Event Messages

The following events describe speech-to-text lifecycle activity, including when transcription starts, when transcript messages are received, when the speech-to-text connection closes, and when speech-to-text fails.

createdAt is formatted as an ISO 8601 UTC timestamp.

direction relates to either the 'local' or 'remote' channel. Local is always that of the Voxtop user. Both audio channels are sent to Deeprgam as separate streams.

source specifies where the messages eminate from. Current values include 'voxtop-phone' for audio sourced from the Voxtop phone. 'voxtop-microphone' for audio coming from the user when in dictation style mode.

Required is based on the provided examples. Fields marked Conditional appear only for some speech-to-text event scenarios.

Event Type	Purpose
speech.speechToText.started	Sent when speech-to-text starts for one side of a call
speech.speechToText.message	Sent when a speech-to-text transcript message is received
speech.speechToText.closed	Sent when a speech-to-text connection or session is closed
speech.speechToText.failed	Sent when speech-to-text fails

`speech.speechToText.started`

Emitted when speech-to-text starts for one side of a call.

{
  "eventId": "51dd95f4-47a7-4c31-9f2f-81253445c841",
  "createdAt": "2026-07-03T16:43:40.924Z",
  "source": "voxtop-phone",
  "callRef": "f10477e1-edae-463b-9d2e-2661814f53dc",
  "direction": "local",
  "callDirection": "outgoing",
  "connectionId": "8f1fa31a-2389-4412-9fa3-1a23892412ea",
  "deviceRegistrationUUID": "8f1fa31a-2389-4412-9fa3-1a23892412ea",
  "virtualDeviceRegistrationUUID": "e4971753-daca-4c9f-9717-53daca1c9f51",
  "eventType": "speech.speechToText.started"
}

Properties

Property	Type	Required	Description
`eventId`	string	Yes	Unique identifier for this event message.
`createdAt`	string	Yes	Time the event occurred, formatted as an ISO 8601 UTC timestamp.
`source`	string	Yes	Source system that generated the event. Example value is `voxtop-phone`.
`callRef`	string	Yes	Unique reference for the call. This value can be used to correlate speech-to-text events with call events for the same call.
`direction`	string	Yes	Side of the call that speech-to-text applies to. Values are `local` and `remote`.
`callDirection`	string	Yes	Direction of the call. Values are `incoming` and `outgoing`.
`connectionId`	string	Yes	Unique identifier for the phone connection.
`deviceRegistrationUUID`	string	Yes	Unique identifier for the registered phone device.
`virtualDeviceRegistrationUUID`	string	Yes	Unique identifier for the virtual device registration associated with the call.
`eventType`	string	Yes	Name of the event. For this message, the value is `speech.speechToText.started`.

`speech.speechToText.message`

Emitted when a speech-to-text transcript message is received.

{
  "eventId": "dcc617d1-59b7-40f9-a025-a802d80605b1",
  "createdAt": "2026-07-03T16:43:45.889Z",
  "source": "voxtop-phone",
  "callRef": "f10477e1-edae-463b-9d2e-2661814f53dc",
  "direction": "remote",
  "callDirection": "outgoing",
  "connectionId": "8f1fa31a-2389-4412-9fa3-1a23892412ea",
  "deviceRegistrationUUID": "8f1fa31a-2389-4412-9fa3-1a23892412ea",
  "virtualDeviceRegistrationUUID": "e4971753-daca-4c9f-9717-53daca1c9f51",
  "eventType": "speech.speechToText.message",
  "data": {
    "type": "transcript.final",
    "sessionId": "2c22da78-c15c-4972-bb8e-32a8cafb1245",
    "sequence": 3,
    "receivedAt": "2026-07-03T16:43:45.893Z",
    "transcript": "forty three and forty four",
    "deepgram": {
      "type": "Results",
      "channel_index": [0, 1],
      "duration": 3.4900002,
      "start": 0.89,
      "is_final": true,
      "speech_final": true,
      "channel": {
        "alternatives": [
          {
            "transcript": "forty three and forty four",
            "confidence": 0.9970703,
            "words": [
              {
                "word": "forty",
                "start": 0.89,
                "end": 1.77,
                "confidence": 0.6088867
              },
              {
                "word": "three",
                "start": 1.77,
                "end": 2.17,
                "confidence": 0.99902344
              },
              {
                "word": "and",
                "start": 2.17,
                "end": 2.9699998,
                "confidence": 0.9790039
              },
              {
                "word": "forty",
                "start": 2.9699998,
                "end": 3.69,
                "confidence": 0.9970703
              },
              {
                "word": "four",
                "start": 3.69,
                "end": 4.0099998,
                "confidence": 1
              }
            ]
          }
        ]
      },
      "metadata": {
        "request_id": "019f28dd-5308-7c80-a372-6fb81265414e",
        "model_info": {
          "name": "general-nova-3",
          "version": "2025-04-17.21547",
          "arch": "nova-3"
        },
        "model_uuid": "40bd3654-e622-47c4-a111-63a61b23bfe8"
      },
      "from_finalize": false
    },
    "isFinal": true
  }
}

Properties

Property	Type	Required	Description
`eventId`	string	Yes	Unique identifier for this event message.
`createdAt`	string	Yes	Time the event occurred, formatted as an ISO 8601 UTC timestamp.
`source`	string	Yes	Source system that generated the event. Example value is `voxtop-phone`.
`callRef`	string	Yes	Unique reference for the call. This value can be used to correlate speech-to-text events with call events for the same call.
`direction`	string	Yes	Side of the call that speech-to-text applies to. Values are `local` and `remote`.
`callDirection`	string	Yes	Direction of the call. Values are incoming and outgoing.
`connectionId`	string	Yes	Unique identifier for the phone connection.
`deviceRegistrationUUID`	string	Yes	Unique identifier for the registered phone device.
`virtualDeviceRegistrationUUID`	string	Yes	Unique identifier for the virtual device registration associated with the call.
`eventType`	string	Yes	Name of the event. For this message, the value is `speech.speechToText.message`.
`data`	object	Yes	Transcript message details, including the transcript text and provider payload.

`data` object

Property	Type	Required	Description
`data.type`	string	Yes	Type of transcript message. Values are `transcript.final` or `transcript.partial`.
`data.sessionId`	string	Yes	Unique identifier for the speech-to-text session.
`data.sequence`	number	Yes	Sequence number for the transcript message within the session.
`data.receivedAt`	string	Yes	Time the transcript message was received, formatted as an ISO 8601 UTC timestamp.
`data.transcript`	string	Yes	Final transcript text for this speech-to-text message.
`data.deepgram`	object	Yes	Raw or provider-specific Deepgram result payload for the transcript message.
`data.isFinal`	boolean	Yes	Indicates whether this transcript message is final.

`data.deepgram` object

Property	Type	Required	Description
`data.deepgram.type`	string	Yes	Deepgram message type. Value is `Results`.
`data.deepgram.channel_index`	array	Yes	Channel indexes included in the result. Example value is `[0, 1]`.
`data.deepgram.duration`	number	Yes	Duration of the result audio segment in seconds.
`data.deepgram.start`	number	Yes	Start time of the result audio segment in seconds.
`data.deepgram.is_final`	boolean	Yes	Indicates whether Deepgram considers the result final.
`data.deepgram.speech_final`	boolean	Yes	Indicates whether Deepgram considers the speech segment final.
`data.deepgram.channel`	object	Yes	Channel-level transcript result details.
`data.deepgram.metadata`	object	Yes	Metadata about the Deepgram request and model used.
`data.deepgram.from_finalize`	boolean	Yes	Indicates whether the result was produced from a finalize action.

`data.deepgram.channel` object

Property	Type	Required	Description
`data.deepgram.channel.alternatives`	array	Yes	Transcript alternatives returned for the channel.

`data.deepgram.channel.alternatives[]` object

Property	Type	Required	Description
`data.deepgram.channel.alternatives[].transcript`	string	Yes	Transcript text for this alternative.
`data.deepgram.channel.alternatives[].confidence`	number	Yes	Confidence score for this transcript alternative.
`data.deepgram.channel.alternatives[].words`	array	Yes	Word-level transcript details for this alternative.

`data.deepgram.channel.alternatives[].words[]` object

Property	Type	Required	Description
`data.deepgram.channel.alternatives[].words[].word`	string	Yes	Recognised word.
`data.deepgram.channel.alternatives[].words[].start`	number	Yes	Start time of the word in seconds.
`data.deepgram.channel.alternatives[].words[].end`	number	Yes	End time of the word in seconds.
`data.deepgram.channel.alternatives[].words[].confidence`	number	Yes	Confidence score for the recognised word.

`data.deepgram.metadata` object

Property	Type	Required	Description
`data.deepgram.metadata.request_id`	string	Yes	Unique identifier for the Deepgram request.
`data.deepgram.metadata.model_info`	object	Yes	Information about the Deepgram model used.
`data.deepgram.metadata.model_uuid`	string	Yes	Unique identifier for the Deepgram model.

`data.deepgram.metadata.model_info` object

Property	Type	Required	Description
`data.deepgram.metadata.model_info.name`	string	Yes	Name of the Deepgram model used. Example value is `general-nova-3`.
`data.deepgram.metadata.model_info.version`	string	Yes	Version of the Deepgram model used.
`data.deepgram.metadata.model_info.arch`	string	Yes	Model architecture. Example value is `nova-3`.

`speech.speechToText.closed`

Emitted when a speech-to-text connection or session is closed.

{
  "eventId": "0033ecd2-bde9-417f-b0c5-853831affbc2",
  "createdAt": "2026-07-03T16:43:48.669Z",
  "source": "voxtop-phone",
  "callRef": "f10477e1-edae-463b-9d2e-2661814f53dc",
  "direction": "remote",
  "callDirection": "outgoing",
  "connectionId": "8f1fa31a-2389-4412-9fa3-1a23892412ea",
  "deviceRegistrationUUID": "8f1fa31a-2389-4412-9fa3-1a23892412ea",
  "virtualDeviceRegistrationUUID": "e4971753-daca-4c9f-9717-53daca1c9f51",
  "eventType": "speech.speechToText.closed",
  "code": 1000,
  "reason": "Client stopped"
}

Properties

Property	Type	Required	Description
`eventId`	string	Yes	Unique identifier for this event message.
`createdAt`	string	Yes	Time the event occurred, formatted as an ISO 8601 UTC timestamp.
`source`	string	Yes	Source system that generated the event. Example value is `voxtop-phone`.
`callRef`	string	Yes	Unique reference for the call. This value can be used to correlate speech-to-text events with call events for the same call.
`direction`	string	Yes	Side of the call that speech-to-text applies to. Values are `local` and `remote`.
`callDirection`	string	Yes	Direction of the call. Values are incoming and outgoing.
`connectionId`	string	Yes	Unique identifier for the phone connection.
`deviceRegistrationUUID`	string	Yes	Unique identifier for the registered phone device.
`virtualDeviceRegistrationUUID`	string	Yes	Unique identifier for the virtual device registration associated with the call.
`eventType`	string	Yes	Name of the event. For this message, the value is `speech.speechToText.closed`.
`code`	number	Yes	Close code for the speech-to-text connection. Example value is `1000`.
`reason`	string	Yes	Human-readable reason why the speech-to-text connection was closed. Example value is `Client stopped`.

`speech.speechToText.failed`

Emitted when speech-to-text fails.

{
  "eventId": "f5e48aab-b17b-4684-96b4-4a43606ea5ac",
  "createdAt": "2026-07-03T16:49:59.345Z",
  "eventType": "speech.speechToText.failed",
  "source": "voxtop-microphone",
  "error": "[object Event]"
}

Properties

Property	Type	Required	Description
`eventId`	string	Yes	Unique identifier for this event message.
`createdAt`	string	Yes	Time the event occurred, formatted as an ISO 8601 UTC timestamp.
`eventType`	string	Yes	Name of the event. For this message, the value is `speech.speechToText.failed`.
`source`	string	Yes	Source system that generated the failure event. Example value is `voxtop-microphone`.
`error`	string	Yes	Error information associated with the speech-to-text failure. Example value is `[object Event]`.