@pinecall/sdk

---

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
• 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/ — clone, cp .env.example .env, and run.

Example	What it shows
simple/	Minimal voice agent — phone + history in 30 lines
outbound-dispatch/	CSV-driven outbound campaign — rate limiting, dedup, result writeback
turn-detection/	Debug turn events: Flux (native) vs Nova-3 (SmartTurn + Silero)
ringing/	Accept or reject calls programmatically with call.ringing
history/	Conversation persistence — returning callers get context restored
sse/	Real-time event streaming via Server-Sent Events (SSE)
whatsapp-dashboard/	WhatsApp agent + human takeover dashboard (Express + React + SSE)

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