> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  ¿Vas a crear tu primer agente manualmente? El dashboard te guía por este mismo
  flujo — crear el agente, agregar un número, simular, revisar — con un
  asistente guiado. Comienza con la
  [guía de inicio rápido del dashboard](/es/quickstart-dashboard).
</Note>

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](/api-reference/agents) para ver todos los campos
de configuración; lo mínimo es:

```bash theme={null}
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.

<Tip>
  Elige `spark` para preguntas y respuestas simples al menor costo, y `bolt` cuando
  la velocidad sea lo más importante. Actualiza a `storm-base-with-ack` cuando tu prompt
  necesite un razonamiento más profundo y pueda tolerar una frase de relleno de medio segundo
  mientras el modelo piensa. Consulta los
  [niveles de producto](/api-reference/agents#product-tiers-at-a-glance).
</Tip>

## 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:

```bash theme={null}
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}`](/api-reference/phone-numbers#retrieve-a-phone-number)
para observar la transición si te interesa.

<Note>
  Para producción, omite los números de demostración y
  [trae tus propios números mediante VoIP](/es/guides/bring-your-own-numbers).
  Los números de demostración solo admiten llamadas entrantes y tienen un límite de volumen.
</Note>

## 3. Asigna el agente

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

```bash theme={null}
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`](/api-reference/calls#list-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:

```bash theme={null}
curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

Obtén la transcripción:

```bash theme={null}
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):

```bash theme={null}
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`](/es/webhooks/events),
recibirás los mismos datos como un POST en tu servidor; consulta
[call.complete](/es/webhooks/call-complete).

***

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Configuración dinámica por llamada" icon="bolt" href="/es/guides/dynamic-call-config">
    Elige un agente diferente para cada persona que llama según el número de teléfono
    o una lógica personalizada en un webhook.
  </Card>

  <Card title="Agregar integraciones de herramientas" icon="screwdriver-wrench" href="/es/guides/build-tool-integration">
    Permite que el agente llame a tus API durante la conversación.
  </Card>

  <Card title="Recibir webhooks de call.complete" icon="bolt" href="/es/webhooks/call-complete">
    Envía cada llamada finalizada a tu pipeline de CRM o analítica.
  </Card>

  <Card title="Evaluación con IA e informes de problemas" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    Evalúa cada llamada automáticamente y envía las marcadas para revisión.
  </Card>
</CardGroup>