Required dependencies

npm install ws
npm install --save-dev @types/ws

No native build steps, pod installs, or Android linking are required. This is a pure Node.js/TypeScript package.

Project setup

1. Copy the source/ directory into your project, e.g. src/deepgram/.

2. Add path aliases in tsconfig.json so your code resolves the source root cleanly:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@deepgram/sdk": ["src/deepgram/index.ts"]
    },
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "target": "ES2020",
    "esModuleInterop": true
  }
}

3. If you use a bundler (esbuild, Webpack, tsup), add the same alias there. For tsup:

// tsup.config.ts
export default { alias: { "@deepgram/sdk": "./src/deepgram/index.ts" } };

4. Set the required environment variable before running:

export DEEPGRAM_API_KEY="your_api_key_here"

5. The SDK reads process.env.DEEPGRAM_API_KEY automatically. You can also pass it explicitly to the constructor (see examples below).

Public API

DeepgramClient

import { DeepgramClient } from "@deepgram/sdk";

const client = new DeepgramClient(options?: BaseClientOptions);

The main entry point for all SDK functionality. BaseClientOptions accepts apiKey, global, and namespace fields. Use this class when you need a custom auth flow or want to inject additional headers. This is CustomDeepgramClient under the hood.

DefaultDeepgramClient

import { DefaultDeepgramClient } from "@deepgram/sdk";

const client = new DefaultDeepgramClient(options?: BaseClientOptions);

The upstream SDK's canonical client class. Use when you want the out-of-the-box Deepgram-hosted endpoint configuration without customization. Exposes .listen, .speak, .read, .agent, .manage, .auth, .selfHosted, and .voiceAgent resource namespaces.

DeepgramEnvironment

import { DeepgramEnvironment, type DeepgramEnvironmentUrls } from "@deepgram/sdk";

// Values: DeepgramEnvironment.Default, DeepgramEnvironment.SelfHosted, etc.

Enum for selecting the API base URL. Pass environment: DeepgramEnvironment.Default in BaseClientOptions to explicitly target Deepgram's cloud, or provide a DeepgramEnvironmentUrls object to point at a self-hosted deployment.

DeepgramError / DeepgramTimeoutError

import { DeepgramError, DeepgramTimeoutError } from "@deepgram/sdk";

Base error classes for all SDK failures. Catch DeepgramError for API-level problems and DeepgramTimeoutError for requests that exceeded their deadline. Both are subclasses of Error and carry a structured message.

Working examples

Scenario - Pre-recorded file transcription

Send a local audio file to Deepgram's speech-to-text API and print the transcript. The listen.v1.media.transcribeFile method accepts a ReadStream and a model options object.

import { createReadStream } from "fs";
import { DeepgramClient } from "@deepgram/sdk";

async function transcribeFile(filePath: string): Promise<void> {
  const client = new DeepgramClient({ apiKey: process.env.DEEPGRAM_API_KEY });

  const response = await client.listen.v1.media.transcribeFile(
    createReadStream(filePath),
    { model: "nova-3", punctuate: true, language: "en" }
  );

  const transcript =
    response.results.channels[0].alternatives[0].transcript;
  console.log("Transcript:", transcript);
}

transcribeFile("./audio.wav");

Scenario - Real-time streaming transcription

Open a WebSocket to Deepgram and stream raw PCM audio chunks as they arrive from a microphone or other audio source.

import { DeepgramClient, DeepgramError } from "@deepgram/sdk";

async function streamAudio(audioChunks: AsyncIterable<Buffer>): Promise<void> {
  const client = new DeepgramClient({ apiKey: process.env.DEEPGRAM_API_KEY });

  const connection = await client.listen.v1.connect({
    model: "nova-3",
    language: "en",
    punctuate: "true",
    interim_results: "true",
  });

  connection.on("open", () => console.log("WebSocket open"));

  connection.on("message", (data: unknown) => {
    const msg = data as { type: string; channel?: { alternatives: { transcript: string }[] } };
    if (msg.type === "Results") {
      console.log(msg.channel?.alternatives[0].transcript);
    }
  });

  connection.on("error", (err: Error) => {
    if (err instanceof DeepgramError) {
      console.error("Deepgram error:", err.message);
    }
  });

  connection.connect();
  await connection.waitForOpen();

  for await (const chunk of audioChunks) {
    connection.socket.send(chunk);
  }

  connection.socket.close();
}

Scenario - Text-to-speech audio generation

Convert a string of text into a WAV audio stream using Deepgram's TTS API and pipe it to a file.

import { createWriteStream } from "fs";
import { pipeline } from "stream/promises";
import { DeepgramClient } from "@deepgram/sdk";

async function synthesizeSpeech(text: string, outPath: string): Promise<void> {
  const client = new DeepgramClient({ apiKey: process.env.DEEPGRAM_API_KEY });

  const response = await client.speak.v1.audio.generate({
    text,
    model: "aura-2-thalia-en",
    encoding: "linear16",
    container: "wav",
  });

  const audioStream = response.stream();
  const fileWriter = createWriteStream(outPath);
  await pipeline(audioStream, fileWriter);
  console.log("Audio saved to", outPath);
}

synthesizeSpeech("Hello from Deepgram.", "./output.wav");

Scenario - Voice agent over WebSocket

Establish a conversational voice agent session, configure it with a LLM provider, and handle agent responses.

import { DeepgramClient } from "@deepgram/sdk";

async function runVoiceAgent(): Promise<void> {
  const client = new DeepgramClient({ apiKey: process.env.DEEPGRAM_API_KEY });

  const connection = await client.agent.v1.connect();

  connection.on("open", () => {
    connection.sendAgentV1Settings({
      type: "Settings",
      agent: {
        language: "en",
        listen: { provider: { type: "deepgram", model: "nova-3" } },
        think: {
          provider: { type: "open_ai", model: "gpt-4o-mini" },
          prompt: "You are a concise AI assistant.",
        },
        speak: { provider: { type: "deepgram", model: "aura-2-thalia-en" } },
      },
    });
  });

  connection.on("message", (data: { type: string; role?: string; content?: string }) => {
    if (data.type === "ConversationText") {
      console.log(`[${data.role}]:`, data.content);
    }
  });

  connection.connect();
  await connection.waitForOpen();
}

runVoiceAgent();

File walkthrough

• index.ts - Root barrel; exports the Deepgram namespace alias plus all types and resource classes as named exports.
• Client.ts - Defines DeepgramClient (the upstream default client); wires together all resource sub-clients against Deepgram's hosted endpoints.
• CustomClient.ts - CustomDeepgramClient (re-exported as DeepgramClient); allows overriding HTTP transport and auth headers.
• BaseClient.ts - Abstract base with BaseClientOptions and BaseRequestOptions; inherited by both client variants.
• environments.ts - DeepgramEnvironment enum and DeepgramEnvironmentUrls type controlling which base URLs the SDK calls.
• errors/ - DeepgramError and DeepgramTimeoutError; all SDK-thrown errors extend these.
• exports.ts - Supplementary re-exports bundled by the SDK build pipeline.
• version.ts - Exports the SDK semver string; useful for logging and support diagnostics.
• api/ - Top-level namespace for all API resources, errors, and shared types.
• api/errors/ - BadRequestError (HTTP 400 wrapper) and other HTTP-status error classes.
• api/resources/agent/ - Voice agent client and WebSocket socket wrapper for conversational AI.
• api/resources/listen/ - Streaming and pre-recorded speech-to-text clients.
• api/resources/speak/ - Text-to-speech REST client.
• api/resources/read/ - Text analysis client (sentiment, topics, intents).
• api/resources/manage/ - Project, key, and member management REST clients.
• api/resources/auth/ - Auth token and grant management clients.
• api/resources/selfHosted/ - Credential management for self-hosted Deepgram deployments.
• api/resources/voiceAgent/ - Additional voice-agent resource helpers.
• api/types/ - Shared TypeScript interfaces for all request and response shapes.
• core/ - Internal HTTP fetch wrapper, WebSocket abstraction, retry logic, and header utilities.
• auth/ - Internal authentication helpers used by the client constructors.

Common pitfalls and fixes

• Missing DEEPGRAM_API_KEY: The SDK will throw or return 401s silently; always verify process.env.DEEPGRAM_API_KEY is set before constructing any client.
• ESM .js extension errors: The source uses import ... from "./foo.js" paths; ensure "moduleResolution": "NodeNext" or "Bundler" is set in tsconfig.json, otherwise TypeScript will fail to resolve local imports.
• ws not found at runtime: ws is a runtime dependency; run npm install ws in the consuming project even if @deepgram/sdk is not installed from npm.
• WebSocket connection.connect() must be called after attaching listeners: Attach all .on(...) handlers before calling connection.connect() and await connection.waitForOpen(), or early messages will be missed.
• Self-hosted endpoint: Pass environment: DeepgramEnvironment.SelfHosted and a DeepgramEnvironmentUrls object; forgetting this will route traffic to Deepgram's cloud even in on-prem setups.
• Bundler path aliases not mirroring tsconfig paths: If your bundler (Webpack, Vite, esbuild) does not have the same @deepgram/sdk alias as tsconfig.json, you will get runtime module-not-found errors in production builds.

Vibe-coding prompt template

I have the Deepgram JavaScript SDK source code in `src/deepgram/` and its
integration guide at `USAGE.md`. The upstream package is `@deepgram/sdk@5.1.1`.

Please help me integrate the Deepgram SDK into my existing project step by step:

1. Read `USAGE.md` for the full setup instructions and public API reference.
2. Look at `src/deepgram/index.ts` to understand all available exports.
3. Add the required `ws` dependency to `package.json`.
4. Configure `tsconfig.json` to resolve `@deepgram/sdk` from `src/deepgram/index.ts`.
5. Create a `DeepgramClient` instance using `DEEPGRAM_API_KEY` from environment.
6. Implement the following feature in my project: [DESCRIBE YOUR FEATURE HERE].
7. Add proper error handling using `DeepgramError` and `DeepgramTimeoutError`.
8. Show me the final integration code with all imports sourced from `src/deepgram/`.

My project stack is: [YOUR STACK: e.g. Express + TypeScript + Node 20].

License and credit

The Deepgram JavaScript SDK is released under the MIT License (see source/LICENSE if present, or the upstream repository). Upstream package: @deepgram/sdk on npm — maintained by Deepgram, Inc. Full API documentation at developers.deepgram.com.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.