JavaScript / TypeScript SDK

Use @vatel/sdk to connect to Vatel voice agents from JavaScript or TypeScript. The SDK provides a REST client and a WebSocket session for real-time voice: send audio, receive events, and handle tool calls. It works in Node.js and the browser.

Session token

REST endpoint used to obtain a short-lived JWT for the WebSocket connection.

Connection

WebSocket channel, message types, and request/response flow.

Prerequisites

Node.js 18+ or a modern browser
API key (organization API key from the Vatel dashboard)
Agent ID for the agent you want to connect to
In Node.js only: a WebSocket implementation (ws package)

Walkthrough

Install the SDK

Install the package:

npm install @vatel/sdk

In Node.js, also install a WebSocket implementation (browsers have one built in):

npm install ws

Get a session token

Create a Client with your API key and call generateSessionToken with your agent ID. The token is a short-lived JWT used to open the WebSocket session.

import { Client } from "@vatel/sdk";

const client = new Client({
  getToken: () => process.env.VATEL_API_KEY,
});

const { data } = await client.generateSessionToken("your-agent-id");
if (!data?.token) throw new Error("Failed to get token");

In the browser, call your backend to get the token (never expose the API key in client code).

Connect a session and listen for events

Create a Session with the token, register event handlers, then call connect().

import { Session } from "@vatel/sdk";

const session = new Session({ token: data.token });

session.on("session_started", () => console.log("Connected"));
session.on("response_text", (msg) => console.log("Agent:", msg.data.text));
session.on("response_audio", (msg) => {
  // msg.data.audio is base64-encoded PCM (24 kHz, mono, 16-bit)
  // Decode and play with your audio stack
});
session.on("input_audio_transcript", (msg) => console.log("You said:", msg.data.transcript));

await session.connect();

Send audio

Send microphone (or other) audio as base64-encoded PCM chunks (24 kHz, mono, 16-bit):

session.sendInputAudio(base64PcmChunk);

Use your preferred audio capture and encoding; the SDK does not capture the microphone for you.

Node.js: WebSocket setup

Node does not include a WebSocket API. Install ws and pass a WebSocket factory when creating the session:

import { Session } from "@vatel/sdk";
import WebSocket from "ws";

const session = new Session({
  token: data.token,
  createWebSocket: (url) => new WebSocket(url),
});
await session.connect();

Session options

Option	Description
`token`	Required. JWT from `client.generateSessionToken(agentId)`.
`baseUrl`	API base URL. Default: `https://api.vatel.ai`. Use `https://…` or `wss://…`; the SDK picks the right protocol.
`createWebSocket`	Node only. Function that takes a URL and returns a WebSocket instance. Use with the `ws` package.

REST client

The Client uses your organization API key as a Bearer token and exposes the REST API. See the API reference for all endpoints. Example:

import { Client } from "@vatel/sdk";

const client = new Client({
  getToken: () => process.env.VATEL_API_KEY,
});

const { data: tokenData } = await client.generateSessionToken("agent-id");
// Other endpoints available on the client

Tool calls

When the agent invokes a tool, handle the tool_call event and send the result back with sendToolCallOutput:

session.on("tool_call", async (msg) => {
  const { toolCallId, toolName, arguments: args } = msg.data;
  const result = await yourToolHandler(toolName, args);
  session.sendToolCallOutput(toolCallId, JSON.stringify(result));
});

TypeScript

The package includes type definitions. No extra @types install; import types when needed:

import type { ResponseAudioMessage, SessionStartedMessage } from "@vatel/sdk";

Overview

Configure

Deploy

Monitor

Integrations

Session token

Connection

Prerequisites

Walkthrough

Node.js: WebSocket setup

Session options

REST client

Tool calls

TypeScript

Session token

Connection

​Prerequisites

​Walkthrough

​Node.js: WebSocket setup

​Session options

​REST client

​Tool calls

​TypeScript

Prerequisites

Walkthrough

Node.js: WebSocket setup

Session options

REST client

Tool calls

TypeScript