@pinecall/sdk

Build real-time voice & messaging AI agents in TypeScript.

WebSocket client for Pinecall Voice — ~80 KB, one dependency.

Docs · Quickstart · API Reference · Examples

Install

npm install @pinecall/sdk

Node.js ≥ 18. Only runtime dependency: ws.

30-second example

import { Pinecall } from "@pinecall/sdk";

const pc = new Pinecall();
await pc.connect();

const mara = pc.agent("mara", {
  prompt: "You are Mara, a friendly voice assistant. Be concise.",
  llm: "openai/gpt-4.1-mini",
  voice: "elevenlabs/sarah",
  language: "es",
  phoneNumber: "+13186330963",
  greeting: "¡Hola! ¿En qué puedo ayudarte?",
});

mara.on("call.ended", (call, reason) =>
  console.log(`Call ended: ${reason} (${call.duration}s)`),
);

That's a production-ready voice agent. It answers calls on a phone number, speaks a greeting, runs an LLM, and talks back. No webhooks, no platform dashboard, no infra.

Why Pinecall

Most voice AI platforms are platform-first: you configure agents in their dashboard, define tools as JSON schemas, and expose webhook URLs for the platform to call. Your app adapts to the platform.

Pinecall is code-first: the agent is your code. It runs inside your app, uses your database, calls your internal APIs, and handles tool calls as local functions. The platform adapts to your app.

• ✅ One agent, many channels — phone, SIP, WebRTC, chat, WhatsApp from the same instance
• ✅ Hot-reload everything — change voice, language, prompt, tools mid-call
• ✅ Skills — bundle prompt + tools + knowledge base into a capability the agent loads on demand (loadSkill/unloadSkill) — keeps the tool list small
• ✅ Knowledge bases — ground answers on your docs (RAG); one KB or several merged by score
• ✅ Bring your own LLM — or use the server-side LLM and skip the plumbing
• ✅ Local tool calls — no public endpoints, no webhook URLs to expose
• ✅ Dev mode — share a phone number between prod and any number of devs

The Pinecall ecosystem

This package is the server-side SDK. The full picture includes three browser-side packages too:

| Package | What it is | When to use | |---|---|---| | @pinecall/sdk | Server-side SDK (this repo) | Build agents in Node.js — voice, WhatsApp, phone, SIP, outbound | | @pinecall/voice-core | WebRTC client (framework-agnostic) | Browser voice in vanilla JS, Vue, Svelte, or any framework | | @pinecall/voice-widget | React voice widget | Drop-in animated orb UI with multi-language + interactive tools API | | @pinecall/chat-core | Text chat client | Browser chat over WebSocket — vanilla JS + React hook |

All four packages talk to the same Pinecall voice server. The same agent (pc.agent("mara", ...)) can be reached over phone, WebRTC, chat, or WhatsApp — without changing your agent code.

Documentation

| | | |---|---| | 🚀 Quickstart | Zero to first call in 5 minutes | | 📘 Concepts | How agents, channels, and sessions fit together | | 🛠 Guides | Build phone agents, WhatsApp bots, browser widgets | | 📚 Server SDK API | @pinecall/sdk — every class, method, event | | 🌐 Voice Core | @pinecall/voice-core browser WebRTC client | | ⚛️ Voice Widget | @pinecall/voice-widget React widget + Tools API | | 💬 Chat Core | @pinecall/chat-core browser chat client | | ⚙️ Configuration | STT, TTS, LLM providers and tuning | | 🔒 Security | Token model and best practices |

Examples

Runnable examples in examples/ — npm install, cp .env.example .env, npm start.

One feature, one file. Each folder shows ONE thing, in a single server.mjs, against this checkout of the SDK. Whole apps — storage, deploys, two processes — live in pinecall/examples.

| Example | What it shows | |---|---| | simple/ | The smallest agent worth running — prompt, voice, calls saved to a file | | ringing/ | Accept or reject an inbound call before it is ever answered | | history/ | A returning caller's previous conversation, restored into the live one | | turn-detection/ | Turn events as a state machine: Flux (native) vs Nova-3 (SmartTurn + Silero) | | tools/ | One tool(), and a return value that proves the model actually called it | | skills/ | skill() — tools that stay latent until the model loads them | | reservations/ | Three tools in a fixed order: check, then confirm, then book | | phone-line/ | pc.line() — a keypad menu decided by if, with no model in it | | outbound-dispatch/ | DispatchHub — a CSV of people to ring, paced, with results written back | | whatsapp-dashboard/ | WhatsApp with human takeover — pause the agent, answer yourself, resume | | agent-tests/ | pinecall test specs — chat and real voice |

📖 More in the Examples Guide.

Browse the docs offline

All docs live in docs/ as plain markdown — readable on GitHub, rendered on docs.pinecall.io via Mintlify.

docs/
├── quickstart.md
├── concepts/        # agents, channels, hot-reload, deployment
├── guides/          # how to build X (phone, WhatsApp, browser)
├── api/             # @pinecall/sdk class reference
├── voice-core/      # @pinecall/voice-core (browser WebRTC)
├── voice-widget/    # @pinecall/voice-widget (React UI)
├── chat-core/       # @pinecall/chat-core (browser chat)
├── reference/       # config tables (STT, TTS, LLM, events)
└── examples/        # complete runnable snippets

Status

Pinecall SDK is used in production today. The API surface is stable; breaking changes follow semver and ship with migration notes in the changelog.

License

MIT © Pinecall