Quickstart

Build production voice agents with StateSet.

Authenticate, verify runtime health, make the first call, connect inbound telephony, and prepare the launch controls a business needs before production traffic.

Request API key Start building Endpoint guides Authentication Production readiness

Runtime APIBearer tenant keys

Admin APIx-admin-key

TelephonyTwilio signatures

SpecsOpenAPI 3.1

Before you start

1Tenant runtime key

Create or request the tenant API key for the environment you are testing.

2Phone route

Confirm the outbound caller ID or inbound Twilio number maps to the right tenant and agent.

3Webhook URL

Use an HTTPS endpoint that can preserve the public URL Twilio signs.

4Launch owner

Identify who approves prompts, tools, fallback behavior, and escalation rules.

Common use cases

Support

Inbound support triage

Answer common questions, authenticate callers, collect structured context, and hand off sensitive issues.

Revenue

Outbound follow-up

Recover missed calls, qualify opportunities, confirm appointments, and reconcile the outcome in call logs.

1. Set the base URL and API key

export STATESET_VOICE_BASE_URL="https://voice.stateset.app"
export STATESET_VOICE_API_KEY="sk_live_..."

Tenant runtime requests use Authorization: Bearer. Admin automation uses x-admin-key.

2. Check readiness

curl -sS "https://voice.stateset.app/health/ready"

3. Make the first call

POST /api/v1/make-call

curl -sS -X POST "https://voice.stateset.app/api/v1/make-call" \
  -H "Authorization: Bearer ${STATESET_VOICE_API_KEY}" \
  -H "content-type: application/json" \
  -d '{
    "to": "+15555555678",
    "from": "+15555551234",
    "agent_key": "support_primary"
  }'

Expected result: persist the returned call identifier in your system, then reconcile it against /api/v1/call-logs and /api/v1/voice-sessions before retrying or creating another call.

4. Connect inbound calls

Configure Twilio to send inbound voice traffic to /api/v1/incoming-call, verify X-Twilio-Signature, and route each number to the correct tenant and agent.

Twilio setting	Production value
Voice webhook	`https://voice.stateset.app/api/v1/incoming-call`
HTTP method	`POST`
Signature header	`X-Twilio-Signature`
Fallback behavior	Transfer, callback task, or safe message when the agent cannot continue.

5. Inspect outcomes

curl -sS "https://voice.stateset.app/api/v1/call-logs?limit=25" \
  -H "Authorization: Bearer ${STATESET_VOICE_API_KEY}"

curl -sS "https://voice.stateset.app/api/v1/voice-sessions?limit=25" \
  -H "Authorization: Bearer ${STATESET_VOICE_API_KEY}"

Enterprise launch checklist

Security

Confirm tenant API keys and admin keys are stored separately.

Coverage

Run synthetic calls for each supported intent and handoff path.

Telemetry

Verify Twilio signatures, stream token rotation, call logs, voice sessions, and webhook delivery.

Contract

Review /api-docs/public.json and /api-docs/admin.json for generated clients.