Inicio rápido (API)

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

Necesitarás una cuenta de ThunderPhone. 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 te permite atender la misma primera llamada sin escribir código.

Paso 1: Obtén una clave de API

Inicia sesión

Abre app.thunderphone.com.

Ve a Claves

Ve a Organización → Claves en el dashboard.

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.

¿Atascado? Crear una clave de API de servidor explica este flujo paso a paso, y el copiloto integrado puede resaltar cada control para ti en tiempo real.

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.

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

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"])

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);

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 para ver la comparación completa.

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 en su lugar.)

# 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}'

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"])

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.

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

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:

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:

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

Agrega herramientas de funciones

Permite que tu agente llame a tus API durante una conversación.

Realiza llamadas salientes

Activa llamadas desde tu propio código.

Gestiona webhooks

Reacciona a eventos de llamadas en tiempo real.

Referencia completa de la API

Todos los endpoints públicos, documentados.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Paso 1: Obtén una clave de API

Paso 2: Crea un agente

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

Paso 4 (opcional): Configura un webhook

Paso 5: Prueba tu agente

Próximos pasos

Agrega herramientas de funciones

Realiza llamadas salientes

Gestiona webhooks

Referencia completa de la API

​Paso 1: Obtén una clave de API

​Paso 2: Crea un agente

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

​Paso 4 (opcional): Configura un webhook

​Paso 5: Prueba tu agente

​Próximos pasos

Agrega herramientas de funciones

Realiza llamadas salientes

Gestiona webhooks

Referencia completa de la API

Paso 1: Obtén una clave de API

Paso 2: Crea un agente

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

Paso 4 (opcional): Configura un webhook

Paso 5: Prueba tu agente

Próximos pasos