> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# StateSet Voice

> Production AI voice agents over Twilio and OpenAI Realtime — multi-tenant, streaming, observable.

# StateSet Voice

Production-grade AI voice agents over **Twilio** and the **OpenAI Realtime API**, written in
Rust. Multi-tenant, streaming, and observable.

```
 Caller ──PSTN / SIP──▶ Twilio
                          │ signed webhook
                          ▼
                  StateSet Voice  ◀──Realtime WS──▶ OpenAI Realtime
                    │    │    │
        tool call ──┘    │    └── signed webhook ──▶ your receiver
        (your backend)   │
                         └── persisted ──▶ VoiceSession + transcripts
```

A browser call uses the same media protocol and pipeline as a phone call, so
[web calls](/stateset-voice/sdks#web-sdk-browser-calls) get the whole platform — agents, custom
tools, transfers, evals, billing — with nothing extra to configure.

## Capabilities

<CardGroup cols={2}>
  <Card title="Telephony" icon="phone">
    Twilio REST plus webhooks with signature validation, inbound and outbound PSTN, and a
    WebSocket media bridge.
  </Card>

  <Card title="Realtime voice" icon="waveform">
    OpenAI Realtime bridge with WebSocket media streaming, plus optional ElevenLabs TTS as the
    audio output provider.
  </Card>

  <Card title="Live supervision" icon="headset">
    Monitor, whisper, barge, escalate, and end an in-flight session.
  </Card>

  <Card title="Custom tools" icon="wrench">
    Bring your own backend — a JSON-schema function plus an HTTPS endpoint, invoked mid-call.
  </Card>
</CardGroup>

Also included: a function registry for business logic (auth, subscriptions, orders, returns,
exchanges, logistics), multi-tenant configuration, Kafka event streaming, and voice activity
detection with per-tenant tuning.

## Production surface

| Area              | What ships                                                         |
| ----------------- | ------------------------------------------------------------------ |
| **Rate limiting** | Token bucket, per-IP and per-tenant, with automatic bucket cleanup |
| **Metrics**       | Prometheus with pre-configured Grafana dashboards                  |
| **Health**        | Kubernetes liveness and readiness probes                           |
| **API docs**      | OpenAPI 3.0 with interactive Swagger UI at `/swagger-ui`           |
| **Resilience**    | Exponential-backoff retries, plus a circuit breaker on ElevenLabs  |
| **Debugging**     | Real-time log broadcast over WebSocket                             |
| **Shutdown**      | Graceful, with resource cleanup                                    |

## Stack

Axum 0.7 on Tokio, SQLx against PostgreSQL for tenant configuration (with an in-memory
fallback for development), DashMap for rate-limit and session state, Tokio-Tungstenite for
WebSockets, RDKafka for event streaming, and Utoipa for the OpenAPI spec.

Twilio signature validation uses HMAC with constant-time comparison, so it is resistant to
timing attacks.

## Getting started

```bash theme={null}
cp .env.example .env
# add your credentials
docker-compose up -d

curl http://localhost:5050/health
```

The Compose stack brings up the server, PostgreSQL, Kafka, Prometheus, Alertmanager, and
Grafana.

| Service      | URL                                |
| ------------ | ---------------------------------- |
| Phone server | `http://localhost:5050`            |
| Swagger UI   | `http://localhost:5050/swagger-ui` |
| Prometheus   | `http://localhost:9090`            |
| Alertmanager | `http://localhost:9093`            |

Rust 1.75+ is recommended; Docker 24+ for the containerised path.

## Next

<CardGroup cols={2}>
  <Card title="Build your first agent" icon="rocket" href="/stateset-voice/quickstart">
    End to end, from a phone number to a working agent.
  </Card>

  <Card title="API" icon="code" href="/stateset-voice/api">
    Call control, sessions, supervisor actions, admin.
  </Card>

  <Card title="SDKs" icon="cube" href="/stateset-voice/sdks">
    TypeScript, Python, and browser web calls.
  </Card>

  <Card title="Webhooks" icon="bell" href="/stateset-voice/webhooks">
    The event catalog and signature verification.
  </Card>

  <Card title="Configuration" icon="gear" href="/stateset-voice/configuration">
    Tenants, auth transport, audio providers, VAD.
  </Card>

  <Card title="MCP server" icon="plug" href="/stateset-voice/mcp-server">
    Drive the platform from Claude.
  </Card>
</CardGroup>