Saltar al contenido
Qomni

Agents

Crea un agente, dale voz y ponlo a atender: REST para las llamadas y un WebSocket para hablar con él en tiempo real desde tu app.

URL base
https://api.qomni.ai/agents/v1
Clave
sk_agents_test_…
curl https://api.qomni.ai/agents/v1/calls \
  -H "Authorization: Bearer sk_agents_test_…"

Novedades

El edge y las celdas

Dónde viven los datos de tu workspace, qué hace el edge con cada petición y por qué tu código nunca elige región.

Los datos de cada workspace viven en una celda: una copia completa de la plataforma en una región (us1 en Estados Unidos, co1 en Colombia, br1 en Brasil). Delante de todas las celdas hay un solo punto de entrada, el edge, que recibe cada petición y la lleva a la celda correcta.

Para ti esto significa una cosa: la API vive en un único host, api.qomni.ai, con el producto y la versión en la ruta (https://api.qomni.ai/agents/v1), y la URL nunca lleva región. Tu código es el mismo para un cliente en Bogotá y para uno en São Paulo.

La app web también tiene un único host, app.qomni.ai: el portal y la página de cada producto dentro de cada workspace, en app.qomni.ai/{workspace}/{producto} (por ejemplo app.qomni.ai/acme/agents). Las direcciones antiguas de cada producto (agents.qomni.ai/acme…) redirigen ahí.

Por qué hay celdas

Las grabaciones y transcripciones de llamadas tienen reglas legales distintas en cada país. Guardar los datos de un workspace en su propio país hace más simple cumplirlas y más corto el camino de cada petición. La alternativa, una sola base de datos para todo el mundo, obligaría a elegir un país para todos.

Qomni eligió no trasladar esa decisión a tu código. Por eso la celda va dentro de la clave de API (sk_agents_live_co1_…) y el edge la lee de ahí. No hay un parámetro de región, ni un host por país, ni nada que puedas configurar mal.

El recorrido de una petición

sk_agents_live_co1_…token de 10 sTu servidorEdgeCelda co1apiCelda us1Celda br1
  1. El edge identifica la petición. Lee el prefijo de la clave (sk_<product>_<mode>_<cell>_…) y comprueba su checksum. Una clave mal copiada se rechaza aquí, con 401 api_key_malformed, sin llegar a ningún servidor.
  2. Encuentra la celda. Con una clave de API, la celda está en la clave. En la app web, una página de producto (app.qomni.ai/{workspace}/{producto}/…) va a la celda del workspace de su ruta; el resto de app.qomni.ai (tus workspaces, los ajustes, el inicio de sesión) no vive en ninguna celda. Una dirección antigua de producto (agents.qomni.ai/acme/…) no llega a ninguna celda: el edge responde 308 hacia la misma página en app.qomni.ai/acme/agents/….
  3. Firma un token de edge. Vale 10 segundos, sirve para una sola petición y va ligado al host público, a la celda y a tu dirección IP.
  4. Reenvía la petición al servicio de esa celda que sirve la ruta, con la ruta tal cual. Cuál es ese servicio no se ve desde fuera. El origen sólo acepta peticiones que traigan el token: nadie puede saltarse el edge llamando a un origen directamente.

La respuesta trae el header X-Request-Id. Guárdalo en tus logs: es lo que soporte usa para encontrar tu petición.

Errores del edge

Tienen la misma forma que los errores de la API.

Código Cuándo
api_key_missing, api_key_malformed Falta el header Authorization, o la clave no tiene la forma o el checksum esperados.
realtime_session_invalid La sesión del WebSocket no existe o expiró. Vale 60 segundos.
origin_unavailable La celda no respondió. No se hizo nada: reintenta con backoff.
unknown_api 404: el primer segmento de la ruta en api.qomni.ai no nombra ninguna API (/payroll/v1/…).
api_host_moved 404: el host es la dirección antigua de la API (agents-api.qomni.ai). Usa https://api.qomni.ai/agents/v1.
not_found, method_not_allowed La ruta o el método no existen en esa API.
product_host_moved 410: un método distinto de GET o HEAD en la dirección antigua de un producto (agents.qomni.ai). Envía la petición a app.qomni.ai/{workspace}/{producto}.
host_moved 404: el host es la dirección antigua de un producto, que ya no sirve páginas.

Límites

  • Tu código nunca elige la celda. No hay parámetro, host ni header para eso.
  • La dirección antigua de la API (agents-api.qomni.ai) no redirige: responde 404 api_host_moved con la URL base nueva.
  • Una clave sólo vale en su celda. Usarla en otra responde 421 wrong_cell. En la práctica no ocurre: la celda de la clave es la del workspace que la creó.
  • Los datos no se mueven entre celdas. Un workspace nace en una celda y se queda ahí.
  • El edge no guarda ni lee tus datos: sólo enruta y firma.

Ver también

Navegación del sitio

Nuevo

2 de 7 pasos hechosSigue: la plataforma en producción

Qomni está en beta privada

La API y la app todavía no están abiertas. Mira qué está hecho, qué falta y cómo se abre, paso a paso hasta el primer cliente.

Escribe para buscar…

↑↓ moverte↵ abrirEsc para cerrar