Solución de problemas
A continuación se describen los posibles errores que pueden ocurrir al usar el Gateway (modo PBX→Telegram) — tanto durante el registro (PBX→SIP.TG) como en el momento de establecer la llamada (SIP→Telegram o Telegram→SIP). Algunos aparecen en los registros de la PBX, otros — como un código visible cuando se intenta llamar a una cuenta de Telegram. No todos los errores se encuentran frecuentemente en la operación real, pero es útil conocerlos para fines de diagnóstico.
Como referencia:
- Manager — el componente de control de SIP.TG, responsable de conectarse a los servidores Worker y a los Almacenamientos de Sesiones.
- Worker — el componente operativo que procesa llamadas, tráfico RTP y realiza la señalización SIP.
Si está comenzando con el Gateway, también recomendamos consultar estos artículos:
- Interacción con Telegram — cómo autorizar una cuenta de Telegram para llamadas.
- Interacción con PBX — descripción detallada de las opciones de conexión SIP.
- Resumen de suscripciones — para asegurarse de que su suscripción “Gateway” cubra el número requerido de líneas.
Preguntas frecuentes
¿Qué sucede si alguien llama directamente a esta cuenta?
¿Qué sucede si alguien llama directamente a esta cuenta?
Al configurar el Gateway, la cuenta de Telegram reenvía las llamadas entrantes a la PBX.
Si una persona está en la lista de llamantes permitidos, la llamada se dirigirá a la PBX, y en el dispositivo donde esta cuenta está abierta, también puede responder manualmente a la llamada.
Generalmente se recomienda deshabilitar la recepción de llamadas en otros dispositivos para que todo pase a través de la PBX.
¿Puedo trabajar con varias cuentas de Telegram a la vez?
¿Puedo trabajar con varias cuentas de Telegram a la vez?
Sí, en la suscripción “Gateway”, puede pagar por múltiples cuentas de Telegram. La primera cuenta cuesta 15 EUR/mes, cada cuenta adicional cuesta 150 EUR/mes.
¿Qué pasa si necesito procesar también mensajes de texto?
¿Qué pasa si necesito procesar también mensajes de texto?
El Gateway puede procesar mensajes entrantes si activa la opción “Procesamiento de mensajes” en la configuración del gateway. Esto habilita la respuesta automática, el modo Callback y el procesamiento de mensajes por un bot externo.
Para más detalles, consulte Configuración de sesión SIP.TG.
¿Qué tan confiable es esto?
¿Qué tan confiable es esto?
Toda la infraestructura SIP.TG está distribuida en múltiples centros de datos. Sin embargo, para sistemas críticos, podría considerar sus propios servidores Worker.
¿Qué cuenta de Telegram es mejor usar como Gateway?
¿Qué cuenta de Telegram es mejor usar como Gateway?
Se recomienda crear una cuenta de trabajo separada para la empresa — para que su Telegram personal no se mezcle con las llamadas de negocios. Es importante que esta cuenta esté siempre en línea (o almacene la sesión en el Almacenamiento en la nube de SIP.TG).
¿Puede una cuenta de Telegram ser compartida entre varios empleados?
¿Puede una cuenta de Telegram ser compartida entre varios empleados?
Sí, pero esto significa que todos usarán la misma cuenta de Telegram, y las llamadas entrantes llegarán a todos los dispositivos simultáneamente. Tan pronto como una persona responda, la llamada se cancelará para los demás.
¿Por qué se cancela la llamada para los demás cuando una persona responde?
¿Por qué se cancela la llamada para los demás cuando una persona responde?
Este es el comportamiento normal del Gateway: la PBX ve que la llamada ya ha sido aceptada. Se envía un CANCEL a otros clientes. Si desea que cada empleado tenga su propia cuenta de Telegram, use múltiples suscripciones gateway.
¿Se requiere una tarjeta SIM?
¿Se requiere una tarjeta SIM?
Una cuenta de Telegram se crea basándose en un número de teléfono. Normalmente, se toma cualquier tarjeta SIM, se registra con Telegram, y luego el número puede no usarse para llamadas de voz tradicionales del operador. Lo importante es no perder el acceso a este número para la recuperación de Telegram.
¿Cuál es el rango de puertos utilizado para RTP?
¿Cuál es el rango de puertos utilizado para RTP?
Nuestro stack SIP está basado en Yate, donde el rango de puertos UDP predeterminado es 16384-32768.
Problemas generales
La llamada entrante no llega al gateway de Telegram
La llamada entrante no llega al gateway de Telegram
- Compruebe que la cuenta de Telegram esté activa y no bloqueada por el mensajero.
- Asegúrese de que en la configuración de privacidad de Telegram, las llamadas de todos estén permitidas.
Audio unidireccional al usar el Gateway
Audio unidireccional al usar el Gateway
Al igual que con el Softphone, esto suele ser una cuestión de códecs o restricciones de red.
- Intente especificar un códec específico (
alaw
omulaw
). - Asegúrese de que el tráfico UDP esté permitido.
DTMF no reconocido en el menú de voz
DTMF no reconocido en el menú de voz
Errores SIP comunes
Tales respuestas pueden aparecer tanto durante las llamadas como durante el registro simple del troncal SIP. El código a continuación es enviado por el servidor SIP.TG a su PBX.
401 Unauthorized
401 Unauthorized
402 …
402 …
Esencia: Limitación de la suscripción “Gateway”. Esto significa que la cuenta de Telegram no tiene líneas pagadas para el modo Gateway, la suscripción ha expirado, o se ha excedido el volumen de recursos.
Qué hacer:
- En @siptg_bot con el comando
/subscriptions
, compruebe si el plan “Gateway” está activo y si hay suficientes líneas. - Si el período de suscripción ha expirado o se necesitan líneas adicionales, organice la renovación/extensión de la suscripción (consulte Resumen de suscripciones).
- Asegúrese de que la cuenta específica de Telegram esté realmente vinculada a la suscripción correcta (al pagar por múltiples cuentas).
500 Database error
500 Database error
Esencia: Error interno en el lado de SIP.TG relacionado con la base de datos. Tales casos son extremadamente raros.
Qué hacer:
- Por lo general, es de naturaleza temporal y se resuelve automáticamente.
- Intente de nuevo; si el error ocurre regularmente, busque ayuda. Para más detalles, consulte Cómo obtener ayuda.
503 No response from Manager
503 No response from Manager
Esencia: El Worker no puede conectarse al servidor Manager de SIP.TG debido a un problema de red interno. Su PBX verá esto como una respuesta 503
.
Qué hacer:
- Por regla general, estos son fallos de corta duración. Intente esperar 1-2 minutos y repetir la llamada.
- Si el problema persiste, puede cambiar el troncal SIP a otro servidor Worker (consulte Interacción con PBX).
Errores durante el registro PBX → SIP.TG
Aquí están las respuestas que pueden llegar cuando su PBX intenta registrarse con el servidor Worker de SIP.TG (conexión con el tipo PBX→SIP.TG). Todos los errores enumerados a continuación generalmente tienen código 403 o 404.
403 Wrong password
403 Wrong password
Esencia: La PBX intenta autenticarse correctamente, pero la contraseña especificada no coincide con lo que SIP.TG espera.
Qué hacer:
- Compruebe la contraseña en la sección
/gateway
de @siptg_bot y compárela con lo que está introducido en la PBX. - Si es necesario, cambie la contraseña en el bot (el botón “Cambiar contraseña”) e introduzca la nueva en el lado de la PBX.
- Asegúrese de que el login (nombre de usuario) tampoco contenga errores tipográficos.
403 Untrusted IP address
403 Untrusted IP address
Esencia: La contraseña es correcta, pero su dirección IP no está en la lista de direcciones permitidas para esta conexión SIP.
Qué hacer:
- En @siptg_bot, sección
/gateway
, abra la configuración de la conexión SIP correspondiente y:- Añada su dirección IP a la lista de confianza.
- O limpie la lista para permitir conexiones desde cualquier IP (pero observe medidas de seguridad).
- Si su IP externa cambia en su red, tenga esto en cuenta al configurar (quizás valga la pena deshabilitar completamente ACL).
403 Telegram session is inactive
403 Telegram session is inactive
Esencia: La cuenta de Telegram a la que va la vinculación está inactiva (se ha perdido la autorización). Como resultado, SIP.TG se niega a registrar el troncal, ya que no hay una conexión real de Telegram.
Qué hacer:
- En @siptg_bot en la sección
/gateway
, reconecte la cuenta de Telegram (autorice el número de teléfono). - Si la cuenta de Telegram ha sido eliminada, tendrá que asignar otro número de teléfono para el Gateway.
- Para más detalles, consulte Interacción con Telegram.
403 Session storage is inactive
403 Session storage is inactive
Esencia: El almacenamiento donde se guarda la sesión de Telegram (almacenamiento en la nube o su propio Almacenamiento de Sesiones) está actualmente apagado o no disponible. En consecuencia, no hay posibilidad de trabajar con la sesión de Telegram.
Qué hacer:
- Si usa el almacenamiento en la nube de SIP.TG, compruebe el estado en
/gateway
. Normalmente estos fallos son de corta duración. - Si tiene su propio Almacenamiento de Sesiones, asegúrese de que esté funcionando y disponible. Si es necesario, cambie a la nube de SIP.TG.
403 Worker is inactive
403 Worker is inactive
Esencia: El servidor Worker seleccionado está deshabilitado en el lado de SIP.TG o está en proceso de actualización/reinicio. El servidor no puede aceptar el registro PBX→SIP.TG.
Qué hacer:
- En la sección
/gateway
del bot, compruebe la configuración del Worker. Si el servidor está deshabilitado, seleccione otro o espere hasta que vuelva a estar activo. - Si este es su propio Worker, inicie/reinicie.
403 Worker address is not set
403 Worker address is not set
Esencia: La configuración del servidor Worker no prevé conexiones con el tipo “PBX→SIP.TG”. Por ejemplo, el servidor solo está configurado para “SIP.TG→PBX” o “IP⇿IP”.
Qué hacer:
- En @siptg_bot, compruebe nuevamente el tipo de conexión (PBX→SIP.TG) y seleccione un Worker apropiado.
- Cree otro tipo de conexión SIP (“SIP.TG→PBX” o “IP⇿IP”).
403 Route is not permitted
403 Route is not permitted
Esencia: El acceso a la sesión de Telegram utilizada ha sido revocado o ya no le pertenece. Por ejemplo, el administrador que creó la sesión ha sido privado de derechos, y no puede usar esta sesión.
Qué hacer:
- Cree su propia sesión de Gateway. En la sección
/gateway
del bot, conecte el número de Telegram que usted controla. - Asegúrese de que el administrador que creó previamente la sesión no le quitó el acceso.
404 Route not found
404 Route not found
Esencia: El login especificado en la solicitud SIP no existe o ya ha sido eliminado. El servidor SIP.TG no encuentra tal “cuenta”.
Qué hacer:
- Verifique nuevamente el login/nombre de usuario que recibió en la sección
/gateway
. - Si este registro fue eliminado previamente, cree uno nuevo.
- Asegúrese de que su PBX tenga exactamente el login que fue emitido por el bot (sin caracteres o espacios adicionales).
Errores al llamar SIP → Telegram
Estos errores ocurren cuando su PBX ya está registrada (o IP-to-IP), y durante una llamada saliente a Telegram, el servidor SIP.TG devuelve un código si no puede llamar correctamente a la cuenta de Telegram.
403 USER_PRIVACY_RESTRICTED
403 USER_PRIVACY_RESTRICTED
Esencia: El usuario de Telegram ha restringido el círculo de personas que pueden llamarle (por ejemplo, solo contactos), y su cuenta gateway no está en esta lista.
Qué hacer:
- Pida al usuario llamado que configure el permiso de llamada: “Configuración → Privacidad → Llamadas de voz” → “Todos los usuarios” o añadir su cuenta gateway a “Permitir siempre”.
- O use una cuenta que realmente esté en los contactos del usuario objetivo.
404 Not Found / 404 Chat not found / 404 USERNAME_NOT_OCCUPIED
404 Not Found / 404 Chat not found / 404 USERNAME_NOT_OCCUPIED
Esencia: SIP.TG no pudo encontrar la cuenta de Telegram por el identificador transmitido (número, user_id, nombre de usuario). Telegram puede devolver tal respuesta si:
- El número efectivamente no está registrado en Telegram.
- El nombre de usuario no existe o ha sido liberado.
- El perfil no está disponible debido a restricciones.
- Su cuenta gateway busca un número de teléfono con demasiada frecuencia.
Qué hacer:
- Asegúrese de estar utilizando el identificador correcto (si usa un teléfono, debe ser un número real de Telegram).
- Si sucede a menudo, compruebe si cometió un error en el formato. Podría ser mejor usar el user_id interno.
405 REGISTER is required first
405 REGISTER is required first
Esencia: Está enviando un INVITE sin un registro previo PBX→SIP.TG, mientras que el Worker requiere un REGISTER completo.
Qué hacer:
- Habilite el modo “Registration” en el lado de su PBX (registre el troncal PBX→SIP.TG). Para más detalles, consulte Interacción con PBX.
408 Timeout of waiting RPC result
408 Timeout of waiting RPC result
Esencia: El servidor de Telegram no respondió a tiempo, o la solicitud SIP.TG se quedó colgada al acceder a Telegram. Esto sucede durante sobrecarga o filtro anti-spam de Telegram, cuando hay muchas llamadas salientes en un corto período de tiempo.
Qué hacer:
- Reduzca la intensidad de las llamadas salientes.
- Espere e intente nuevamente si fue un fallo temporal.
470 Anonymous user
470 Anonymous user
Esencia: SIP.TG está tratando de llamar a un usuario por su user_id interno, con el que no hay un contacto explícito confirmado. Telegram rechaza tales llamadas “anónimas”.
Qué hacer:
- Normalmente necesita llamar por un número confirmado o nombre de usuario, o hacer que el usuario le añada a contactos o le escriba primero.
500 (otros)
500 (otros)
Esencia: Cualquier otro error interno en el lado de Telegram. A veces esto designa fallos inesperados durante el procesamiento del canal de audio, sobrecarga interna, etc.
Qué hacer:
- Compruebe la estabilidad de la red, repita la llamada.
- Si el error aparece regularmente en el mismo número, busque ayuda. Para más detalles, consulte Cómo obtener ayuda.
503 Account is not running
503 Account is not running
Esencia: El servidor Worker de SIP.TG recibió un INVITE, pero no hay una sesión activa para la cuenta necesaria. Es decir, la PBX podría haber enviado un INVITE sin esperar una respuesta a REGISTER.
Qué hacer:
- Asegúrese de que el troncal PBX→SIP.TG esté registrado con éxito y el Worker vea una cuenta activa.
- A veces ayuda reiniciar el troncal en la PBX. Si es necesario, consulte Interacción con PBX.
503 Session is not running
503 Session is not running
Esencia: La sesión de Telegram está realmente desconectada. Es posible que en @siptg_bot, la sesión se muestre, pero realmente no está autorizada.
Qué hacer:
- Vuelva a comprobar el estado de la sesión en
/gateway
, si es necesario, vuelva a autorizar el número de Telegram. - Si el error ocurre con frecuencia, intente cambiar a otro Worker o reiniciar la cuenta.
503 Telegram storage is unavailable
503 Telegram storage is unavailable
503 Too Many Requests: retry after … / 503 PEER_FLOOD
503 Too Many Requests: retry after … / 503 PEER_FLOOD
Esencia: Esta es la protección anti-spam de Telegram, cuando ocurren demasiadas llamadas salientes en un corto período, especialmente a números desconocidos.
Qué hacer:
- Reduzca la velocidad de marcación (en el lado de la PBX o su script).
- Use varias cuentas diferentes de Telegram para distribuir la carga.
- Espere el tiempo especificado “retry after N”, luego intente de nuevo.
503 Worker is not ready
503 Worker is not ready
Esencia: El Worker fue reiniciado recientemente o está siendo actualizado, y aún no ha completado la inicialización. Como resultado, las llamadas son rechazadas a nivel SIP.
Qué hacer:
- Espere 1-2 minutos e intente la llamada de nuevo.
- O en @siptg_bot, seleccione otro servidor Worker para su conexión.
Errores al llamar Telegram → SIP
Aquí consideramos situaciones cuando un usuario real intenta llamar a la cuenta Gateway desde la aplicación Telegram, y el Worker intenta transferir la llamada a su PBX. Si la PBX devuelve un error, o si ocurre un error en el lado de SIP.TG, el usuario puede ver un error en el chat con la cuenta Gateway.
En esta sección, solo enumeramos aquellos errores que pueden ocurrir en el lado de SIP.TG.
482 Caller has active gateway accounts
482 Caller has active gateway accounts
Esencia: El Gateway SIP.TG también está activado en la cuenta del llamante. El servicio bloquea tal intento (Telegram→SIP) para evitar bucles o ciclos de llamadas imprevistos.
Qué hacer:
- Si realmente necesita recibir llamadas de una cuenta que también es un gateway, es mejor usar un modo diferente para ella (por ejemplo, Softphone) u otra cuenta de Telegram sin Gateway.
503 SIP account is unavailable
503 SIP account is unavailable
503 Worker is unavailable
503 Worker is unavailable
Si ninguna de las soluciones enumeradas ayuda, busque asistencia. Para más detalles, consulte Cómo obtener ayuda.