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

Idempotencia y reintentos

Qué es una petición idempotente, cuándo es seguro reintentar una llamada a Qomni y cómo usar el header Idempotency-Key.

Una petición es idempotente cuando repetirla produce el mismo resultado que hacerla una sola vez. Listar tus llamadas es idempotente: lo haces diez veces y la lista no cambia. Crear una llamada no lo es: la creas dos veces y el agente marca dos veces al mismo cliente.

Las redes fallan, así que tu código tiene que reintentar. El problema es reintentar una petición que crea algo sin crearlo dos veces.

Por qué el problema existe

El caso peligroso no es cuando la petición falla. Es cuando no sabes si falló:

POST /agents/v1/callscrea call_01… y el agente marcala respuesta se pierdereintento: POST /agents/v1/callscrea call_02… y el agente marca otra vez201 call_02…Tu servidorAgents APITu servidorAgents API
  1. Tu servidor envía POST /agents/v1/calls.
  2. Qomni crea la llamada y el agente marca al cliente.
  3. La respuesta se pierde por el camino (se cae la conexión, se agota tu tiempo de espera).
  4. Tu código ve un error de red y reintenta.
  5. Qomni crea una segunda llamada y el cliente recibe dos.

Desde tu lado, los pasos 2 y 3 son invisibles: un fallo de red antes de la respuesta se ve igual que un fallo de red antes de que la petición llegara. Ningún cliente puede distinguirlos solo.

Cómo se resuelve

La solución es que tú nombres cada operación. Envías un header Idempotency-Key con un valor que eliges, y repites ese mismo valor en cada reintento de la misma operación. Así la API puede reconocer el reintento y devolver el resultado de la primera vez en lugar de crear otra llamada.

La clave buena sale de tus propios datos: el id del pedido que se recuerda, el id de la cita que se confirma, el id del cliente más la fecha. Una clave aleatoria generada en cada reintento no sirve, porque cada reintento llevaría una clave nueva.

Cuándo reintentar

Qué recibiste Reintenta Por qué
503 origin_unavailable Sí, con backoff La celda no recibió la petición. No se hizo nada.
429 rate_limited Sí, tras Retry-After segundos La petición no se procesó.
Error de conexión antes de enviar el cuerpo Sí La petición no llegó.
Tiempo de espera agotado esperando la respuesta Sólo con Idempotency-Key Puede haber llegado y haberse procesado.
4xx distinto de 429 No La petición está mal. Reintentarla igual fallará igual.

Usa un backoff exponencial: espera 1 segundo, luego 2, luego 4, con un máximo de cinco intentos. Reintentar sin esperar sólo empeora una celda que ya está saturada.

Límites

  • Las peticiones GET ya son idempotentes. No necesitan el header.
  • La clave identifica una operación, no un recurso. Dos pedidos distintos llevan dos claves distintas aunque llamen al mismo número.
  • La clave no cambia lo que hace la petición. Si reintentas con la misma clave y otro cuerpo, el cuerpo que cuenta es el de la primera vez.

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