Open in
Inicio rápido (API)
Responde tu primera llamada telefónica con un agente de voz con IA: obtén una clave de API, crea un agente, aprovisiona un número de teléfono y realiza una llamada de prueba en vivo, todo mediante la API REST.
Esta guía te muestra las cuatro llamadas REST necesarias para responder tu primera llamada telefónica con un agente de IA.
Paso 1: Obtén una clave API
- Iniciar sesión
Abre app.thunderphone.com.
- Ve a Claves
Ve a Organización → Claves en el panel.
- 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.
A lo largo de esta guía, reemplaza sk_live_YOUR_API_KEY por el valor que
acabaste de copiar. La clave identifica automáticamente a tu organización, así 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);Paso 3: Aprovisiona un número de teléfono
Esta llamada solicita un número a 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 pasa 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 administrador
de secretos. Usa ese secreto para verificar el encabezado X-ThunderPhone-Signature-V2
en las solicitudes entrantes (consulta la
descripción general de webhooks).
Paso 5: Prueba tu agente
Llama al número que acabas de aprovisionar. El agente contesta, 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"Accede a 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"