Skip to main content
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

1

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
2

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).
3

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();
4

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

OptionDescription
tokenRequired. JWT from client.generateSessionToken(agentId).
baseUrlAPI base URL. Default: https://api.vatel.ai. Use https://… or wss://…; the SDK picks the right protocol.
createWebSocketNode 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";