Troubleshooting
For the correct operation of the Softphone in Telegram, you need to:
- Have an active Softphone subscription in the @siptg_bot.
- Make sure that in Telegram privacy settings, voice calls are allowed from “Everyone” or at least from @siptg.
- Correctly specify the SIP server address (with the necessary port if it’s non-standard), login, and password in the bot.
- If necessary, configure audio codecs and “Dialing Rules” so that they meet the requirements of your PBX or SIP provider.
Frequently Asked Questions
Softphone — is when you use Telegram as a SIP client (linking to any SIP operator).
Gateway — is when you connect a Telegram account to a PBX so that Telegram calls are processed by the PBX.
Yes. Voice stream through Telegram is an internet channel, it doesn’t interfere with your GSM calls.
When creating an account, activate the “Call Recording” checkbox. Available on a paid subscription (5 EUR/month per account). If necessary, you can select a separate channel/chat where audio files will be saved.
Yes. In the /softphone section of the @siptg_bot bot, open the SIP account and click “Disable”.
In the @siptg_bot bot, open the settings of the desired account, click “User” and select your colleague’s Telegram profile. Now all incoming calls will go to them, and you will remain the Owner.
Yes, if your “Softphone” subscription allows the required number of accounts. You can create several SIP accounts. For outgoing calls, a request to select an account will appear before each call.
If you have a non-standard port on the operator or PBX side, specify it in the “Domain” or “Proxy” field with a colon (for example: sip.example.com:5062). For the standard 5060, it’s not necessary to specify.
Problems and Debugging
Below is an expanded list of problems that our users have encountered.
Symptoms
- No information about the incoming call appears in Telegram.
Possible causes
- Voice calls are prohibited at the level of your Telegram account.
- The SIP account is being used in parallel on another device (in another Softphone, in a widget for calls through the browser, etc.).
- The connection between your Telegram account and our @siptg was lost.
Solution
- Check the settings in Telegram: make sure that in the “Privacy and Security → “Voice Calls” section, the “Everyone” option is selected.
- Update the SIP account password on the SIP provider or PBX side, and specify the new password for the account in the
/softphonesection of the @siptg_bot. - Open the chat with @siptg and send any message.
Symptoms
- When an incoming (or Callback) call arrives, the user doesn’t have time to answer it, and in the @siptg chat it’s shown with the status “Rejected call”.
- As a result, all incoming calls are automatically rejected on all devices linked to the Telegram account.
Possible causes
- On one of the devices, the Telegram application is “stuck” in an active call state, although there are no signs of an active call.
- During an incoming call, you’re talking through another application or via mobile connection, and Telegram doesn’t have access to the device’s microphone.
- You’re trying to make a test call to yourself. For example, while making a call via mobile connection (thereby blocking the microphone), the call comes in through Telegram, and due to the other active call, the new Telegram call is rejected.
Solution
- Identify the problematic device: each of your devices must be disconnected from the internet in turn until the incoming calls stop dropping. After that, the problematic device needs to be restarted or the Telegram application should be completely unloaded from memory on it.
- Make a test call involving two different devices, and ensure that your Telegram account is not used on the second device.
- If the problem repeats, collect logs from the problematic device for further analysis and troubleshooting. See Getting Log Files from Telegram for details.
When you send a number to the chat, the bot tries to call you back (callback). If you don’t accept the incoming call in Telegram, the outgoing call won’t happen.
What to do:
- Enable call notifications in Telegram.
- Check that calls are allowed from @siptg.
- Confirm the incoming call within 60 seconds.
This is most often related to codec incompatibility or UDP traffic blocking.
Solution
-
In the @siptg_bot bot in the
/softphone→ Configure SIP Account → Audio Codecs section, set a short list, for example:opus,alaw,mulaw.If necessary, specify a specific audio codec (for example, only
alawormulaw). -
If the call is coming from abroad or through mobile internet, try another Worker server.
This is due to the free subscription. To remove the restriction — activate the Softphone subscription. See more at Subscriptions Overview.
This is most often due to an unstable internet connection between the Telegram user and our server.
Solution
- Allow peer-to-peer calls in Telegram settings: ☰ → Settings → Privacy and Security → Calls → Peer-to-peer → Always Allow → Add Users → @siptg
- Change the connection type and device; try calling from your computer via Wi-Fi.
- In the bot @siptg_bot in the section
/softphone→ Configure SIP Account → Worker select another server that is closer in geographical location.
Symptoms
- During an outgoing or incoming call, the subscriber can’t be heard, or the sound suddenly disappears.
- The call drops within 5-10 seconds.
Possible causes
- Unsuitable or conflicting audio codec.
- The provider or PBX doesn’t accept the current set of codecs, or Telegram doesn’t have time to negotiate the audio stream parameters.
- Incorrect RTP settings or errors in voice packet transmission.
Solution
-
In the @siptg_bot bot in the
/softphone→ Configure SIP Account → Audio Codecs section, set a short list, for example:opus,alaw,mulaw.If necessary, specify a specific audio codec (for example, only
alawormulaw). -
Check the Worker server and firewall settings.
Symptoms
- When trying to make an outgoing call, the bot reports that there are no available lines.
- Possibly, a code error appears in the logs indicating line unavailability.
Possible causes
- Incorrectly configured “Dialing Rules” that exclude correct numbers.
- Exceeded the number of active SIP accounts allowed by the subscription.
- Errors in SIP account parameters (incorrect login, server, or password).
Solution
- Check and, if necessary, reset the dial rules by entering the value
=in the SIP account settings. - Make sure that the total number of SIP accounts corresponds to the paid subscription.
- Try to restart the SIP account through the
/softphonecommand in the @siptg_bot bot.
Symptoms
- The bot reports that the limits of unsuccessful calls have been exceeded or that the current SIP account is not allowed by the tariff.
- Calls don’t go through due to exceeding established limits.
Possible causes
- The user has independently activated a SIP account without linking it to the administrated subscription.
- Internal limitations of the tariff plan have been exceeded (for example, the number of unsuccessful attempts).
- SIP accounts are incorrectly distributed or activated.
Solution
- Check that the SIP account is enabled and linked in the
/softphonesection of the bot. - Compare the number of active accounts with the data in the
/subscriptionssection. - If the account was activated independently, contact support to reconfigure it for administration.
Symptoms
- When I try to call, an error appears that the account is not started and the call does not start.
- In the
/softphonesection, the account is marked with the ⚠️ icon, and in the settings, the Domain / Proxy / Template fields have such an icon.
Possible causes
- Temporary outage in the SIP.TG infrastructure: no communication between Manager and Worker servers.
- Temporary outage on the side of the telephony provider or PBX: no communication between Worker and PBX/provider servers.
Solution
- Change the Worker server to a different one in the
/softphonesection of the bot. - Wait for the connection to be restored.
Usually errors of this type are recovered automatically after a short time.
Symptoms
- When enabling a SIP account, the error “Invalid parameters (params)” appears. The account remains not connected.
Possible causes
- Required connection parameters are not specified: Login, Password, and Domain.
- The selected Settings Template doesn’t contain a preset value for Domain and Proxy for connection.
Solution
- Set the correct value for the Domain and Proxy parameters (if it’s different), and re-enable the SIP account.
Symptoms
- When enabling a SIP account, after some waiting the error “Time out (timeout)” appears. The account remains not connected.
Possible causes
- Incorrect SIP server address specified.
- Firewall is active on the SIP server.
- SIP server accepts requests on a non-standard port.
- The server’s DNS name returns an incorrect IP address or multiple IP addresses.
- The server’s DNS name returns an IPv6 address, but the SIP server is running only on IPv4.
Solution
- Set the correct value for the Domain and Proxy parameters (if it’s different), and re-enable the SIP account.
- For Proxy, specify the IP address explicitly, leaving Domain pointing to the DNS name.
- Check the receipt of SIP packets using the
sngreportcpdumputilities. - Check the Firewall rules. Set up automatic updates of the whitelist IP addresses from the file
https://files.sip.tg/fw.txt.
Symptoms
- Call recording only works if it’s enabled manually during each call.
- Call recording stops after 15 seconds.
Possible causes
- The “Call Recording” setting is not enabled in the SIP account settings.
- When paying for the “Softphone” subscription, the “Call Recording” option was not added.
Solution
- Check the status of the SIP account settings. See Configuring the Softphone for details.
- Add the “Call Recording” option in the subscription settings. See Softphone Subscription for details.
Symptoms
- In the
/softphonesection of the bot, there are no buttons with account settings (Login, Password, Domain, Proxy, Worker, Dialing Rules, DTMF, Audio codecs). There are only Switch off and Delete buttons.
Possible causes
- You are a User of the SIP account, but not the Owner.
Solution
- Contact the owner of the SIP account with a request to change your settings.
See Owner and User roles for SIP account for more details.
- 403 Forbidden: incorrect password/login, or the provider has blocked you.
- 404 Not Found: incorrect SIP domain or subscriber number not found.
- 408 Request Timeout: the provider is not responding, try another Worker or check the firewall.
- 503 Service Unavailable: the operator is experiencing temporary problems or Telegram limits have been exceeded (Too Many Requests).
- 603 Declined: the call is rejected by the operator or the called party.
- Telegram limitations with mass calls:
With a large number of outgoing calls, the system may issue503 Too Many Requestsor408 Timeout of waiting RPC resulterrors. The solution is to reduce the speed of dialing. - Problems with DTMF:
If button presses are not recognized when interacting with the voice menu (IVR), change the DTMF transmission method in the settings (for example, switch frominbandtoRFC2833orINFO). - Problems with registration on the Worker server:
Sometimes SIP registration doesn’t occur because the Worker server doesn’t respond or the IP address isn’t on the “whitelist”. The solution is to check network settings and add the necessary IPs to the whitelist. - Conflicts when independently updating settings:
If users independently change SIP account parameters (for example, audio codecs, dialing rules), this can lead to errors in mass management. Centralized administration through a common “admin” account is recommended.
If the described actions didn’t help, ask for assistance. See How to Get Help for details.