# VoIPBIN

> CPaaS REST APIs for AI voice agents, programmable calls, SMS, email, chat, and social channels. All media server-side. Send JSON commands, receive JSON events via webhook or WebSocket. No XML, no TwiML, no client-side media handling.

- **Base URL:** `https://api.voipbin.net/v1.0`
- **Auth:** `?token=<jwt>` or `?accesskey=<key>` as a query parameter on every request. Token (JWT, 7-day expiry): `POST /auth/login`. Accesskey (permanent): returned by `POST /auth/signup` or create via `POST /v1.0/accesskeys`.
- **Headless signup:** `POST /auth/signup` with `email` + `accepted_tos: true` → returns `accesskey.token` immediately. No email OTP required. Save the token, shown only once.
- **Events:** Webhook (HTTP POST) or WebSocket (`wss://api.voipbin.net/v1.0/ws?accesskey=<key>`). WebSocket preferred for AI agents.
- **Direct Hash SIP URI:** Every resource gets `sip:direct.<12hex>@sip.voipbin.net` instantly, no phone number purchase needed. Extensions/Conferences/Teams/Queues/Flows: auto-created. Agents/AIs: call `POST /{resource}/{id}/direct-hash-regenerate` first.
- **Media Offloading:** VoIPBin handles all raw audio (RTP, STT, TTS). Your AI sends/receives text only: caller audio → VoIPBin STT → `transcript_created` webhook → your AI → `POST /speakings/{id}/say` → VoIPBin TTS → caller.
- **MCP Server:** `uvx voipbin-mcp`. Use VoIPBin directly from Claude Code, Cursor, and other MCP clients. Config: `{"mcpServers": {"voipbin": {"command": "uvx", "args": ["voipbin-mcp"], "env": {"VOIPBIN_API_KEY": "<key>"}}}}`
- **Phone numbers:** E.164 format (`+15551234567`). `+899` prefix = virtual/test numbers, never route as outbound PSTN.
- **Full guide:** [skill.md](https://voipbin.net/skill.md) (AI agent self-onboarding, API examples, troubleshooting, and decision trees).

## Common Workflows

**AI voice agent:** `POST /ais` (engine_model, engine_key, prompt) → `POST /flows` (actions: [answer, ai_talk]) → `PUT /numbers/{id}` (call_flow_id) → inbound calls handled by AI.
**Outbound call:** Verify destination country is in `GET /outbound_config` → `destination_whitelist`. If not, `PUT /outbound_config` to add it first. Then `POST /calls` with source (E.164), destinations, and either inline actions or flow_id. Status: dialing → ringing → progressing → hangup.
**Self-host:** Clone `github.com/voipbin/install`, fill `config.yaml` (GCP project, domain, credentials), run `./voipbin-install apply`. Eight-stage pipeline, resumable on failure.
**Send SMS:** `POST /messages` with source (E.164 number you own), destinations, text. Max 160 chars/segment, 70 for unicode.
**Send email:** `POST /emails` with from (verified domain), to, subject, content (text + html). Returns queued status.
**IVR menu:** `POST /flows` with actions: [answer, talk (prompt), digits_receive, branch (route by DTMF)] → bind to number.
**Call queue:** `POST /tags` → `POST /agents` (with tag_ids) → `POST /queues` (with tag_ids, wait flow) → add queue_join action to flow.
**Record + transcribe:** Add `recording_start` and `transcribe_start` actions to any flow. Transcripts arrive via webhook/WebSocket events.
**Campaign:** `POST /outplans` (schedule, concurrency) → `POST /outdials` (target list) → `POST /campaigns` (links outplan + outdials + flow).

## Task Routing

| Goal | Endpoint | Section |
|------|----------|---------|
| AI-powered phone support | `POST /ais` + flow with `ai_talk` | AI & Voice Agents |
| Make/receive calls | `POST /calls` or flow with `answer` | Voice & Calls |
| Send SMS | `POST /messages` | Messaging |
| Send email | `POST /emails` | Messaging |
| IVR / call routing | `POST /flows` with branch actions | Flows & Automation |
| Call center with agents | `POST /queues` + `POST /agents` | Voice & Calls |
| Bulk outbound | `POST /campaigns` | Outbound Campaigns |
| Live transcription | `transcribe_start` flow action | AI & Voice Agents |
| Call recording | `recording_start` flow action | Voice & Calls |
| Real-time events | WebSocket subscribe or webhook | Events |
| Buy phone number | `POST /numbers` | Numbers & Infrastructure |
| Self-host VoIPBin on GCP | `./voipbin-install apply` | Self-Hosting |
| Use VoIPBin from AI coding tools | `uvx voipbin-mcp` (MCP server) | API Reference |

## AI & Voice Agents

- [AI Overview](https://api.voipbin.net/docs/_sources/ai_overview.rst.txt): Capabilities, supported LLM providers (OpenAI, Anthropic, Google), STT/TTS engines
- [AI Voice Agent Integration](https://api.voipbin.net/docs/_sources/ai_voice_agent_integration.rst.txt): Build custom voice agents (architecture, audio pipeline, prompt design)
- [AI API](https://api.voipbin.net/redoc/#tag/AI): `POST /ais`, requires `engine_model` (provider.model format), `engine_key`, `prompt`, optional `tool_names`
- [Speaking API](https://api.voipbin.net/redoc/#tag/Speaking): Stream TTS audio into active calls in real-time
- [RAG API](https://api.voipbin.net/redoc/#tag/RAG): Attach knowledge bases to AI agents for context-aware responses
- [Transcription Overview](https://api.voipbin.net/docs/_sources/transcribe_overview.rst.txt): Real-time STT (Google Cloud Speech and Amazon Transcribe providers)
- [Transcription API](https://api.voipbin.net/redoc/#tag/Transcribe): `transcribe_start`/`transcribe_stop` flow actions, results via webhook/WebSocket
- [Mediastream](https://api.voipbin.net/docs/_sources/mediastream.rst.txt): Raw audio over WebSocket for custom STT/processing pipelines

## Flows & Automation

- [Flow Overview](https://api.voipbin.net/docs/_sources/flow_overview.rst.txt): JSON action sequences for calls, messages, and API triggers. Reusable across numbers
- [Flow Tutorial](https://api.voipbin.net/docs/_sources/flow_tutorial_basic.rst.txt): Build flows with actions, branching, variables, and chaining
- [Flow API](https://api.voipbin.net/redoc/#tag/Flow): `POST /flows` with `name`, `actions` array. Key actions: answer, talk, ai_talk, branch, digits_receive, queue_join
- [Activeflow API](https://api.voipbin.net/redoc/#tag/Activeflow): Monitor running instances. `GET /activeflows/{id}` shows current_action and state
- [Variable](https://api.voipbin.net/docs/_sources/variable.rst.txt): `${voipbin.call.caller_id}`, `${voipbin.call.digits}`, `${voipbin.message.text}`, custom vars via `variable_set`

## Voice & Calls

- [Call Overview](https://api.voipbin.net/docs/_sources/call_overview.rst.txt): Lifecycle: dialing → ringing → progressing → hangup. Check `hangup_reason` for diagnostics.
- [Call Tutorial](https://api.voipbin.net/docs/_sources/call_tutorial.rst.txt): Outbound and inbound call handling step-by-step
- [Call API](https://api.voipbin.net/redoc/#tag/Call): `POST /calls` with source, destinations, actions/flow_id. `GET /calls/{id}` for status.
- [Conference API](https://api.voipbin.net/redoc/#tag/Conference): `POST /conferences`, type `conference` (multi-party) or `connect` (1:1 bridge, auto-terminates)
- [Groupcall API](https://api.voipbin.net/redoc/#tag/Groupcall): Ring multiple destinations simultaneously, connect first to answer
- [Queue Overview](https://api.voipbin.net/docs/_sources/queue_overview.rst.txt): Skill-based routing, agents matched by tags (AND logic), checked every 1s
- [Queue API](https://api.voipbin.net/redoc/#tag/Queue): `POST /queues` with tag_ids and wait_flow_id. Monitor via `GET /queuecalls`.
- [Recording API](https://api.voipbin.net/redoc/#tag/Recording): `GET /recordings/{id}` for download URL (signed, expires in 1hr)
- [Transfer API](https://api.voipbin.net/redoc/#tag/Transfer): Blind and attended transfers between active calls

## Messaging

- [Message API](https://api.voipbin.net/redoc/#tag/Message): `POST /messages` with source (E.164), destinations, text. Status: sending → sent → delivered/failed.
- [Email API](https://api.voipbin.net/redoc/#tag/Email): `POST /emails` with from (verified domain required), to, subject, content. Status: queued → delivered/bounced.
- [Talk](https://api.voipbin.net/docs/_sources/talk.rst.txt): Real-time agent-customer chat
- [Conversation API](https://api.voipbin.net/redoc/#tag/Conversation): Threaded messaging with full history across social channels (WhatsApp, LINE, etc.)

## Outbound Campaigns

- [Campaign](https://api.voipbin.net/docs/_sources/campaign.rst.txt): Bulk outreach, links outplan (schedule) + outdials (targets) + flow (call logic)
- [Campaign API](https://api.voipbin.net/redoc/#tag/Campaign): `POST /campaigns` to create, then start/pause/monitor
- [Outdial API](https://api.voipbin.net/redoc/#tag/Outdial): `POST /outdials`, target phone numbers for campaign dialing
- [Outplan API](https://api.voipbin.net/redoc/#tag/Outplan): `POST /outplans` (schedule windows, concurrency limits, dialing rules)

## Events

- [Webhook Overview](https://api.voipbin.net/docs/_sources/webhook_overview.rst.txt): HTTP POST to your HTTPS endpoint. Must respond 200 within 5s. Retries on failure.
- [WebSocket Overview](https://api.voipbin.net/docs/_sources/websocket_overview.rst.txt): Subscribe by topic `<scope>:<scope_id>:<resource>:<resource_id>` (wildcards: `*`). Reconnect with exponential backoff.
- [WebSocket API](https://api.voipbin.net/redoc/#tag/Websocket): `wss://api.voipbin.net/v1.0/ws?accesskey=<key>` (events as JSON with event_type, topic, data)

## Numbers & Infrastructure

- [Number API](https://api.voipbin.net/redoc/#tag/Number): `GET /number_availables` to search, `POST /numbers` to buy, `PUT /numbers/{id}` to bind flow_id
- [Trunk API](https://api.voipbin.net/redoc/#tag/Trunk): SIP trunk config for Bring Your Own Carrier (BYOC)
- [Extension API](https://api.voipbin.net/redoc/#tag/Extension): Internal extension numbering and routing
- [Route API](https://api.voipbin.net/redoc/#tag/Route): Inbound and outbound call routing rules
- [OutboundConfig Overview](https://api.voipbin.net/docs/_sources/outbound_config_overview.rst.txt): Per-customer outbound PSTN control (destination country whitelist and codec preference)
- [OutboundConfig API](https://api.voipbin.net/redoc/#tag/OutboundConfig): `GET /outbound_config` (own), `PUT /outbound_config` (update own). Required before any outbound PSTN call.

## Self-Hosting

- [Self-Hosting Overview](https://api.voipbin.net/docs/_sources/self_hosting_overview.rst.txt): Eight-stage install pipeline (terraform, GKE, Kamailio, Ansible). Run on GCP.
- [Self-Hosting Install](https://api.voipbin.net/docs/_sources/self_hosting_install.rst.txt): Prerequisites, `voipbin-install apply` walkthrough, resumable stages.
- [Self-Hosting Configuration](https://api.voipbin.net/docs/_sources/self_hosting_configuration.rst.txt): `config.yaml` reference for all deployment parameters.
- [Self-Hosting Troubleshooting](https://api.voipbin.net/docs/_sources/self_hosting_troubleshooting.rst.txt): Common failure modes and recovery steps.

## Troubleshooting

- [Call Troubleshooting](https://api.voipbin.net/docs/_sources/call_troubleshooting.rst.txt): Connection failures, audio issues, flow errors, webhook delivery. Start with `GET /calls/{id}`
- [Timeline API](https://api.voipbin.net/redoc/#tag/Timeline): SIP traces and PCAP downloads, `GET /timelines?reference_id=<call-id>`

## API Reference

- [OpenAPI 3.0 (JSON)](https://api.voipbin.net/openapi.json): Machine-readable spec for client code generation
- [API Reference (ReDoc)](https://api.voipbin.net/redoc/): Interactive reference (all endpoints, schemas, and examples)
- [Docs (plain text)](https://api.voipbin.net/docs/): RST at `/docs/_sources/<name>.rst.txt`, LLM-optimized with AI hints
- [Quickstart](https://api.voipbin.net/docs/_sources/quickstart.rst.txt): End-to-end walkthrough (signup, auth, first call, queues, transcription)
- [Install CLI](https://github.com/voipbin/install): Production self-hosting on GCP via `./voipbin-install apply`
- [Sandbox](https://github.com/voipbin/sandbox): Run VoIPBin locally with Docker for development and testing

## Optional

- [Agent API](https://api.voipbin.net/redoc/#tag/Agent): `POST /agents` with name, tag_ids. Status lifecycle: available → ringing → busy → wrap-up.
- [Contact API](https://api.voipbin.net/redoc/#tag/Contact): CRUD contacts, lookup by phone (`?phone=%2B155...`) or email. Tags and external_id for CRM.
- [Billing API](https://api.voipbin.net/redoc/#tag/Billing): `GET /billing-accounts`, check balance and usage. 402 = insufficient funds.
- [Customer](https://api.voipbin.net/docs/_sources/customer.rst.txt): Account management, billing tiers, and permissions
- [Glossary](https://api.voipbin.net/docs/_sources/glossary.rst.txt): Key terms and definitions