Monitoreo de pantalla en vivo: contrato para integradores

English version: Live screen monitoring.

Un supervisor puede ver en vivo la pantalla de un agente. Esta página es la vista del integrador sobre esa función: qué hay que reconocer, qué llamadas y eventos intervienen, quién puede mirar y qué tiene que permitir la red. Las rutas exactas, los cuerpos y los códigos de estado están en Transcripciones de grabaciones, redacción de audio y aviso de monitoreo de pantalla (en inglés) y en la Referencia de la API generada; esta página no los repite.

Disponibilidad

El lado del dashboard requiere el dashboard v0.51.1 o posterior: las versiones anteriores enviaban Permissions-Policy: display-capture=(), así que el navegador rechazaba la captura de pantalla. Las rutas de core de abajo se publican desde core v0.106.0. El monitoreo en vivo depende del flag de tenant screen_monitor_enabled y de la ruta de red descrita en «Requisito de red».

Los nombres de campo, los enums y los códigos de estado salen del openapi/dialer-v1.yaml vendorizado (info.version: 0.106.0).

Qué interviene

Pieza	Papel
Flag de tenant screen_monitor_enabled	Apagado: toda ruta screen-monitor responde 404 not_found, salvo las dos lecturas del libro mayor (GET /v1/screen-monitor/sessions y GET /v1/screen-monitor/acks) y el cierre de una sesión.
Aviso y acuse	El puesto del agente reconoce un aviso versionado con el alcance live_monitoring (y un acuse aparte para screen_recording). GET /v1/me lo informa en screen_monitor.scopes.<scope>.ack_current; un alcance sólo está autorizado cuando enabled y ack_current son ambos true.
Armado	PUT /v1/screen-monitor/armed: el dashboard del agente dice que tiene una captura. Necesita el puesto con check-in hecho (409 not_checked_in) y un acuse live_monitoring vigente (409 no_ack). Una pestaña por puesto.
Sesión	POST /v1/screen-monitor/sessions desde un puesto de supervisor o admin; core valida, escribe una fila en el libro mayor y avisa al agente. Core nunca transporta el vídeo: los dos navegadores lo negocian de igual a igual mediante POST .../sessions/{id}/signal.
Libro mayor	GET /v1/screen-monitor/sessions: quién miró a quién, incluidos los intentos rechazados. Nunca guarda carga de señalización.

Quién puede mirar

Sólo un inicio de sesión ddu_ cuyo rol de plantilla de puesto sea supervisor o admin. El rol siempre se evalúa; no depende de supervision_role_enforced. Una clave de integración dd_ recibe 403 forbidden (no hay una persona detrás) y un token de widget ddw_ se rechaza antes del manejador. Un agente sólo puede ser observado si está armado y tiene un acuse live_monitoring vigente, y por un supervisor a la vez (409 agent_busy). Todo resultado de un inicio de sesión ddu_, rechazos incluidos, deja una fila en el libro mayor; el 403 de una clave dd_ no deja ninguna.

Eventos que reciben los navegadores

Core avisa a cada parte por el tópico WebSocket privado de esa parte (la especificación nombra los frames; no figuran en Eventos WebSocket):

Frame	Enviado a	Cuándo
screen.view_requested	el agente	un supervisor abrió una sesión sobre el puesto
screen.disarmed	la pestaña del agente	otra pestaña armó (reason: displaced) o el puesto hizo check-out (reason: checkout)
screen.ended	la otra parte cuando una parte la cierra; las dos partes cuando la cierra el sistema	la sesión se cerró, con result y reason (checkout, agent_stopped, peer_failed, credential_lapsed, flag_off, role, no_ack)

Una sesión en vivo se cierra sola cuando el agente hace check-out, cuando cualquiera de las partes pierde su último socket, cuando caduca una credencial, o cuando el flag, el rol del supervisor o el acuse del agente dejan de cumplirse. Un reinicio de core desarma todos los puestos (cierre por defecto).

Requisito de red

El vídeo viaja por WebRTC entre el navegador del agente y el del supervisor, no por core. Ambos navegadores necesitan un camino directo o un relé.

• ICE en el dashboard. Desde el dashboard v0.52.0 (dashboard#739) las dos partes piden a core GET /v1/screen-monitor/sessions/{id}/ice y añaden esa credencial TURN a la lista STUN de GET /v1/softphone/ice. Si la celda no tiene relé (503 turn_unavailable) o la petición falla, la sesión se queda sólo con STUN, que falla detrás de un NAT simétrico; entonces el dashboard muestra la sesión como failed. El dashboard v0.51.1 usa sólo la lista STUN. Grabar la pantalla no usa WebRTC (sube fragmentos por REST), así que sólo afecta al monitoreo en vivo.
• Ruta de la credencial TURN: publicada en core v0.107.0. Core firma una credencial efímera por sesión y por parte mediante GET /v1/screen-monitor/sessions/{id}/ice (operación getScreenMonitorSessionIce, core#2131, ADR #267): sólo las dos partes de una sesión todavía started la obtienen (cualquier otro, un id desconocido o un id mal formado responden el mismo 404), la respuesta es Cache-Control: no-store, username es <unix expiry>:scr.<session_id>.<agent|viewer>, caduca una hora después de emitirse (expires_at), y una celda sin TURN configurado responde 503 turn_unavailable (nunca devuelve una lista que parezca válida y no tenga relé). El openapi/dialer-v1.yaml vendorizado sigue en 0.106.0 y no lista esta ruta; la fuente es el openapi/dialer-v1.yaml de core en el tag v0.107.0. Mientras la celda del cliente no tenga un relé configurado, un cliente detrás de una red restrictiva no debe esperar que el monitoreo en vivo conecte.
• Puertos. El cortafuegos de un cliente debe dejar que los navegadores lleguen al relé de la celda por 3478 (UDP y TCP) y 5349 (TCP) una vez que el relé esté habilitado para su celda.

El acuse del agente al aviso de grabación y supervisión

Aparte del aviso de pantalla de arriba, a un agente se le puede pedir que acepte un aviso de grabación y supervisión antes de ponerse disponible. Es otro aviso (global, versionado, un texto por idioma) con sus propias tres operaciones en la Referencia de la API:

Operación	Ruta	Qué hace
getAgentMonitoringNotice	GET /v1/agent-monitoring-notice	Devuelve la versión vigente y sus textos (title, body, text_sha256). 404 not_found mientras no haya versión publicada. Pueden leerlo una clave dd_ o un inicio de sesión ddu_; un token de widget ddw_ recibe 403.
acknowledgeAgentMonitoringNotice	POST /v1/agent-monitoring-acknowledgements	El propio puesto del agente acepta notice_version (tiene que ser la vigente) leída en lang. Sólo un inicio de sesión ddu_ con puesto vinculado: una clave dd_ recibe 403 forbidden, un ddu_ sin puesto activo 403 seat_not_linked, y un agent_id que no es el puesto de quien llama 403 forbidden. 409 no_notice_published, 409 stale_notice, y 422 si la versión vigente no tiene texto en lang. Aceptar otra vez la misma versión devuelve el primer acuse (200, sin fila nueva).
getAgentMonitoringAcknowledgement	GET /v1/agents/{id}/monitoring-acknowledgement	Si ese agente aceptó la versión vigente (monitoring.current) y su último acuse de cualquier versión (null si no hay). Un puesto lee el suyo; un puesto supervisor o admin y una clave dd_ leen a cualquier agente del tenant; otro puesto recibe 403 forbidden.

Los acuses son un libro de sólo añadir: nunca se editan ni se borran, y una versión nueva del aviso deja archivados los acuses viejos, que dejan de cubrir al agente.

Bandera apagada y encendida

La bandera de tenant agent_monitoring_ack_enforced nace apagada; sólo la enciende el founder y esta guía no da fecha. Las tres operaciones de arriba responden con la bandera encendida o apagada.

• Bandera apagada (por defecto). No se le pide nada al agente: el check-in y el resume funcionan como antes. Los acuses ya escritos se conservan.
• Bandera encendida, en un tenant con al menos una campaña que graba (record_calls) y no está terminada ni archivada. Un agente que no ha aceptado la versión vigente recibe 403 monitoring_ack_required de POST /v1/agents/checkin y de POST /v1/agents/{id}/resume, y no cambia nada: el puesto sigue fuera de línea (o en pausa) y no se emite ninguna credencial SIP. Core aplica la misma puerta a PATCH /v1/agents/{id}/status con available desde paused; cerrar el trabajo posterior a la llamada no está sujeto a ella. El cuerpo del error trae error.notice_version, la versión por aceptar. Es null cuando no hay aviso publicado: la puerta entonces sigue cerrada, porque no hay nada que aceptar.

Para recuperarse: lee el aviso (GET /v1/agent-monitoring-notice), muestra el texto al agente, haz POST del acuse desde el propio puesto del agente con esa notice_version y el lang mostrado, y repite el check-in. El dashboard lo hace por el agente: la tarjeta del check-in enseña el aviso tal como lo entrega core, el agente lo acepta y se reintenta el mismo check-in.

Core no publica texto legal propio: el catálogo de avisos nace vacío. Lo que dice el aviso y lo que exige cada jurisdicción no se afirma aquí; mira la Hoja de ruta.

Fuentes en core: lib/dialer/api/v1_router.ex (las tres rutas y monitoring_ack_required), lib/dialer/agents/monitoring_gate.ex (cuándo aplica la puerta), lib/dialer/flags/catalog.ex (agent_monitoring_ack_enforced) y openapi/dialer-v1.yaml.

Lo que esta página no afirma

• El texto legal del aviso y lo que exige cada jurisdicción: mira la Hoja de ruta.
• La redacción de datos personales en la grabación de pantalla (core#2017): no está publicada en la especificación.