Audio Keep Alive

Send keep alive messages while streaming audio to keep the connection open.
Streaming:Nova

Use the KeepAlive message to keep your WebSocket connection open during periods of silence, preventing timeouts and optimizing costs.

Purpose

Send a KeepAlive message every 3-5 seconds to prevent the 10-second timeout that triggers a NET-0001 error and closes the connection. Ensure the message is sent as a text WebSocket frame—sending it as binary may result in incorrect handling and potential connection issues.

Example Payloads

To send the KeepAlive message, send the following JSON message to the server:

JSON
{
"type": "KeepAlive"
}

The server will not send a response back when you send a KeepAlive message. If no audio data or KeepAlive messages are sent within a 10-second window, the connection will close with a NET-0001 error.

Language Specific Implementations

Below are code examples to help you get started using KeepAlive.

Sending a KeepAlive message in JSON Format

Construct a JSON message containing the KeepAlive type and send it over the WebSocket connection in each respective language.

const WebSocket = require("ws");
// Assuming 'headers' is already defined for authorization
const ws = new WebSocket("wss://api.deepgram.com/v1/listen", { headers });
// Assuming 'ws' is the WebSocket connection object
const keepAliveMsg = JSON.stringify({ type: "KeepAlive" });
ws.send(keepAliveMsg);

Streaming Examples

Make a streaming request and use KeepAlive to keep the connection open.

const WebSocket = require("ws");
const authToken = "DEEPGRAM_API_KEY"; // Replace 'DEEPGRAM_API_KEY' with your actual authorization token
const headers = {
Authorization: `Token ${authToken}`,
};
// Initialize WebSocket connection
const ws = new WebSocket("wss://api.deepgram.com/v1/listen", { headers });
// Handle WebSocket connection open event
ws.on("open", function open() {
console.log("WebSocket connection established.");
// Send audio data (replace this with your audio streaming logic)
// Example: Read audio from a microphone and send it over the WebSocket
// For demonstration purposes, we're just sending a KeepAlive message
setInterval(() => {
const keepAliveMsg = JSON.stringify({ type: "KeepAlive" });
ws.send(keepAliveMsg);
console.log("Sent KeepAlive message");
}, 3000); // Sending KeepAlive messages every 3 seconds
});
// Handle WebSocket message event
ws.on("message", function incoming(data) {
console.log("Received:", data);
// Handle received data (transcription results, errors, etc.)
});
// Handle WebSocket close event
ws.on("close", function close() {
console.log("WebSocket connection closed.");
});
// Handle WebSocket error event
ws.on("error", function error(err) {
console.error("WebSocket error:", err.message);
});
// Gracefully close the WebSocket connection when done
function closeWebSocket() {
const closeMsg = JSON.stringify({ type: "CloseStream" });
ws.send(closeMsg);
}
// Call closeWebSocket function when you're finished streaming audio
// For example, when user stops recording or when the application exits
// closeWebSocket();

Using Deepgram SDKs

Deepgram’s SDKs make it easier to build with Deepgram in your preferred language. For more information on using Deepgram SDKs, refer to the SDKs documentation in the GitHub Repository.

const { DeepgramClient } = require("@deepgram/sdk");
const live = async () => {
const deepgram = new DeepgramClient({ apiKey: "DEEPGRAM_API_KEY" });
let connection;
let keepAlive;
const setupDeepgram = async () => {
connection = await deepgram.listen.v1.connect({
model: "nova-3",
utterance_end_ms: "1500",
interim_results: "true",
});
if (keepAlive) clearInterval(keepAlive);
keepAlive = setInterval(() => {
console.log("KeepAlive sent.");
connection.sendKeepAlive({ type: "KeepAlive" });
}, 3000); // Sending KeepAlive messages every 3 seconds
connection.on("open", () => {
console.log("Connection opened.");
});
connection.on("close", () => {
console.log("Connection closed.");
clearInterval(keepAlive);
});
connection.on("message", (data) => {
if (data.type === "Metadata") {
console.log(data);
} else if (data.type === "Results") {
console.log(data.channel);
} else if (data.type === "UtteranceEnd") {
console.log(data);
} else if (data.type === "SpeechStarted") {
console.log(data);
}
});
connection.on("error", (err) => {
console.error(err);
});
connection.connect();
await connection.waitForOpen();
};
setupDeepgram();
};
live();

Word Timings

Word timings in streaming transcription results are based on the audio stream itself, not the lifetime of the WebSocket connection. If you send KeepAlive messages without any audio payloads for a period of time, then resume sending audio, the timestamps will continue from where the audio left off—not from when the KeepAlive messages were sent.

Here is an example timeline demonstrating the behavior.

EventWall TimeWord Timing Range on Results Response
Websocket opened, begin sending audio payloads0 seconds0 seconds
Results received5 seconds0-5 seconds
Results received10 seconds5-10 seconds
Pause sending audio payloads, while sending KeepAlive messages10 secondsn/a
Resume sending audio payloads30 secondsn/a
Results received35 seconds10-15 seconds