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

# Inicio rápido (API)

> Responde tu primera llamada telefónica con un agente de IA en cuatro llamadas REST.

Esta guía te muestra las cuatro llamadas REST necesarias para atender
tu primera llamada telefónica con un agente de IA.

<Info>
  Necesitarás una [cuenta de ThunderPhone](https://app.thunderphone.com).
  Registrarte es gratis y toma menos de un minuto. ¿Prefieres hacer clic en lugar de usar curl?
  La [guía de inicio rápido del dashboard](/es/quickstart-dashboard) te permite atender la misma
  primera llamada sin escribir código.
</Info>

## Paso 1: Obtén una clave de API

<Steps>
  <Step title="Inicia sesión">
    Abre [app.thunderphone.com](https://app.thunderphone.com).
  </Step>

  <Step title="Ve a Claves">
    Ve a **Organización → Claves** en el dashboard.
  </Step>

  <Step title="Crea una clave">
    Haz clic en **Crear clave**, asígnale un nombre y copia el
    valor `sk_live_...`. La clave sin procesar se muestra **solo una vez**; guárdala
    de inmediato en tu administrador de secretos.
  </Step>
</Steps>

<Tip>
  ¿Atascado? [Crear una clave de API de servidor](/es/guides/api-keys) explica
  este flujo paso a paso, y el copiloto integrado puede
  resaltar cada control para ti en tiempo real.
</Tip>

A lo largo de esta guía, sustituye `sk_live_YOUR_API_KEY` por el valor que
acabaste de copiar. La clave identifica automáticamente a tu organización, por lo que
nunca necesitas incluir un id de organización en las URL.

## Paso 2: Crea un agente

Un agente define cómo la IA gestiona las conversaciones: prompt, voz,
nivel de producto, herramientas y elegibilidad para widgets.

<CodeGroup>
  ```bash cURL 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":   "Customer Support",
      "prompt": "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
      "voice":  "john",
      "product": "spark"
    }'
  ```

  ```python Python theme={null}
  import os, requests

  agent = requests.post(
      "https://api.thunderphone.com/v1/agents",
      headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
      json={
          "name":   "Customer Support",
          "prompt": "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
          "voice":  "john",
          "product": "spark",
      },
  ).json()
  print("Agent id:", agent["id"])
  ```

  ```javascript Node.js theme={null}
  const agent = await fetch("https://api.thunderphone.com/v1/agents", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.THUNDERPHONE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name:    "Customer Support",
      prompt:  "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
      voice:   "john",
      product: "spark",
    }),
  }).then((r) => r.json());
  console.log("Agent id:", agent.id);
  ```
</CodeGroup>

<Tip>
  Niveles de producto: `spark` está optimizado para el costo, `bolt` para la velocidad y
  `storm-base` / `storm-extra` para la inteligencia en prompts complejos. Consulta
  [Agentes](/api-reference/agents#product-tiers-at-a-glance) para ver la comparación
  completa.
</Tip>

## Paso 3: Aprovisiona un número de teléfono

Esta llamada solicita un número al grupo de demostración de ThunderPhone y asigna tu
nuevo agente como controlador de llamadas entrantes. (Para traer tu propio número desde un proveedor
de VoIP, consulta [conexiones VoIP](/api-reference/voip-connections)
en su lugar.)

<CodeGroup>
  ```bash cURL theme={null}
  # First provision
  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"}'

  # Then assign the agent you created in Step 2
  curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/<id-from-previous> \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"inbound_agent_id": 12}'
  ```

  ```python Python theme={null}
  number = requests.post(
      "https://api.thunderphone.com/v1/phone-numbers",
      headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
      json={"area_code": "415"},
  ).json()
  requests.patch(
      f"https://api.thunderphone.com/v1/phone-numbers/{number['id']}",
      headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
      json={"inbound_agent_id": agent["id"]},
  )
  print("Your ThunderPhone number:", number["number"])
  ```
</CodeGroup>

Tu nuevo número comienza con `status="provisioning"` y cambia a
`active` en unos segundos; para cuando cierres el navegador, el número estará
listo para recibir llamadas.

## Paso 4 (opcional): Configura un webhook

Para eventos en tiempo real (enrutamiento dinámico de llamadas, procesamiento posterior a la llamada), agrega
un endpoint de webhook. Suscríbete solo a los eventos que necesites.

```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Prod webhook",
    "url":    "https://your-server.com/thunderphone-webhook",
    "events": ["telephony.incoming", "telephony.complete"]
  }'
```

La respuesta contiene un `secret` de un solo uso; cópialo en tu gestor
de secretos. Usa ese secreto para verificar el encabezado
`X-ThunderPhone-Signature` en las solicitudes entrantes (consulta
[descripción general de webhooks](/es/webhooks/overview)).

## Paso 5: Prueba tu agente

Llama al número que acabas de aprovisionar. El agente responde, se presenta
y sigue tu prompt.

Inspecciona la llamada después de que termine:

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

Consulta una llamada específica para obtener la transcripción y la URL de la grabación:

```bash theme={null}
curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

***

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Agrega herramientas de funciones" icon="screwdriver-wrench" href="/es/tools/overview">
    Permite que tu agente llame a tus API durante una conversación.
  </Card>

  <Card title="Realiza llamadas salientes" icon="arrow-up-right" href="/api-reference/outbound-calls">
    Activa llamadas desde tu propio código.
  </Card>

  <Card title="Gestiona webhooks" icon="bolt" href="/es/webhooks/overview">
    Reacciona a eventos de llamadas en tiempo real.
  </Card>

  <Card title="Referencia completa de la API" icon="book" href="/api-reference/introduction">
    Todos los endpoints públicos, documentados.
  </Card>
</CardGroup>