Tutorial
Build a production-shaped voice agent.
Follow an end-to-end path from agent contract to outbound calls, inbound telephony, observability, and launch acceptance criteria.
Target architecture
Start with one tenant, one approved agent, one inbound phone route, and one outbound workflow. Keep runtime credentials, admin credentials, and webhook consumers owned by separate deployment surfaces.
Customer-facing calls
Uses tenant bearer auth to create outbound calls and read sessions, call logs, and evaluations.
Internal automation
Uses admin auth to configure tenants, agent versions, phone routes, and rollout gates.
Business systems
Receives webhook events, deduplicates delivery, and writes outcomes into CRM, ticketing, or analytics systems.
1. Define the agent contract
| Decision | Example | Why it matters |
|---|---|---|
| Supported intents | Appointment confirmation, order status, missed-call recovery | Limits what the agent can promise and what tools it may call. |
| Escalation rules | Payment, identity failure, complaint, repeated low confidence | Protects customers and keeps regulated or sensitive work human-reviewed. |
| Success signals | Resolved, transferred, callback created, no answer, failed authentication | Gives operators and analytics teams a stable outcome model. |
| Launch gates | 20 synthetic calls, 95% signature verification, no duplicate outbound calls | Turns voice launch from a demo into a controlled production workflow. |
2. Configure runtime behavior
Use admin automation to attach the model, voice, prompt key, and telephony defaults to the tenant or agent version that will receive traffic.
curl -sS -X PUT "https://voice.stateset.app/api/v1/admin/tenants/${TENANT_ID}/runtime-config" \
-H "x-admin-key: ${STATESET_ADMIN_API_KEY}" \
-H "content-type: application/json" \
-d '{
"model": "gpt-realtime",
"voice": "alloy",
"system_prompt_key": "front_desk_v1",
"webhook_url": "https://api.example.com/webhooks/stateset-voice"
}'3. Start the first outbound call
Use POST /api/v1/make-call to create the first customer-facing outbound workflow.
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": "front_desk",
"greeting": "Hi, this is Acme calling to confirm your appointment."
}'4. Receive inbound traffic
Configure Twilio to POST signed inbound calls to StateSet Voice. Route numbers to tenants and agents before production traffic moves over.
| Twilio field | Value |
|---|---|
| Voice webhook | https://voice.stateset.app/api/v1/incoming-call |
| HTTP method | POST |
| Security | Validate X-Twilio-Signature and keep fallback routing configured. |
| Monitoring | Watch readiness, call status callbacks, media stream setup, and session creation. |
5. Observe 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}"Review call status, duration, transcript turns, tool calls, escalations, summaries, tags, and evaluation score before broadening the rollout.
Production acceptance criteria
Tenant keys, admin keys, Twilio auth token, and webhook secrets are stored separately and rotated by environment.
Each supported intent has a synthetic call, expected transcript outcome, and approved escalation path.
Clients retry only safe failures, webhook consumers deduplicate by event ID or call/session ID, and duplicate outbound calls are blocked.
Dashboards track call creation, answer rate, transfer rate, failed webhooks, error rate, and provider health.