Al terminar esta guía habrás comprobado tu clave y creado una llamada con la API de Agents. Todo corre en modo de prueba: no se marca ningún número y no se factura nada.
Antes de empezar
Necesitas:
- Una cuenta de Qomni (prueba gratis de 14 días, sin tarjeta).
- Una terminal con
curl, o Python 3.9 o superior, o Node.js 18 o superior.
-
Crea una clave de prueba
Regístrate en qomni.ai. En Settings → API keys de tu workspace, crea una clave de prueba: empieza por
sk_agents_test_. Guárdala en una variable de entorno de tu shell:export QOMNI_KEY="sk_agents_test_…"Los ejemplos de esta página la leen de
QOMNI_KEY. No la escribas en tu código ni la subas a un repositorio. -
Instala lo necesario
Con cURL no necesitas nada más. En Python usamos
requests; Node.js ya traefetch, ytsxejecuta TypeScript sin compilarlo.pip install requestsnpm install --save-dev tsx -
Comprueba la clave
Pide a la API el contexto de tu clave. Guarda el código en
ping.pyoping.mts, o pega el comando de cURL en tu terminal:curl https://api.qomni.ai/agents/v1/ping \ -H "Authorization: Bearer $QOMNI_KEY"import os import requests key = os.environ["QOMNI_KEY"] response = requests.get( "https://api.qomni.ai/agents/v1/ping", headers={"Authorization": f"Bearer {key}"}, timeout=10, ) if not response.ok: error = response.json()["error"] raise SystemExit(f"{error['code']}: {error['message']}") print(response.json())const response = await fetch("https://api.qomni.ai/agents/v1/ping", { headers: { Authorization: `Bearer ${process.env.QOMNI_KEY}` }, }); if (!response.ok) { const { error } = await response.json(); throw new Error(`${error.code}: ${error.message}`); } console.log(await response.json());Ejecútalo:
python ping.pynpx tsx ping.mtsUn
200trae tu workspace ylivemode: false, porque la clave es de prueba. La respuesta puede traer más campos: ignora los que no conozcas.200 OKjson { "product": "agents", "tenant": "acme", "cell": "co1", "region": "co", "livemode": false }Un
401significa que la clave falta o no es válida: el campocodedel error te dice cuál de las dos. Mira Errores. -
Crea una llamada
Pide que un agente llame a un número. En modo de prueba,
+15005550001es un número mágico que siempre terminacompleted. Guarda el código encreate_call.pyocreate_call.mtsy ejecútalo como en el paso anterior:curl https://api.qomni.ai/agents/v1/calls \ -H "Authorization: Bearer $QOMNI_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "+15005550001" }'import os import requests key = os.environ["QOMNI_KEY"] response = requests.post( "https://api.qomni.ai/agents/v1/calls", headers={"Authorization": f"Bearer {key}"}, json={"to": "+15005550001"}, timeout=10, ) if not response.ok: error = response.json()["error"] raise SystemExit(f"{error['code']}: {error['message']}") call = response.json() print(call["id"], call["status"])const url = "https://api.qomni.ai/agents/v1/calls"; const response = await fetch(url, { method: "POST", headers: { Authorization: `Bearer ${process.env.QOMNI_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ to: "+15005550001" }), }); if (!response.ok) { const { error } = await response.json(); throw new Error(`${error.code}: ${error.message}`); } const call = await response.json(); console.log(call.id, call.status);La API responde
201con la llamada:201 Createdjson { "id": "call_01k8x2m4v7q9r3t5w8y1z0a2b4", "to": "+15005550001", "status": "completed", "livemode": false, "cell": "co1", "region": "co", "created_at": "2026-10-21T15:04:05+00:00" }
Deberías ver
La llamada existe, con estado completed, y ningún teléfono sonó: así
funciona el modo de prueba. Acabas de hacer las dos
llamadas que hace cualquier integración con Agents: comprobar la clave y crear
una llamada. GET /calls te las devuelve, la más reciente primero.
Si en el paso 3 viste 401, el campo code dice por qué: api_key_missing
si falta el header, api_key_malformed si la clave está mal copiada,
api_key_invalid si fue revocada.
Siguiente paso
Cambia la clave de prueba por una real (sk_agents_live_…) y el mismo código
hace llamadas de verdad. Antes de eso, pon al agente a conversar con tu app:
- Referencia de Agents: cada endpoint, campo y error.
- Idempotencia y reintentos: reintenta sin crear dos llamadas.