Constructor#
new Pinecall(options)| Option | Type | Default | Description |
|---|---|---|---|
apiKey | string | — (required) | Your Pinecall API key |
url | string | wss://voice.pinecall.io/client | WebSocket endpoint |
reconnect | boolean | true | Auto-reconnect on disconnect |
pingInterval | number | 30000 | Keepalive interval in ms |
Example#
const pc = new Pinecall({
apiKey: process.env.PINECALL_API_KEY!,
});Methods#
connect()#
Open the WebSocket connection and authenticate. Returns a promise that resolves when auth succeeds.
await pc.connect();disconnect()#
Gracefully close the connection.
await pc.disconnect();agent(id, config?)#
Create or retrieve an agent. If an agent with this ID already exists, returns it (idempotent).
const agent = pc.agent("support", {
voice: "elevenlabs:abc",
language: "en",
llm: { provider: "openai", model: "gpt-4.1-mini", enabled: true, prompt: "..." },
});See Agent for full config.
deploy(id, config)#
Shortcut for agent() + addChannel(). Combines agent creation, LLM config, and channel registration in one call.
const mara = pc.deploy("mara", {
prompt: "You are Mara. Be concise.",
model: "gpt-4.1-mini",
voice: "elevenlabs:EXAVITQu4vr4xnSDxMaL",
language: "es",
channels: ["webrtc", "+13186330963"],
});DeployConfig fields:
| Field | Type | Description |
|---|---|---|
prompt | string | System prompt for the LLM |
model | string | LLM model (default: gpt-4.1-mini) |
voice | string | TTS voice shortcut (e.g. elevenlabs:voiceId) |
language | string | BCP-47 language code |
stt | string | STT provider (default: deepgram-flux) |
tools | array | OpenAI function-calling tool definitions |
channels | string[] | Channels to register: "webrtc", "chat", or phone numbers |
sessionLimits | object | Session timeout config (see Session Limits) |
allowedOrigins | string[] | Allowed origins for public browser token access (see Security) |
getAgent(id)#
Look up an agent by ID. Returns Agent | undefined.
const mara = pc.getAgent("mara");removeAgent(id)#
Unregister an agent. Returns boolean indicating whether the agent existed.
const removed = pc.removeAgent("mara");createToken(channel, agentId)#
Generate a short-lived, single-use token for browser WebRTC or chat connections. Used to mint tokens for browsers.
const token = await pc.createToken("webrtc", "mara");
// { token, server, expiresIn }See Security for the full token model.
stream(res?, options?)#
Open an SSE stream of agent events. Works with any framework — returns a Web API Response or writes to a Node.js ServerResponse.
// Web API (Remix, Next.js, Hono, Bun)
app.get("/events", () => pc.stream());
// Express / Node.js
app.get("/events", (req, res) => pc.stream(res));
// Filtered to specific agents
app.get("/events", () => pc.stream({ agents: ["mara", "julia"] }));
app.get("/events", (req, res) => pc.stream(res, { agents: ["mara"] }));See Multi-tenant guide for the filtering pattern.
Events#
Subscribe via pc.on(event, handler).
| Event | Signature | When |
|---|---|---|
connected | () | WebSocket auth succeeded |
disconnected | (reason) | Connection closed |
reconnecting | (attempt) | Auto-reconnect attempt N |
error | (err) | Protocol or transport error |
pc.on("connected", () => console.log("Live"));
pc.on("disconnected", (reason) => console.log("Down:", reason));
pc.on("reconnecting", (n) => console.log(`Retry ${n}`));
pc.on("error", (err) => console.error(err));