Troubleshooting

Llamadas y audio

El agente no recibe llamadas

Causa típica: el estado del agente es On Break, Logged Out o el agente no está en la cola correcta.

Comprueba en orden:

1. Dashboard → Agentes → tu usuario → status debe ser Available.
2. Cola → debe incluir al agente en sus miembros (Settings → Queues → ver miembros).
3. Softphone → registro SIP verde (icono superior derecho del softphone). Si está rojo, hay problema de conexión.
4. WebRTC → permisos de micrófono concedidos en el navegador.

No hay audio en la llamada (un lado o ambos)

Causa típica: NAT/firewall corporativo bloqueando RTP, o codec mismatch.

• Si el caller PSTN no oye al agente: revisa el firewall del lado del agente, abre rango RTP UDP saliente.
• Si el agente no oye al caller: lo mismo en sentido contrario.
• Codecs negociados visibles en CDR del backoffice → “Call detail” → “Technical”.
• WebRTC requiere STUN. Si tu red corporativa bloquea stun.l.google.com:19302, el ICE falla. Solución: usar TURN (configurable en Enterprise).

Llamada cae al transferir ciego

Causa típica: el destino no existe o no está disponible.

• Verifica que la extensión destino está registrada (Settings → Agentes).
• Revisa Audit Log con filtro event=transfer para ver la causa concreta.
• Transferencia atendida (3-way) suele ser más fiable si el destino es incierto.

Registro SIP

El softphone aparece desconectado

1. Logout y login otra vez (regenera tokens).
2. Si persiste, abre las DevTools del navegador → Console → busca mensajes con “SIP” o “WSS”.
3. WSS sobre puerto 443 puede ser bloqueado por proxies HTTP/2 mal configurados. Usar puerto alternativo o desactivar HTTP/2 en el proxy.

Trunk SIP en estado FAIL

Causa habitual (90% de los casos): CIDRs mal configurados o credenciales incorrectas.

• Settings → SIP trunks → tu trunk → “Allowed CIDRs” debe contener el rango completo del proveedor.
• Zadarma envía desde 185.45.152.0/24 (no solo 185.45.152.180).
• Twilio: ver IPs en su dashboard → Elastic SIP Trunking → “IP ACL”.
• Tras corregir, espera 30s y comprueba estado.

Transcripción en vivo

No aparece transcripción aunque la política está activa

Causa típica: la política está activa pero la llamada no llegó a bridge-agent-start ni entró en nodo ai_agent.

Si crees que sí se atendió y no se transcribió:

1. Settings → Transcription policies → verifica que tu política aplica (scope global vs DID vs queue vs agent).
2. Settings → Transcription providers → API key del proveedor STT debe estar válida (test botón).
3. CDR de la llamada → “Technical” → busca eventos transcription_*. Si falta transcription_started, no se inició la captura.

Transcripción se interrumpe a mitad de llamada

• WebSocket del proveedor STT puede caer ocasionalmente. Reintentamos hasta 3 veces. Si todos fallan, queda anotado en transcription_errors del CDR.
• Si pasa sistemáticamente: posible problema de cuota o rate-limit del proveedor (Deepgram, ElevenLabs). Revisa su dashboard.

auth_error con ElevenLabs Scribe

• API key incorrecta o expirada.
• Verifica que el modelo configurado es scribe_v2_realtime (con sufijo _realtime), no scribe_v2. El batch no soporta WebSocket streaming.

Salesforce SCV

El botón “Conectar con SIVO” en el LWC no abre OAuth

• El admin SF no tiene permiso de instalación de External Client Apps. Asigna Profile/Permission Set con permiso “Manage Connected Apps”.
• Popup bloqueado por el navegador. Permitir popups para tu dominio SF.

OAuth callback failed: invalid_grant

• El reloj del servidor SIVO y el de Salesforce difieren más de 5 min. Caso raro pero posible. Reportar a soporte.
• La External Client App fue eliminada entre la apertura del OAuth y el callback. Reinstalar package.

VoiceCall no se crea al entrar la llamada

• Mapping de usuarios SF ↔ SIVO incompleto. Settings → Salesforce → “User mappings”.
• El agente que va a atender no está mapeado a un User activo en SF.
• SCRT2 endpoint inaccesible. Comprueba status.salesforce.com.

Transcripción no aparece en Conversation

• Verifica en SIVO → Settings → Salesforce → push_transcripts: true.
• Header Telephony-Provider-Name: calltree debe estar configurado en Call Center de SF (lo hace el LWC automáticamente).
• SOQL: SELECT Id, ConversationIdentifier FROM Conversation ORDER BY CreatedDate DESC LIMIT 5 debe tener filas recientes.
• Errores SCRT2 → CDR → “Technical” → buscar sf_push_error.

AI agents

El bot interrumpe su propia voz (loop)

Causa: el VAD del agente IA detecta el playback del TTS como speech.

• Configuración avanzada (Pro/Enterprise) → AI Agents → “Anti-echo cooldown” → aumentar a 400-500ms si tu hardware o entorno es ruidoso.
• Asegúrate de que el caller no llama desde manos libres en altavoz cerca del micro.

Latencia muy alta (>2s)

• Cambia LLM a Groq (TTFT ~120ms vs OpenAI 700+).
• STT: Deepgram Nova-2 es el más rápido.
• Si usas ElevenLabs TTS, prueba eleven_multilingual_v2 (WS) en vez de eleven_v3 (HTTP).

LLM devuelve JSON inválido y el bot dice “no he entendido”

• Revisa el prompt: debe instruir explícitamente JSON con campos response, action, variables.
• El LLM más fiable para JSON output estructurado son OpenAI GPT-4o-mini y Groq Llama 3.x con temperature ≤ 0.3.

Multi-tenant

Veo datos de otro tenant en mi dashboard

Esto no debería ocurrir y es un bug de seguridad crítico. Si lo ves:

1. Cierra sesión inmediatamente.
2. Captura URL completa, IDs visibles, fecha/hora.
3. Email a [email protected] con asunto [SECURITY] Cross-tenant data leak.
4. SIVO te confirma en menos de 2h y abre incident response interno.

PostgreSQL RLS está activa en 23+ tablas. Si llegas a ver datos cross-tenant, el motor RLS falló — escalado inmediato.

Webhooks

Mi endpoint recibe el evento 2 veces

Normal. Cada webhook lleva X-Sivo-Event-Id único. Si recibes el mismo ID dos veces (puede pasar tras timeouts en tu lado), descártalo. SIVO nunca cambia el ID en un reintento.

Mi webhook devuelve 200 pero los datos no llegan

• Verifica que el body es JSON parseable. Algunos frameworks comen el body si no haces app.use(express.raw()) antes de tu handler de HMAC.
• HMAC: la firma se calcula sobre el raw body, no el parsed.

Firma HMAC no coincide

• Asegúrate de usar el webhook_secret correcto (no el global, sino el del endpoint específico).
• El algoritmo es sha256 (no sha1).
• El comparador debe ser timing-safe (crypto.timingSafeEqual en Node).

Backoffice y dashboard

Página queda cargando indefinidamente

• Browser cache antiguo. Hard refresh con Ctrl+Shift+R (Windows/Linux) o Cmd+Shift+R (Mac).
• WebSocket del Socket.IO desconectado. Revisar Network tab → WS → si está rojo, recargar.

Login dice “credenciales inválidas” con la password correcta

• 5 intentos fallidos en 15 min bloquean temporalmente. Espera o pide reset.
• MFA habilitado (admin/superadmin): el código TOTP es lo que falta, no la password.

Cómo obtener soporte si nada de esto funciona

1. Audit Log: backoffice — si hay incidente, espera el ETA.
2. Audit log: backoffice → Audit → filtra por usuario/recurso afectado.
3. Email: [email protected] con:
   • Tenant slug.
   • Hora exacta del problema (timezone).
   • User/agent/queue/call ID si aplica.
   • Pantalla con DevTools Console + Network abiertos.
4. Enterprise: usa tu canal directo de CSM.