Below are possible errors that may occur when using the Gateway (PBX→Telegram mode) — both during registration (PBX→SIP.TG) and at the moment of call establishment (SIP→Telegram or Telegram→SIP). Some of them appear in PBX logs, some — as a displayed code when trying to call a Telegram account. Not all errors are frequently encountered in real operation, but it’s useful to know about them for diagnostic purposes.
For reference:
If you’re just getting started with the Gateway, we also recommend checking out these articles:
What happens if someone calls this account directly?
When setting up the Gateway, the Telegram account forwards incoming calls to the PBX.
If a person is on the list of allowed callers, the call will be directed to the PBX, and on the device where this account is open, you can also manually answer the call.
It’s usually recommended to disable call reception on other devices so that everything goes through the PBX.
Can I work with multiple Telegram accounts at once?
Yes, in the “Gateway” subscription, you can pay for multiple Telegram accounts. The first account costs 15 EUR/month, each additional one costs 150 EUR/month.
What if I need to process text messages too?
The Gateway can process incoming messages if you enable the “Message Processing” option in the gateway settings. This enables auto-reply, Callback mode, and message processing by an external bot.
For more details, see SIP.TG Session Settings.
How reliable is this?
The entire SIP.TG infrastructure is distributed across multiple data centers. Nevertheless, for mission-critical systems, you might consider your own Worker servers.
Which Telegram account is best to use as a Gateway?
It’s recommended to create a separate work account for the company — so that your personal Telegram doesn’t mix with business calls. It’s important that this account is always online (or store the session in the SIP.TG Cloud Storage).
Can one Telegram account be shared among multiple employees?
Why is the call dropped for others when one person answers?
This is normal Gateway behavior: the PBX sees that the call has already been accepted. A CANCEL is sent to other clients. If you want each employee to have their own Telegram account, use multiple gateway subscriptions.
Is a SIM card required?
A Telegram account is created based on a phone number. Usually, you take any SIM card, register it with Telegram, and then the number may not be used for traditional operator voice calls. The main thing is not to lose access to this number for Telegram recovery.
What is the port range used for RTP?
Our SIP stack is based on Yate, where the default UDP port range is 16384-32768.
Incoming call not reaching the Telegram gateway
One-way audio when using the Gateway
As with the Softphone, this is most often a question of codecs or network restrictions.
alaw
or mulaw
).DTMF not recognized in voice menu
Such responses may appear both during calls and during simple SIP trunk registration. The code below is sent by the SIP.TG server to your PBX.
401 Unauthorized
402 …
Essence: “Gateway” subscription limitation. This means that the Telegram account has no paid lines for Gateway mode, the subscription has expired, or the resource volume is exceeded.
What to do:
/subscriptions
, check if the “Gateway” plan is active and if there are enough lines.500 Database error
Essence: Internal error on the SIP.TG side related to the database. Such cases are extremely rare.
What to do:
503 No response from Manager
Essence: The Worker cannot connect to the SIP.TG Manager server due to an internal network problem. Your PBX will see this as a 503
response.
What to do:
Here are responses that may come when your PBX tries to register with the SIP.TG Worker server (connection with the PBX→SIP.TG type). All errors listed below usually have code 403 or 404.
403 Wrong password
Essence: The PBX correctly tries to authenticate, but the specified password does not match what SIP.TG expects.
What to do:
/gateway
section of @siptg_bot and compare with what is entered on the PBX.403 Untrusted IP address
Essence: The password is correct, but your IP address is not in the list of allowed addresses for this SIP connection.
What to do:
/gateway
, open the settings of the corresponding SIP connection and:
403 Telegram session is inactive
Essence: The Telegram account to which the binding is going is inactive (authorization has been lost). As a result, SIP.TG refuses to register the trunk, as there is no real Telegram connection.
What to do:
/gateway
section, reconnect the Telegram account (authorize the phone number).403 Session storage is inactive
Essence: The storage where the Telegram session is saved (cloud or your own Sessions storage) is currently turned off or unavailable. Consequently, there is no possibility to work with the Telegram session.
What to do:
/gateway
. Usually such failures are short-lived.403 Worker is inactive
Essence: The selected Worker server is disabled on the SIP.TG side or is in the process of updating/restarting. The server cannot accept PBX→SIP.TG registration.
What to do:
/gateway
section, check the Worker settings. If the server is disabled, select another one or wait until it becomes active again.403 Worker address is not set
Essence: The Worker server configuration does not provide for connections with the “PBX→SIP.TG” type. For example, the server is only configured for “SIP.TG→PBX” or “IP⇿IP”.
What to do:
403 Route is not permitted
Essence: Access to the used Telegram session has been revoked or no longer belongs to you. For example, the administrator who created the session has been deprived of rights, and you cannot use this session.
What to do:
/gateway
section, connect the Telegram number that you control.404 Route not found
Essence: The login specified in the SIP request does not exist or has already been deleted. The SIP.TG server does not find such an “account”.
What to do:
/gateway
section.These errors occur when your PBX is already registered (or IP-to-IP), and during an outgoing call to Telegram, the SIP.TG server returns a code if it cannot correctly call the Telegram account.
403 USER_PRIVACY_RESTRICTED
Essence: The Telegram user has restricted the circle of people who can call them (e.g., only contacts), and your gateway account is not on this list.
What to do:
404 Not Found / 404 Chat not found / 404 USERNAME_NOT_OCCUPIED
Essence: SIP.TG could not find the Telegram account by the transmitted identifier (number, user_id, username). Telegram may return such a response if:
What to do:
405 REGISTER is required first
Essence: You are sending an INVITE without a prior PBX→SIP.TG registration, while the Worker requires a full REGISTER.
What to do:
408 Timeout of waiting RPC result
Essence: The Telegram server did not respond in time, or the SIP.TG request hung when accessing Telegram. This happens during overload or Telegram anti-spam filter, when there are many outgoing calls in a short time.
What to do:
470 Anonymous user
Essence: SIP.TG is trying to call a user by their internal user_id, with which there is no explicit confirmed contact. Telegram rejects such “anonymous” calls.
What to do:
500 (others)
Essence: Any other internal error on the Telegram side. Sometimes this designates unexpected failures during audio channel processing, internal overload, etc.
What to do:
503 Account is not running
Essence: The SIP.TG Worker server received an INVITE, but there is no active session for the needed account. That is, the PBX could have sent an INVITE without waiting for a response to REGISTER.
What to do:
503 Session is not running
Essence: The Telegram session is actually disconnected. It’s possible that in the @siptg_bot, the session is displayed, but it’s not actually authorized.
What to do:
/gateway
, if necessary, re-authorize the Telegram number.503 Telegram storage is unavailable
503 Too Many Requests: retry after … / 503 PEER_FLOOD
Essence: This is Telegram’s anti-spam protection, when too many outgoing calls occur in a short period, especially to unfamiliar numbers.
What to do:
503 Worker is not ready
Essence: The Worker was recently restarted or is being updated, and has not yet completed initialization. As a result, calls are rejected at the SIP level.
What to do:
Here we consider situations when a real user tries to call the Gateway account from the Telegram application, and the Worker tries to transfer the call to your PBX. If the PBX returns an error, or if an error occurs on the SIP.TG side, the user may see an error in the chat with the Gateway account.
In this section, we only list those errors that may occur on the SIP.TG side.
482 Caller has active gateway accounts
Essence: The SIP.TG Gateway is also activated on the caller’s account. The service blocks such an attempt (Telegram→SIP) to prevent looping or unforeseen call loops.
What to do:
503 SIP account is unavailable
503 Worker is unavailable
If none of the listed solutions helps, seek assistance. For more details, see How to Get Help.