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

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.

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

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

data object

data.deepgram object

data.deepgram.channel object

data.deepgram.channel.alternatives[] object

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

data.deepgram.metadata object

data.deepgram.metadata.model_info object

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

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