Guía: voz IA

English version: Guide: voice AI.

Un agente de voz IA lleva la conversación en las llamadas de una campaña. Lo creas en draft, lo ensayas en una conversación sandbox que no hace ninguna llamada y luego lo pones en vivo. Las formas están en la Referencia de la API; los experimentos y la deriva están en Experimentos A/B de voz IA y deriva.

Crea un agente

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."}}'

• Se crea en draft con policy_version: 1; un name duplicado es 409.
• El disclosure.text de apertura es obligatorio y se valida por contenido: debe identificar la voz como automatizada (inglés o español). Pasa a ser inmutable la primera vez que el agente pasa a live.
• Una regla de traspaso human_requested siempre está presente y bloqueada.
• voice.voice_id, si se da, debe salir de GET /v1/ai/voices (si no, 422).
• Exige una clave dd_ o una sesión account_admin.

Ensaya sin llamada

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?"}'

Omite session_id para empezar; devuélvelo tal cual para continuar el hilo. Sin llamada, sin fila de conversación, sin marcación. Cada turno gasta presupuesto de inferencia, así que tiene cuota: pasarse es 429 con Retry-After, y 503 cuando el runtime del sandbox no está disponible. Este es el sandbox de IA; es distinto de las llamadas simuladas de las claves dd_test_.

Opéralo

Objetivo	Endpoint
Qué campañas pueden reproducir voz artificial ahora	GET /v1/ai/eligibility
Pausar / reanudar toda la marcación IA (interruptor, de toda la cuenta)	POST /v1/ai/pause, POST /v1/ai/resume, estado en GET /v1/ai/status
Métricas operativas de hoy	GET /v1/ai/metrics/today
Conversaciones, transcripción y resultado	GET /v1/ai/conversations, GET /v1/ai/conversations/{id}
Un supervisor interviene en una conversación en vivo	POST /v1/ai/conversations/{id}/takeover
Alertas de deriva	GET /v1/ai/agents/drift — y el webhook ai.drift.detected

Pausar es inmediato para las nuevas originaciones; las conversaciones en curso continúan hasta que un supervisor interviene. Una cuenta en pausa bloquea toda originación IA con cierre por defecto.