Guide: voice AI

Español: Guía: voz IA.

A voice-AI agent holds the conversation on a campaign's calls. You create it in draft, rehearse it in a sandbox conversation that places no call, then take it live. The shapes are in the API Reference; experiments and drift are in Voice AI A/B experiments and drift.

Create an agent

curl -s -X POST $API/v1/ai/agents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "balance-reminder", "disclosure": {"text": "Hi, this is an automated assistant calling for Example Co."}}'

• It is created draft at policy_version: 1; a duplicate name is 409.
• The opening disclosure.text is mandatory and content-checked: it must identify the voice as automated (English or Spanish). It becomes immutable the first time the agent goes live.
• A human_requested hand-off rule is always present and locked.
• voice.voice_id, when given, must come from GET /v1/ai/voices (otherwise 422).
• Takes a dd_ key or an account_admin login.

Rehearse without a call

curl -s -X POST $API/v1/ai/agents/$AGENT_ID/test \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Who is this?"}'

Omit session_id to start; echo the one you get back to continue the thread. No call, no conversation row, no dial. Every turn spends inference budget, so it is quota-limited: over the quota is 429 with Retry-After, and 503 when the sandbox runtime is not available. This is the AI sandbox; it is separate from the simulated calls of dd_test_ keys.

Operate it

Goal	Endpoint
Which campaigns may play artificial voice now	GET /v1/ai/eligibility
Pause / resume all AI dialing (kill-switch, tenant-wide)	POST /v1/ai/pause, POST /v1/ai/resume, state at GET /v1/ai/status
Today's operating metrics	GET /v1/ai/metrics/today
Conversations, transcript and outcome	GET /v1/ai/conversations, GET /v1/ai/conversations/{id}
A supervisor steps in on a live conversation	POST /v1/ai/conversations/{id}/takeover
Drift alerts	GET /v1/ai/agents/drift — and the ai.drift.detected webhook

Pausing is immediate for new originations; conversations in flight continue until a supervisor takes over. A paused tenant blocks every AI origination fail-closed.