Skip to main content
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:

​
Frequently Asked Questions

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.
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.
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.
The entire SIP.TG infrastructure is distributed across multiple data centers. Nevertheless, for mission-critical systems, you might consider your own Worker servers.
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).
Yes, but this means that everyone will be using the same Telegram account, and incoming calls will come to all devices simultaneously. As soon as one person answers, the call will be dropped for the others.
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.
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.
Our SIP stack is based on Yate, where the default UDP port range is 16384-32768.

​
General Issues

  • 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.
As with the Softphone, this is most often a question of codecs or network restrictions.
  • Try specifying a specific codec (alaw or mulaw).
  • Make sure that UDP traffic is allowed.
  • Make sure that in the SIP account settings (Gateway), the method RFC2833 or INFO is selected, compatible with your PBX.
  • Try switching the codec, sometimes inband DTMF and high compression don’t work well together.

​
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.
Essence: Standard response when using SIP Digest Auth. The PBX sends an INVITE or REGISTER without a complete set of authorization data, and the SIP.TG server requests authorization.
If error 401 appears repeatedly many times in a row, it means that either the password/login is incorrect, or Digest Auth support is disabled on the PBX side.What to do:
  • Make sure that the login/password from @siptg_bot (section /gateway) is correctly entered in your PBX settings.
  • Check that SIP authorization mode (Digest Auth) is enabled in the PBX itself.
  • If necessary, change the password in /gateway and enter it again.
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).
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.
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.
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 /gateway section 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.
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).
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 /gateway section, 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.
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.
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 /gateway section, 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.
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”).
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 /gateway section, connect the Telegram number that you control.
  • Make sure that the administrator who previously created the session did not take away your access.
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 /gateway section.
  • 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.
Essence: The Telegram user has restricted the circle of people who can call them (e.g., only contacts or users with premium subscription), 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.
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.
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.
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.
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.
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.
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.
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.
Essence: SIP.TG has lost connection with the Telegram session storage, so it cannot find out the current status or create a call.What to do:
  • If you use cloud storage, wait for recovery (usually a minute or two).
  • If your own Session Storage, check the logs and status of the module.
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.
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.
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.
Essence: During an incoming call from Telegram, the Worker could not reach your PBX. This can happen if the PBX→SIP.TG trunk is down, or if you have IP-to-IP, but the required port is not responding.What to do:
  • Make sure that the PBX is registered (with PBX→SIP.TG) or that the IP-to-IP connection is active.
  • Check that SIP/UDP packets are not blocked in your firewall, and that you have opened RTP ports.
  • For more details, see Interaction with PBX.
Essence: The Worker server is currently unavailable for call transfer (network problems or restart), and the call is rejected with code 503.What to do:
  • Wait for some time or switch the Gateway account to another Worker (the bot’s /gateway section).
  • If it’s your own Worker server, check its logs and restart if necessary.
If none of the listed solutions helps, seek assistance. For more details, see How to Get Help.
⌘I