Saltar al contenido principal

Flujo de una llamada con agentes de voz

Esta página describe, a alto nivel, cómo atiende Ocular una llamada telefónica con un agente de voz de IA, tanto cuando la llamada entra desde la red pública como cuando Ocular la origina. Es la base para entender las dos páginas siguientes: cómo un carrier o socio nos entrega llamadas por SIP y cómo Ocular puede devolver una llamada a un destino PSTN.

Piezas​

PiezaRol
Carrier / socioQuien conecta la red telefónica pública (PSTN) con Ocular por SIP. Hoy: un trunk bidireccional para Chile y un trunk de entrada para Estados Unidos.
Borde SIP (FreeSWITCH)Recibe y origina llamadas SIP, negocia códecs y RTP/SRTP, y entrega la señal y el audio al motor. Un perfil SIP por carrier.
Motor de discado (dialer)Servicios que deciden cuándo y a quién marcar, aplican las reglas legales por país, llevan la llamada al agente y registran lo que pasó.
OrquestadorAdaptador entre el motor y el proveedor de agentes de voz conversacional. Reserva sesiones, puentea el audio y ejecuta las herramientas del agente. Cambiar de proveedor no toca el motor ni el borde SIP.
Ocular OSLa plataforma de negocio: proyectos, agentes, herramientas (tools), transferencias, registro de llamadas y webhooks.

Llamada entrante (inbound)​

PSTN ──► Carrier ──SIP INVITE──► FreeSWITCH ──socket──► inbound-gateway ──reserve──► Orquestador ──WS audio──► Agente de voz
(origen, E.164) (DID → tenant, (sesión) (proveedor IA)
reglas, horario) │
└──tools──► Ocular OS (execute-tool)
  1. El carrier envía el INVITE al borde SIP de Ocular. Solo se aceptan orígenes declarados (las direcciones del carrier autorizadas en la red de Ocular). Un INVITE desde un origen no declarado se descarta sin respuesta.
  2. FreeSWITCH valida el número marcado (DID). Debe llegar en formato E.164 (+ y país). Algunos carriers entregan otro formato (por ejemplo, NANP sin +); se normaliza en el borde. Un DID que no se pueda normalizar se rechaza con CALL_REJECTED.
  3. El inbound-gateway toma la llamada por socket de eventos y aplica el default deny: el DID tiene que existir y estar habilitado, el tenant tiene que tener la dirección inbound y el país habilitados, el pack de jurisdicción del país tiene que estar activo. Si algo falta, se cuelga. Luego revisa el horario de atención configurado para ese DID.
  4. Se contesta y se reserva un agente. El gateway contesta la llamada (códec PCMU), crea el intento con direction=inbound y pide al orquestador una sesión (POST /sessions/reserve, idempotente por intento). Si no hay capacidad, aplica la política de desborde del DID: cortesía y colgar, o cola con música y reintentos acotados.
  5. Se puentea el audio. FreeSWITCH abre un audio fork hacia la URL de media que devolvió la reserva: PCM 16 kHz mono, tramas de 20 ms, bidireccional por WebSocket. El agente habla y escucha por ese canal; el audio del cliente nunca sale de la infraestructura de Ocular hacia el proveedor de IA salvo por ese WS cifrado.
  6. El agente conversa y usa herramientas. Cada herramienta del agente es una client tool que el orquestador reenvía a Ocular OS (execute-tool) con el contexto de la llamada (intento, conversación, número del llamante). El OS ejecuta la lógica de negocio: agenda, consulta, transferencia asistida, etc. El modelo nunca ve números de teléfono ni credenciales.
  7. Cierre. Cuando el agente termina (end_call) o la persona cuelga, el orquestador envía la disposición estructurada al motor, el motor libera la sesión, emite los eventos de la llamada al bus y, si el tenant tiene webhooks, los entrega firmados (HMAC) al OS.

Llamada saliente (outbound)​

Ocular OS ──POST /dial-jobs──► API ──► Scheduler ──► Pacer ──► Originator ──ESL originate──► FreeSWITCH ──SIP──► Carrier ──► PSTN
(reglas legales, (capacidad, (idempotente (perfil del trunk,
ventana, topes) CPS, canales) por intento) caller ID)
│ contesta
└──reserve + WS audio──► Orquestador ──► Agente
  1. El OS pide una llamada con POST /dial-jobs (una orden por contacto, con tipo contact, transfer, one_off o requested). La API responde con un veredicto síncrono: aceptada, diferida (fuera de ventana) o denegada (lista No Molestar, tope de intentos, sin clase de numeración válida).
  2. El scheduler evalúa las reglas legales del país del número (pack de jurisdicción: ventana horaria, intentos por número y por contacto, descanso entre intentos, clase de numeración exigida para el tipo de campaña) y encola el intento. Las órdenes priority: immediate se despachan en el acto; el resto, en la pasada incremental.
  3. El pacer emite los intentos al ritmo que permiten los límites: llamadas por segundo del trunk, canales, presupuesto diario y sesiones disponibles en el orquestador.
  4. El originator origina por SIP a través del trunk del país con el caller ID de la campaña. Si la persona contesta, reserva una sesión y abre el mismo audio fork que en inbound. Si no contesta, está ocupado o falla, registra el resultado y cuelga.
  5. Conversación, herramientas y cierre funcionan igual que en inbound. El OS recibe por webhook attempt.finished (resultado telefónico, caller ID usado, causa SIP) y la disposición del agente.

Transferencias hoy: consulta y retorno​

Cuando un agente necesita consultar a un tercero (un asesor, una sucursal), el OS crea una orden hija de tipo transfer con prioridad inmediata. El motor origina una segunda llamada al destino con un agente enlace, mientras el cliente espera en la llamada original con música y avisos. El enlace reporta el resultado y el agente original continúa con el cliente. En este modelo la llamada del cliente nunca se mueve: sigue anclada en Ocular. El traspaso real (conectar al cliente con el destino) se describe en SIP REFER de vuelta a PSTN.

Garantías transversales​

  • Default deny en cada capa. Red, origen SIP, formato del DID, mapeo del DID, tenant, país, pack legal, horario. Lo que no está explícitamente permitido no se atiende ni se marca.
  • Reglas legales como dato, no como código. Cada país tiene un pack con ventanas, topes y clases de numeración, activado por una persona de legal. Los perfiles por tipo de orden (llamada suelta, llamada pedida, transferencia) también viven en el pack y requieren firma.
  • Idempotencia. Reservas, originaciones y entregas de eventos se identifican por intento; un reintento nunca duplica una llamada ni una disposición.
  • Observabilidad. Cada servicio expone métricas y logs estructurados con los números enmascarados. Hay un preflight operativo que verifica trunks, perfiles SIP, certificados y servicios antes y después de cada despliegue.
  • Cero secretos en código o chat. Credenciales de carriers, tokens de orquestador y claves de webhook viven en un gestor de secretos y se inyectan por entorno.