# Voxplo -- full product reference for AI agents

## What it is

Voxplo is an AI phone platform with two main use cases:

1. **AI receptionist (inbound):** An AI assistant answers your business phone number 24/7, handles questions using your business knowledge, books calendar appointments, takes structured messages, and emails you a summary of every call. Configured via an iOS app or web dashboard; no coding required.

2. **Agent calling API (outbound):** A REST API and MCP server that lets AI agents and developers place outbound phone calls with a plain-language objective. The AI handles the conversation, extracts structured data, and returns a summary and transcript. Useful for appointment reminders, lead qualification, order confirmations, and any task that currently requires a human to make a phone call.

## Public API

Base URL: https://api.voxplo.ai

All endpoints require the header:
  Authorization: Bearer bys_ak_YOUR_KEY

Keys are created under Account > Developers in the dashboard.

### Place a call

POST /v1/agent/calls
Content-Type: application/json

Request body fields:
- to (string, required): Destination phone number in E.164 format, e.g. "+14155550123".
- objective (string, required): What the AI should accomplish. Plain text, e.g. "Confirm the appointment for tomorrow at 2 PM and ask if they need to reschedule."
- context (string, optional): Background information the AI should know. Not shared with the recipient.
- fields (array, optional): Structured fields to extract from the transcript. Up to 20 items. Each item: { "name": "...", "type": "string|boolean|number", "description": "..." }.
- webhookUrl (string, optional): HTTPS URL to receive signed webhook events during and after the call.
- callerId (string, optional): Caller ID override. Must be a number on your account (E.164). Defaults to the number set in the Developers dashboard.
- voice (string, optional): The voice the AI uses on the call, e.g. "Aoede", "Kore", "Puck". Defaults to the key's dashboard setting.
- language (string, optional): BCP-47 code (e.g. "en-US", "ru-RU") or "auto". If omitted, Voxplo infers the language from the objective and context.

Example request:
  POST https://api.voxplo.ai/v1/agent/calls
  Authorization: Bearer bys_ak_YOUR_KEY
  {
    "to": "+14155550123",
    "objective": "Book a table for 4 at 7 PM Friday. Confirm the time and ask for their name.",
    "fields": [
      { "name": "booked",         "type": "boolean" },
      { "name": "confirmed_time", "type": "string"  },
      { "name": "contact_name",   "type": "string"  }
    ],
    "webhookUrl": "https://your-server.example.com/webhooks/bys",
    "callerId": "+12134932550"
  }

Response (immediate, call is async):
  { "callId": "f47ac10b-...", "status": "queued" }

### Get a call

GET /v1/agent/calls/{id}
Authorization: Bearer bys_ak_YOUR_KEY

Returns the current state of a call. Response fields include:
- id (string): Call ID.
- status (string): Current status -- see lifecycle below.
- to (string): Destination number (E.164).
- objective (string): The objective supplied at placement.
- voice (string): The voice the AI used.
- language (string): The language the AI spoke (BCP-47).
- languageSource (string): "explicit" | "inferred" | "auto".
- summary (string|null): Plain-English summary. Set on completed.
- transcript (string|null): Full conversation transcript.
- extracted (object|null): Extracted field values keyed by field name.
- recordingUrl (string|null): Authenticated URL to the call recording.
- startedAt (string|null): ISO 8601 timestamp when the call was answered.
- endedAt (string|null): ISO 8601 timestamp when the call ended.
- durationSec (number|null): Call duration in seconds.
- error (string|null): Error token on failed calls.

### List calls

GET /v1/agent/calls?limit=20
Authorization: Bearer bys_ak_YOUR_KEY

Returns recent calls for your account (most recent first). Query param: limit (default 20, max 100).
Response: { "calls": [ ...same shape as get-call... ] }

### Status lifecycle

Non-terminal: queued, dialing, in_progress
Terminal (poll or wait for one of these): completed, no_answer, voicemail, declined, failed

### Guardrails (enforced at placement time; violations return 4xx before any call is placed)

- Allowed destinations: US, CA, GB, AU, NZ, IL. Others: destination_blocked.
- Blocked number types: premium-rate, satellite, IRSF-listed.
- Rate limit: maximum calls per minute per API key. Excess: 429 rate_limited.
- Usage cap: outbound minutes drawn from plan allowance. Exceeded: 429 over_minute_cap.
- Caller ID ownership: callerId must be a number on your account. Unknown: 400 caller_id_not_owned.

Full error reference: https://www.voxplo.ai/docs/agent-api/api-reference

## MCP server

Hosted MCP URL (Streamable HTTP + OAuth):
  https://mcp.voxplo.ai/mcp

To connect from Claude: Settings > Connectors > Add custom connector. Enter the URL above, leave OAuth fields blank, then authorize with a bys_ak_ key when prompted.

To run locally (Node 18+, stdio mode):
  "voxplo-mcp" via npx -- configure in claude_desktop_config.json or .cursor/mcp.json with VOXPLO_API_KEY env var.

Available MCP tools:
- place_call: Places an outbound AI call. Inputs: to (required, E.164), objective (required), context, fields, webhookUrl, callerId. Returns { callId, status }.
- get_call: Fetches the current status and result of a call by callId. Returns the full call record (status, summary, transcript, extracted, recordingUrl). Poll this until status is terminal.
- list_calls: Lists recent calls on your account. Input: limit (optional, default 20, max 100). Returns { calls: [...] }.

MCP reference doc: https://www.voxplo.ai/docs/agent-api/mcp

## SDKs

Both SDKs are published and available via the standard package managers:
- Node SDK: published on npm as "voxplo" (v0.1.0+). Install: npm install voxplo. Client class with placeCall(), waitForCall(), listCalls(); verifyWebhook() helper. Requires Node 18+.
- Python SDK: published on PyPI as "voxplo". Install: pip install voxplo. Client class with place_call(), wait_for_call(), list_calls(); verify_webhook() helper. Requires Python 3.8+.

Both SDKs expose a wait_for_call / waitForCall helper that polls until a terminal status is reached (default timeout 3 minutes / 180 seconds).

SDK reference doc: https://www.voxplo.ai/docs/agent-api/sdks

## Webhooks

Set webhookUrl when placing a call to receive signed events delivered to your HTTPS endpoint.
Signature header: X-BYS-Signature
Events include: call.in_progress (call answered), call.<terminal_status> (e.g. call.completed, call.no_answer).
Webhook reference doc: https://www.voxplo.ai/docs/agent-api/webhooks

## Pricing

All plans include a 14-day free trial. No free tier.

- Starter: $49/month (or $490/year). 1 phone number, 1 agent, 250 answered minutes/month, 75 outbound minutes/month. Recordings, transcripts, summaries, calendar booking, email support.
- Pro (most popular): $149/month (or $1,490/year). 3 phone numbers, 5 agents, 1,000 answered minutes/month, 200 outbound minutes/month. Adds knowledge documents (RAG), call transfer and smart routing, priority email support.
- Business: $299/month (or $2,990/year). 5 phone numbers, 20 agents, 2,500 answered minutes/month, 500 outbound minutes/month. Everything in Pro plus priority support and onboarding assistance.

Pricing page: https://www.voxplo.ai/pricing

## Key links

- Versioning and deprecation policy: https://www.voxplo.ai/docs/agent-api/versioning (URL versioning /v1, 90 days notice, Deprecation/Sunset/Link headers, RateLimit headers on every response)

- [Home](https://www.voxplo.ai/): Overview of Voxplo.
- [Docs overview](https://www.voxplo.ai/docs): Full documentation index.
- [Agent API overview](https://www.voxplo.ai/docs/agent-api): What the API does, the call lifecycle, and how to choose REST vs MCP vs SDK.
- [Quickstart](https://www.voxplo.ai/docs/agent-api/quickstart): Place your first call in three steps.
- [API reference](https://www.voxplo.ai/docs/agent-api/api-reference): Every parameter, response field, status, guardrail, and error token.
- [MCP server docs](https://www.voxplo.ai/docs/agent-api/mcp): Add the hosted connector or run it locally.
- [SDKs](https://www.voxplo.ai/docs/agent-api/sdks): Node and Python SDK install and usage.
- [Webhooks](https://www.voxplo.ai/docs/agent-api/webhooks): Real-time signed events for calls.
- [OpenAPI spec](https://www.voxplo.ai/openapi.json): Machine-readable OpenAPI 3.1 spec for the Agent API.
- [Agents reference](https://www.voxplo.ai/agents.md): Agent instruction file with WHEN TO USE, tools, auth, and constraints.
- [Pricing](https://www.voxplo.ai/pricing): Starter ($49/mo), Pro ($149/mo), Business ($299/mo).
- [Support](https://www.voxplo.ai/support): Email support@voxplo.ai.
- [FAQ](https://www.voxplo.ai/faq): Frequently asked questions.

## Code examples

### Place a call via REST API (curl)

```bash
curl -X POST https://api.voxplo.ai/v1/agent/calls \
  -H "Authorization: Bearer bys_ak_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550123",
    "objective": "Confirm the appointment for tomorrow at 2 PM and ask if they need to reschedule.",
    "fields": [
      { "name": "confirmed", "type": "boolean" },
      { "name": "new_time",  "type": "string"  }
    ]
  }'
# Response: { "callId": "f47ac10b-...", "status": "queued" }
# Poll: GET https://api.voxplo.ai/v1/agent/calls/{callId}
```

### Add the MCP server (Claude / Cursor)

```bash
# Option 1: local stdio MCP (Node 18+)
npx voxplo-mcp
# Set VOXPLO_API_KEY env var; configure in claude_desktop_config.json or .cursor/mcp.json

# Option 2: hosted connector (nothing to install)
# In Claude: Settings > Connectors > Add custom connector
# URL: https://mcp.voxplo.ai/mcp
# Authorize with your bys_ak_ key when prompted
```