Using Deepgram Conversational STT / Flux (JavaScript / TypeScript SDK)
Turn-aware streaming STT via /v2/listen for conversational audio and explicit turn events.
When to use this product
- You need turn-aware transcription, not just a word stream.
- You want Flux-style events like
TurnInfo and Connected.
- You are building a conversational interface but do not want the full Voice Agent runtime.
Use a different skill when:
- You want general v1 transcription or prerecorded REST →
deepgram-js-speech-to-text.
- You want a hosted assistant with think + speak built in →
deepgram-js-voice-agent.
- You want analytics overlays like sentiment and summaries →
deepgram-js-audio-intelligence.
Authentication
require("dotenv").config();
const { DeepgramClient } = require("@deepgram/sdk");
const deepgramClient = new DeepgramClient({
apiKey: process.env.DEEPGRAM_API_KEY,
});
Quick start
From examples/26-transcription-live-websocket-v2.ts:
const deepgramConnection = await deepgramClient.listen.v2.createConnection({
model: "flux-general-en",
});
deepgramConnection.on("message", (data) => {
if (data.type === "Connected") {
console.log("Connected:", data);
} else if (data.type === "TurnInfo") {
console.log("Turn Info:", data);
} else if (data.type === "FatalError") {
deepgramConnection.close();
}
});
deepgramConnection.connect();
await deepgramConnection.waitForOpen();
// Swap this for a live mic capture in real apps; the repo example uses
// `createReadStream` over a sample file.
const { createReadStream } = require("node:fs");
const audioStream = createReadStream("samples/spacewalk.wav");
audioStream.on("data", (chunk) => {
deepgramConnection.sendMedia(chunk);
});
audioStream.on("end", () => {
deepgramConnection.sendCloseStream({ type: "CloseStream" });
});
Key parameters / API surface
- Connect args from
src/api/resources/listen/resources/v2/client/Client.ts: model, encoding, sample_rate, eager_eot_threshold, eot_threshold, eot_timeout_ms, keyterm, tag, mip_opt_out.
- Socket methods from
src/api/resources/listen/resources/v2/client/Socket.ts: sendMedia(...), sendCloseStream(...), sendListenV2Configure(...), waitForOpen().
- Custom wrapper additions from
src/CustomClient.ts: createConnection(...) alias and Node-only ping(...) helper.
Limitations
- The current generated
ListenV2Model type only exposes "flux-general-en".
- Product docs mention broader Flux capabilities, but
flux-general-multi / language_hint are not surfaced in this repo's generated types today.
API reference (layered)
- In-repo reference:
reference.md does not currently document listen.v2; use src/CustomClient.ts and src/api/resources/listen/resources/v2/client/{Client,Socket}.ts as the in-repo source of truth.
- Canonical OpenAPI (REST): https://developers.deepgram.com/openapi.yaml
- Canonical AsyncAPI (WSS): https://developers.deepgram.com/asyncapi.yaml
- Context7: library ID
/llmstxt/developers_deepgram_llms_txt
- Product docs:
Gotchas
- There is no REST path here. This skill is
/v2/listen WebSocket only.
- Current repo typing only allows
flux-general-en. Treat multilingual Flux support as a product capability not yet reflected in this SDK surface.
- Close with
sendCloseStream, not sendFinalize. Finalize is the v1 pattern.
ping() is Node-only. src/CustomClient.ts throws in browsers because browser WS ping frames are not user-exposed.
createConnection() is lazy. Call connect() after registering handlers.
- The example explicitly warns about access/availability. A 400 may mean your account or endpoint is not enabled yet, not that your socket code is wrong.
- Omit
encoding for containerized audio. Keep it for raw PCM/Opus streams.
Example files in this repo
examples/26-transcription-live-websocket-v2.ts
examples/27-deepgram-session-header.ts
Central product skills
For cross-language Deepgram product knowledge — the consolidated API reference, documentation finder, focused runnable recipes, third-party integration examples, and MCP setup — install the central skills:
npx skills add deepgram/skills
This SDK ships language-idiomatic code skills; deepgram/skills ships cross-language product knowledge (see api, docs, recipes, examples, starters, setup-mcp).
1---2name: deepgram-js-conversational-stt3description: Use when writing or reviewing JavaScript/TypeScript in this repo that calls Deepgram Conversational STT v2 / Flux (`/v2/listen`) for turn-aware streaming transcription. Covers `client.listen.v2.createConnection()` / `connect()`, Flux models, and turn events like `TurnInfo`. Use `deepgram-js-speech-to-text` for standard v1 ASR and `deepgram-js-voice-agent` for full-duplex assistants. Triggers include "flux", "v2 listen", "conversational STT", "turn detection", "end of turn", "EOT", and "listen.v2".4metadata:5 source: https://skillmd.com/skills/deepgram/deepgram-js-conversational-stt6---78# Using Deepgram Conversational STT / Flux (JavaScript / TypeScript SDK)910Turn-aware streaming STT via `/v2/listen` for conversational audio and explicit turn events.1112## When to use this product1314- You need **turn-aware** transcription, not just a word stream.15- You want Flux-style events like `TurnInfo` and `Connected`.16- You are building a conversational interface but do **not** want the full Voice Agent runtime.1718**Use a different skill when:**19- You want general v1 transcription or prerecorded REST → `deepgram-js-speech-to-text`.20- You want a hosted assistant with think + speak built in → `deepgram-js-voice-agent`.21- You want analytics overlays like sentiment and summaries → `deepgram-js-audio-intelligence`.2223## Authentication2425```js26require("dotenv").config();2728const { DeepgramClient } = require("@deepgram/sdk");2930const deepgramClient = new DeepgramClient({31 apiKey: process.env.DEEPGRAM_API_KEY,32});33```3435## Quick start3637From `examples/26-transcription-live-websocket-v2.ts`:3839```js40const deepgramConnection = await deepgramClient.listen.v2.createConnection({41 model: "flux-general-en",42});4344deepgramConnection.on("message", (data) => {45 if (data.type === "Connected") {46 console.log("Connected:", data);47 } else if (data.type === "TurnInfo") {48 console.log("Turn Info:", data);49 } else if (data.type === "FatalError") {50 deepgramConnection.close();51 }52});5354deepgramConnection.connect();55await deepgramConnection.waitForOpen();5657// Swap this for a live mic capture in real apps; the repo example uses58// `createReadStream` over a sample file.59const { createReadStream } = require("node:fs");60const audioStream = createReadStream("samples/spacewalk.wav");6162audioStream.on("data", (chunk) => {63 deepgramConnection.sendMedia(chunk);64});6566audioStream.on("end", () => {67 deepgramConnection.sendCloseStream({ type: "CloseStream" });68});69```7071## Key parameters / API surface7273- Connect args from `src/api/resources/listen/resources/v2/client/Client.ts`: `model`, `encoding`, `sample_rate`, `eager_eot_threshold`, `eot_threshold`, `eot_timeout_ms`, `keyterm`, `tag`, `mip_opt_out`.74- Socket methods from `src/api/resources/listen/resources/v2/client/Socket.ts`: `sendMedia(...)`, `sendCloseStream(...)`, `sendListenV2Configure(...)`, `waitForOpen()`.75- Custom wrapper additions from `src/CustomClient.ts`: `createConnection(...)` alias and Node-only `ping(...)` helper.7677## Limitations7879- The current generated `ListenV2Model` type only exposes `"flux-general-en"`.80- Product docs mention broader Flux capabilities, but `flux-general-multi` / `language_hint` are **not** surfaced in this repo's generated types today.8182## API reference (layered)83841. **In-repo reference**: `reference.md` does not currently document `listen.v2`; use `src/CustomClient.ts` and `src/api/resources/listen/resources/v2/client/{Client,Socket}.ts` as the in-repo source of truth.852. **Canonical OpenAPI (REST)**: https://developers.deepgram.com/openapi.yaml863. **Canonical AsyncAPI (WSS)**: https://developers.deepgram.com/asyncapi.yaml874. **Context7**: library ID `/llmstxt/developers_deepgram_llms_txt`885. **Product docs**:89 - https://developers.deepgram.com/reference/speech-to-text/listen-flux90 - https://developers.deepgram.com/docs/flux/quickstart91 - https://developers.deepgram.com/docs/flux/language-prompting9293## Gotchas94951. **There is no REST path here.** This skill is `/v2/listen` WebSocket only.962. **Current repo typing only allows `flux-general-en`.** Treat multilingual Flux support as a product capability not yet reflected in this SDK surface.973. **Close with `sendCloseStream`, not `sendFinalize`.** Finalize is the v1 pattern.984. **`ping()` is Node-only.** `src/CustomClient.ts` throws in browsers because browser WS ping frames are not user-exposed.995. **`createConnection()` is lazy.** Call `connect()` after registering handlers.1006. **The example explicitly warns about access/availability.** A 400 may mean your account or endpoint is not enabled yet, not that your socket code is wrong.1017. **Omit `encoding` for containerized audio.** Keep it for raw PCM/Opus streams.102103## Example files in this repo104105- `examples/26-transcription-live-websocket-v2.ts`106- `examples/27-deepgram-session-header.ts`107108## Central product skills109110For cross-language Deepgram product knowledge — the consolidated API reference, documentation finder, focused runnable recipes, third-party integration examples, and MCP setup — install the central skills:111112```bash113npx skills add deepgram/skills114```115116This SDK ships language-idiomatic code skills; `deepgram/skills` ships cross-language product knowledge (see `api`, `docs`, `recipes`, `examples`, `starters`, `setup-mcp`).