Gestionar llamadas entrantes (API)

De principio a fin: configura un agente, asígnalo a un número de teléfono, atiende una llamada e inspecciona la transcripción.

El flujo canónico de "contestar un teléfono con IA", desde tu terminal. Harás lo siguiente:

1. Crear un agente con un prompt y una voz.
2. Aprovisionar (o incorporar) un número de teléfono y asignar el agente como su gestor de llamadas entrantes.
3. Llamar al número. Revisar el registro de llamadas, la transcripción y la grabación.

Total de llamadas a la API: cuatro. Tiempo total: menos de cinco minutos.

1. Crear un agente#

Un agente reúne el prompt, la voz y el nivel de producto que gestionarán la llamada. También puedes configurar límites de llamada, como max_call_duration_seconds y ring_duration_seconds, en el agente. Los agentes también admiten un intro_clip y intro_ring_count para reproducir una introducción pregrabada y hasta dos tonos antes de que el agente hable. Los agentes nuevos también necesitan una zona horaria. Consulta Agentes para ver todos los campos de configuración; lo mínimo es:

curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":    "Acme Support",
    "prompt":  "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
    "voice":   "john",
    "product": "spark"
  }'

Guarda el id devuelto; lo necesitarás en el paso 2.

2. Obtener un número de teléfono#

Si solo necesitas algo al que llamar, obtén un número de ThunderPhone del grupo de números de ThunderPhone:

curl -X POST https://api.thunderphone.com/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415"}'

La respuesta incluye un id y un number en formato E.164. Los números de ThunderPhone comienzan con status="provisioning" y pasan a estar active en unos pocos segundos; consulta repetidamente GET /v1/phone-numbers/{id} para ver la transición si te interesa.

3. Asignar el agente#

Asocia el agente del paso 1 con la dirección entrante del número:

curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'

Eso es todo: el número está activo. Después de que se aprueben las llamadas salientes para tu organización, también puedes establecer outbound_agent_id en el mismo PATCH. Hasta entonces, la API rechaza esa asignación con 400.

Si enrutas las llamadas entrantes mediante un webhook de configuración en lugar de un inbound_agent_id fijo, ese webhook ahora puede devolver una timezone por llamada junto con agent_id y variables.

4. Atender una llamada#

Marca el número desde tu teléfono. El agente contesta, se presenta según tu prompt y comienza la conversación.

Mientras la llamada está en curso, aparece en GET /v1/calls con status="in_progress". Cuando termina, el registro se actualiza con end_reason, duration_seconds, billable_minutes y, finalmente, una URL de grabación y una calificación de IA.

Las llamadas entrantes cuentan para el límite de llamadas simultáneas de tu organización (20 llamadas en curso de forma predeterminada, compartidas con llamadas salientes, web y de prueba). Una llamada que llega cuando se alcanzó el límite se rechaza antes de que el agente responda y se cuelga, no se factura y se registra como una llamada fallida con el motivo de finalización concurrent_call_limit_reached. Envía un correo a support@thunderphone.com si necesitas un límite mayor.

5. Inspecciona los resultados#

Obtén la lista de llamadas recientes:

curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Obtén la transcripción:

curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Y la URL de la grabación (de corta duración, firmada):

curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Si te suscribiste al webhook telephony.complete, recibirás los mismos datos como un POST en tu servidor; consulta call.complete.

Si tu agente tiene campos de extracción configurados, la carga útil de la llamada completada también puede incluir datos extraídos estructurados.

Próximos pasos#