![\"npm\"](\"https://img.shields.io/npm/v/getpatter?logo=npm&logoColor=white&label=npm%20install%20getpatter\")
\n ![\"MIT](\"https://img.shields.io/badge/license-MIT-green\"){kind=icon}
\n ![\"TypeScript](\"https://img.shields.io/badge/typescript-5.0%2B-3178c6?logo=typescript&logoColor=white\"){kind=icon}
\n\n
Connect AI agents to phone numbers in four lines of code
\n\n\n\n
\n Quickstart •\n Features •\n Configuration •\n Voice Modes •\n API Reference •\n Contributing\n
\n\n---\n\nPatter is the open-source SDK that gives your AI agent a phone number. Point it at any function that returns a string, and Patter handles the rest: telephony, speech-to-text, text-to-speech, and real-time audio streaming. You build the agent — we connect it to the phone.\n\n## Quickstart\n\n```bash\nnpm install getpatter\n```\n\nSet the env vars your carrier and engine need:\n\n```bash\nexport TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\nexport TWILIO_AUTH_TOKEN=your_auth_token\nexport OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx\n```\n\nFour lines of TypeScript:\n\n```typescript\nimport { Patter, Twilio, OpenAIRealtime } from \"getpatter\";\n\nconst phone = new Patter({ carrier: new Twilio(), phoneNumber: \"+15550001234\" });\nconst agent = phone.agent({ engine: new OpenAIRealtime(), systemPrompt: \"You are a friendly receptionist for Acme Corp.\", firstMessage: \"Hello! How can I help?\" });\nawait phone.serve({ agent, tunnel: true });\n```\n\n`tunnel: true` spawns a Cloudflare tunnel and points your Twilio number at it. In production, pass `webhookUrl: \"api.prod.example.com\"` to the constructor instead.\n\n## Features\n\n| Feature | Method | Example |\n|---|---|---|\n| Inbound calls | `phone.serve({ agent })` | Answer calls as an AI |\n| Outbound calls + AMD | `phone.call({ to, machineDetection: true })` | Place calls with voicemail detection |\n| Tool calling | `agent({ tools: [tool(...)] })` | Agent calls external APIs mid-conversation |\n| Custom STT + TTS | `agent({ stt: new DeepgramSTT(), tts: new ElevenLabsTTS() })` | Bring your own voice providers |\n| Dynamic variables | `agent({ variables: {...} })` | Personalize prompts per caller |\n| Pluggable LLM | `agent({ llm: new AnthropicLLM() })` | 5 built-in providers: OpenAI, Anthropic, Groq, Cerebras, Google |\n| Custom LLM (any model) | `serve({ onMessage })` | Route to anything — local inference, internal gateways, etc. |\n| Call recording | `serve({ recording: true })` | Record all calls |\n| Call transfer | `transfer_call` (auto-injected) | Transfer to a human |\n| Voicemail drop | `call({ voicemailMessage: \"...\" })` | Play message on voicemail |\n| Phone-as-a-tool (external agents) | `new PatterTool({ phone, agent }).execute(...)` | Drop into LangChain / OpenAI Assistants / Hermes / MCP |\n\n## Configuration\n\n### Environment variables\n\nEvery provider reads its credentials from the environment by default. Pass `apiKey: \"...\"` to any constructor to override.\n\n| Variable | Used by |\n|---|---|\n| `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN` | `new Twilio()` carrier |\n| `TELNYX_API_KEY`, `TELNYX_CONNECTION_ID`, `TELNYX_PUBLIC_KEY` (optional) | `new Telnyx()` carrier |\n| `PLIVO_AUTH_ID`, `PLIVO_AUTH_TOKEN` | `new Plivo()` carrier — Auth Token doubles as the V3 webhook signature key |\n| `OPENAI_API_KEY` | `OpenAIRealtime`, `WhisperSTT`, `OpenAITTS` |\n| `ELEVENLABS_API_KEY`, `ELEVENLABS_AGENT_ID` | `ElevenLabsConvAI`, `ElevenLabsTTS` |\n| `DEEPGRAM_API_KEY` | `DeepgramSTT` |\n| `CARTESIA_API_KEY` | `CartesiaSTT`, `CartesiaTTS` |\n| `RIME_API_KEY` | `RimeTTS` |\n| `LMNT_API_KEY` | `LMNTTTS` |\n| `SONIOX_API_KEY` | `SonioxSTT` |\n| `ASSEMBLYAI_API_KEY` | `AssemblyAISTT` |\n| `ANTHROPIC_API_KEY` | `AnthropicLLM` |\n| `GROQ_API_KEY` | `GroqLLM` |\n| `CEREBRAS_API_KEY` | `CerebrasLLM` |\n| `GEMINI_API_KEY` (or `GOOGLE_API_KEY`) | `GoogleLLM` |\n\n```bash\ncp .env.example .env\n# Edit .env with your API keys\n```\n\n> **Other carriers:** **Telnyx** and **Plivo** are both fully supported alternatives to Twilio. All three carriers receive equal support for inbound DTMF, transfer, AMD, status callbacks, recording, voicemail drop, and metrics. **Plivo** additionally supports native DTMF *send* over the media WebSocket — a capability Twilio Media Streams lacks. Plivo's Auth Token doubles as the V3 webhook signature key (no separate public key, unlike Telnyx Ed25519).\n\n## Voice Modes\n\n| Mode | Latency | Quality | Best For |\n|---|---|---|---|\n| **OpenAI Realtime** | Lowest | High | Fluid, low-latency conversations |\n| **Pipeline** (STT + LLM + TTS) | Low | High | Independent control over STT and TTS |\n| **ElevenLabs ConvAI** | Low | High | ElevenLabs-managed conversation flow |\n\n## API Reference\n\n### `Patter` constructor\n\n```typescript\nnew Patter({\n carrier: Twilio | Telnyx | Plivo;\n phoneNumber: string;\n webhookUrl?: string; // Public hostname. Mutually exclusive with tunnel.\n tunnel?: CloudflareTunnel | StaticTunnel | boolean; // `true` is shorthand for new CloudflareTunnel().\n})\n```\n\n| Parameter | Type | Description |\n|---|---|---|\n| `carrier` | `Twilio` / `Telnyx` / `Plivo` | Carrier instance. Reads env vars by default. |\n| `phoneNumber` | `string` | Your phone number in E.164 format. |\n| `webhookUrl` | `string` | Public hostname your local server is reachable on. |\n| `tunnel` | `CloudflareTunnel \\| StaticTunnel \\| boolean` | `new CloudflareTunnel()`, `new StaticTunnel({ hostname: ... })`, or `true` (shorthand for `new CloudflareTunnel()`). |\n\n### `phone.agent()`\n\n```typescript\nphone.agent({\n systemPrompt: string;\n engine?: OpenAIRealtime | ElevenLabsConvAI; // default: new OpenAIRealtime()\n stt?: STTProvider; // e.g. new DeepgramSTT()\n tts?: TTSProvider; // e.g. new ElevenLabsTTS()\n voice?: string;\n model?: string;\n language?: string;\n firstMessage?: string;\n tools?: Tool[];\n guardrails?: Guardrail[];\n variables?: Record