Developer cookbook

Gestiona 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. Vas a:

1. Crear un agente con un prompt y una voz.
2. Aprovisionar (o traer) un número de teléfono y asignar el agente como su controlador de llamadas entrantes.
3. Llamar al número. Observar 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. Crea un agente#

Un agente reúne el prompt, la voz y el nivel de producto que gestionarán la llamada. 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. Obtén un número de teléfono#

Si solo necesitas un número al que llamar, aprovisiona un número de demostración del grupo 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 E.164. Los números de demostración comienzan con status="provisioning" y pasan a active en unos segundos; consulta periódicamente GET /v1/phone-numbers/{id} para observar la transición si te interesa.

3. Asigna 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. También puedes establecer outbound_agent_id en el mismo PATCH para que el número también esté listo para realizar llamadas salientes.

4. Atiende una llamada#

Llama al 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, con el tiempo, una URL de grabación y una calificación de IA.

5. Revisa 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 y 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.

Próximos pasos#