Troubleshooting
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:
- Manager — the controlling component of SIP.TG, responsible for connecting to Worker servers and Session Storages.
- Worker — the working component that processes calls, RTP traffic, and performs SIP signaling.
If you’re just getting started with the Gateway, we also recommend checking out these articles:
- Interaction with Telegram — how to authorize a Telegram account for calls.
- Interaction with PBX — detailed description of SIP connection options.
- Subscriptions Overview — to ensure your “Gateway” subscription covers the required number of lines.
Frequently Asked Questions
What happens if someone calls this account directly?
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?
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?
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?
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?
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?
Can one Telegram account be shared among multiple employees?
Why is the call dropped for others when one person answers?
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?
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?
What is the port range used for RTP?
Our SIP stack is based on Yate, where the default UDP port range is 16384-32768.
General Issues
Incoming call not reaching the Telegram gateway
Incoming call not reaching the Telegram gateway
- Check that the Telegram account is active and not blocked by the messenger.
- Make sure that in Telegram privacy settings, calls from everyone are allowed.
One-way audio when using the Gateway
One-way audio when using the Gateway
As with the Softphone, this is most often a question of codecs or network restrictions.
- Try specifying a specific codec (
alawormulaw). - Make sure that UDP traffic is allowed.
DTMF not recognized in voice menu
DTMF not recognized in voice menu
Common SIP Errors
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
401 Unauthorized
402 …
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:
- In the @siptg_bot with the command
/subscriptions, check if the “Gateway” plan is active and if there are enough lines. - If the subscription period has expired or additional lines are needed, arrange for renewal / extension of the subscription (see Subscription Overview).
- Make sure that the specific Telegram account is actually linked to the right subscription (when paying for multiple accounts).
500 Database error
500 Database error
Essence: Internal error on the SIP.TG side related to the database. Such cases are extremely rare.
What to do:
- Usually temporary in nature and is automatically resolved.
- Try again, if the error occurs regularly, seek help. For more details, see How to Get Help.
503 No response from Manager
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:
- As a rule, these are short-term failures. Try waiting 1-2 minutes and repeat the call.
- If the problem persists, you can switch the SIP trunk to another Worker server (see Interaction with PBX).
Errors during PBX → SIP.TG registration
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
403 Wrong password
Essence: The PBX correctly tries to authenticate, but the specified password does not match what SIP.TG expects.
What to do:
- Check the password in the
/gatewaysection of @siptg_bot and compare with what is entered on the PBX. - If necessary, change the password in the bot (the “Change password” button) and enter the new one on the PBX side.
- Make sure that the login (username) also does not contain typos.
403 Untrusted IP address
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:
- In @siptg_bot, section
/gateway, open the settings of the corresponding SIP connection and:- Add your IP address to the trusted list.
- Or clear the list to allow connections from any IP (but observe security measures).
- If your external IP changes in your network, take this into account when configuring (perhaps it’s worth completely disabling ACL).
403 Telegram session is inactive
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:
- In @siptg_bot in the
/gatewaysection, reconnect the Telegram account (authorize the phone number). - If the Telegram account has been deleted, you will have to assign another phone number for the Gateway.
- For more details, see Interaction with Telegram.
403 Session storage is inactive
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:
- If you use the SIP.TG cloud storage, check the status in
/gateway. Usually such failures are short-lived. - If you have your own Session Storage, make sure it is running and available. If necessary, switch to the SIP.TG cloud.
403 Worker is inactive
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:
- In the bot’s
/gatewaysection, check the Worker settings. If the server is disabled, select another one or wait until it becomes active again. - If this is your own Worker, start/restart it.
403 Worker address is not set
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:
- In @siptg_bot, double-check the connection type (PBX→SIP.TG) and select an appropriate Worker.
- Create another type of SIP connection (“SIP.TG→PBX” or “IP⇿IP”).
403 Route is not permitted
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:
- Create your own Gateway session. In the bot’s
/gatewaysection, connect the Telegram number that you control. - Make sure that the administrator who previously created the session did not take away your access.
404 Route not found
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:
- Double-check the login/username that you received in the
/gatewaysection. - If this record was previously deleted, create a new one.
- Make sure that your PBX has exactly the login that was issued by the bot (without extra characters or spaces).
Errors when calling SIP → Telegram
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
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:
- Ask the called user to configure call permission: “Settings → Privacy → Voice Calls” → “All users” or add your gateway account to “Always allow”.
- Or use an account that is actually in the target user’s contacts.
404 Not Found / 404 Chat not found / 404 USERNAME_NOT_OCCUPIED
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:
- The number is indeed not registered in Telegram.
- The username does not exist or has been released.
- The profile is unavailable due to restrictions.
- Your gateway account searches for a phone number too frequently.
What to do:
- Make sure you are using the correct identifier (if using a phone — it should be a real Telegram number).
- If it happens often, check if you made a mistake in the format. It might be better to use the internal user_id.
405 REGISTER is required first
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:
- Enable “Registration” mode on your PBX side (register the PBX→SIP.TG trunk). For more details, see Interaction with PBX.
408 Timeout of waiting RPC result
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:
- Reduce the intensity of outgoing calls.
- Wait and try again if it was a temporary failure.
470 Anonymous user
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:
- Usually you need to either call by a confirmed number or username, or have the user add you to contacts or write to you first.
500 (others)
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:
- Check the stability of the network, repeat the call.
- If the error appears regularly on the same number, seek help. For more details, see How to Get Help.
503 Account is not running
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:
- Make sure that the PBX→SIP.TG trunk is successfully registered and the Worker sees an active account.
- Sometimes it helps to restart the trunk on the PBX. If necessary, see Interaction with PBX.
503 Session is not running
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:
- Double-check the session status in
/gateway, if necessary, re-authorize the Telegram number. - If the error occurs frequently, try switching to another Worker or restarting the account.
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
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:
- Reduce the dialing speed (on the PBX side or your script).
- Use several different Telegram accounts to distribute the load.
- Wait for the specified time “retry after N”, then try again.
503 Worker is not ready
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:
- Wait 1-2 minutes and try the call again.
- Or in @siptg_bot, select another Worker server for your connection.
Errors when calling Telegram → SIP
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
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:
- If you really need to receive calls from an account that is also a gateway, it’s better to use a different mode for it (e.g., Softphone) or another Telegram account without Gateway.
503 SIP account is unavailable
503 SIP account is unavailable
503 Worker is unavailable
503 Worker is unavailable
If none of the listed solutions helps, seek assistance. For more details, see How to Get Help.