This manual is intended for volunteers of the TSF, but anyone else is free to take a look as well.
Every now and then users will report bugs in Telegram. The step-by-step guide and troubleshooting tips on this page will help you deal with those reports in style and eventually help Telegram get rid of the bugs themselves.
See the Bug Hunting Algorithm for tips on investigating new issues.
We use Trello boards to keep track of bugs (sorry, these boards are TSF-only, here's how you join), features and user suggestions, so your first stop when encoutering a bug report is Trello search. Most likely, we already know about the issue — sometimes it is not a bug at all. So make sure you study all the relevant cards.
If you have found the issue on Trello, leave a comment in the card with your user's #tq tag and device info (skip this step if the card already has too many comments of that kind and a ‘trending’ tag). Then go right to step 4.
Trello cards are organized in lists that are pretty self-explanatory:
We also use some labels:
Orange — Our developers are fully aware of this issue and will or will not fix it eventually.
Purple — This issue will be fixed in the upcoming public release and is already fixed in the beta version.
Black — This is a frequent issue, we're getting many complaints about it.
Red — This card is no longer needed and is scheduled for deletion.
IMPORTANT: Please see the Bug Hunting Algorithm after this manual for an in-depth look at investigating bugs.
If you can't find anything useful on Trello:
Reporting a bug is in many regards like convicting the developer of a crime. Just as in that case, you need a clear vision of what happened and why, hard evidence (screenshots) and witnesses (users). Unlike in a criminal case, though, it is considered appropriate and even necessary to reproduce the deed (see if you can reproduce the bug and get the same results).
Another crucial difference: our defendant is also the judge. He is accountable, of course, but still biased. It is in the developer‘s best interest to convince you and the public that the bug is not related to his work. Server-side devs will blame the client devs, client devs will blame the server-side devs — and they all together will blame the OS and device manufacturers. While sometimes this is true, we need to leave no escape for them if it isn’t. Blury bowl of berries
If the bug is not mentioned on the Issues board and the Troubleshooting manual doesn't have any special instructions for the case, we need to report it on Trello.
A new issue should have no labels at first. It can only become ‘confirmed by devs’ when one of the developers has seen it — better leave labelling to them.
Once we‘re done, we need to get back to the user and tell him that we’ve located the issue or are investigating it. You never know how long that might take, but the user must know that he succeeded in alerting us — and helped us greatly.
We are terribly sorry that you are not able to send out your GPS location via Telegram on iOS8. We reproduced it and are already working on a bug fix. Your issue #issue_xpdMFJhw has been recorded and we'll get back to you as soon as we have any news.
This allows us to use Telegram hashtag search to track issues for follow-up questions. The bot can use these hashtags to send automatic replies when a bug is fixed. We can also search for this issue on Trello by its ID.
And remember that in order to achieve this goal with a clear conscience, we need to respect our users' time and effort — a little more on this below:
One may think that users are people with problems. Wrong. It is us, who have problems — the user is just a convenient medium for studying them. Our problem is either that something is wrong in our system. Or that we can't understand what the user is doing wrong. When you look at it this way, you quickly realize that the user is our most important asset when it comes to bugs. He can help us identify bugs and improve usability.
So when somebody comes with a problem, we are not looking for a way to make him go away. Instead we must do all we can to not let the user leave before we find the problem. This means that everything you ask him to do must tell you something important. Nobody enjoys rebooting their phone or logging out and in. The general rule is minimum actions — maximum effect. Rabid bunnies alert
If you do ask something that requires at least some effort, please be nice about it! People don‘t have any obligations to Telegram — we need to convince them to help us and to thank them when they do. It’s the least we can do.
Now that we're done with the basic reporting process, below are some common issues and what you should do when somebody is complaining about similar stuff.
This advanced troubleshooting guide is intended for volunteers of the Telegram Support Force.
Everyone else is also welcome to take a look. Help friends and loved ones — or troubleshoot yourself!
iOS: Device must run iOS 6 or higher.
- If SDK >= 14 —> Android version must be 4.x
- Ask whether other applications install ok
- If nothing helps we need to know the Android version and device model
The following cases cover pretty much all the complaints:
In case it's none of these five (but it must be one of these five, really), this is one of the worst things that can ever happen in Telegram. We need to know:
What we need to know if nothing helps:
We currently have two types of notifications on Android: GCM and our own custom notification service that is independent from Google. Note that Google notifications (GCM) just won‘t work properly on some Android devices. The Telegram notification service is reliable, but requires additional battery resources. It doesn’t and shouldn't take much though, so please report all drastic battery-draining cases immediately.
NOTE: Huawei and Xiaomi devices have evil task killer services that interfere with the Telegram notification service. In order for our notifications to work, users need to add Telegram to allowed apps in those devices' security settings. Huawei: Phone Manager App > Protected apps > Add Telegram to the list. Xiaomi: Services > Security > Permissions > Autostart, find Telegram and enable autostart.
If the user does not want to use the Telegram Notification Service (in this case we cannot guarantee stable notifications) and has problems with GCM notifications:
In case you went through all the steps to no avail, we need to know:
User doesn’t see his contacts in Telegram. Or sees numbers instead of names in Messages list.
Important: Naturally, one of the easiest ways to solve this would be to save the number in international format. Do not advise this before other methods. Our systems must correctly parse any contacts. Therefore it is imperative to collect these samples and bring them to your local group so that we can adjust the algorithms.
Things we need to know if nothing helps:
Things we need to know if nothing helps:
Make sure that we're really talking about speed issues here. In Telegram, 1 check = message sent, 2 checks = message read (opened by the recipient).
What we need to know:
When people are reporting connection issues, check twitter first: are there any widespread problems. If the problem is local, we need to find out a lot of information before things can be investigated. Things to ask:
Don't forget to include with your report:
It is possible that we'll need a Traceroute to our servers, here's how you get that. Wait for instructions from the server cultists to get the right IP to trace the route to — each case potentially requires a different one.
If none of the two, pass to the volunteer group. We need to know:
NOTE: Support accounts are slightly different from ordinary user accounts. Due to some limitations, it is normal if you don't see the correct last seen time for users who are contacting Support.
The changes that come with blocking sometimes do not take effect immediately. Give it a few minutes, maybe half an hour — and the blocked user will stop seeing the status.
If a blocked user restarts the app or relogins, but can still see online status — pass to the volunteer group. This cannot happen under normal conditions.