Accessible Telegram: Script to Enhance Telegram Web Accessibility for VoiceOver Users on iOS

Core Accessibility & Navigation

• Simplified Message Navigation: Each message is converted into a single, focusable item that acts as a "heading." This allows users to easily navigate from one message to the next using their screen reader's heading navigation feature (e.g., the Rotor in VoiceOver).
• Accessible Context Menus: Replaces Telegram's default, inaccessible context menus with custom-built, fully accessible dialogs. This allows users to reliably perform actions like replying, forwarding, copying, and deleting messages or chats.
• Enhanced Chat List: The main chat list is significantly improved. Each chat is clearly labeled with:
  • Chat type (Private Chat, Group, or Channel).
  • The number of unread messages.
  • The sender of the last message.
  • A summary of the last message text.
• Navigable "Unread Messages" Divider: The "Unread Messages" line within a chat is converted into a proper heading, making it a landmark you can quickly jump to.

Live Announcements

• Real-Time Status Announcements: Clearly announces when a user's status changes to "online" or "is typing," providing real-time feedback during a conversation. It filters out unnecessary clutter like "last seen recently."
• New Message Announcements: When a new message arrives in the currently open chat, its content is announced by the screen reader.

Media & File Handling

• Accessible Audio (Voice & Music):
  • Voice and music messages are presented with a clear, descriptive label that includes the sender, title, artist, and duration.
  • Adds a large, clearly labeled "Download" button for all music files, a feature that was previously very difficult to access.
  • Provides an accessible menu for audio player controls (Play/Pause, Next/Previous Track, Playback Rate, etc.).
• Accessible Media (Photos, Videos, Albums):
  • Clearly identifies messages containing photos, videos, GIFs, and stickers.
  • For albums, it announces the total number of items and adds "Previous Media" and "Next Media" buttons, allowing users to navigate through all items in the collection before opening them.
• Accessible Files: File messages are announced with the filename and size, and an accessible download button is provided for each file.

Interactive Elements & UI Fixes

• Accessible Interactive Buttons: Inline keyboard buttons, links, "Comments" buttons, and "Forward" buttons are all made fully accessible and are presented as distinct controls that are easy to activate. The "Comments" button also announces the current number of comments.
• Improved Lists (Forward & Search): The "Forward to..." screen and global search results are properly labeled, adding context like whether an item is a User, Group, or Channel.
• Message Input Fix: Resolves a critical bug where screen readers would announce the text field twice, making it difficult to type. The script hides the invisible cloned input that caused this issue.
• Hides UI Clutter: Redundant or distracting on-screen elements are hidden from the screen reader to create a cleaner navigation experience.

Hi, and you're very welcome!
It will most likely work on macOS Safari. However, I should mention that the script has been primarily optimized for touch devices like iOS, so I'm not entirely sure how it will perform on a desktop environment.
For example, on Chrome for Windows, it doesn't work as smoothly as it does on iOS, and there can be some issues with clicking on certain options.
If you decide to try it, I would be very interested to hear about your experience!

Hi, thank you so much for the kind words and for your detailed feedback. It's truly appreciated. I'm glad the script is helpful.

To answer your questions:

1) You are correct to ask about the different versions. The script was developed and tested on the `/a/` version of Telegram Web, which is the default version you are directed to. It is not designed to work with the `/k/` version. Thank you for pointing out that the script is currently set to match the `/k/` URL; this was included for some early testing and will be removed in the next update to avoid confusion. While it doesn't cause any harm, the `/a/` version is the intended environment for the script to function correctly.

2) Regarding your question about notifications, my understanding is that push notifications for Telegram Web on iOS only work correctly when you install the site as a PWA (Progressive Web App) to your Home Screen. That is why you are unable to enable them directly in the browser.

The challenge with this, however, is that an installed PWA runs in its own separate container, which Safari extensions (like Userscripts) cannot access. This means the accessibility script will not function on the PWA version.

However, there is a workaround you could try to get the best of both worlds:

• First, install the PWA version to your Home Screen. You can use this instance primarily just to receive push notifications.
• Then, separately, create a standard Home Screen shortcut that opens the web.telegram.org URL in the main Safari browser.

This setup would give you two icons on your home screen. You'll receive timely notifications from the PWA, and when you want to read and reply to messages, you can open the Safari shortcut to use the fully accessible version with the script.

I hope this helps!

Hi again,

Just a quick follow-up: I've now removed the match for the /k/ version from the script. If you download it again from the source, the new version will no longer include that URL.

Thanks again for pointing it out!

Hi Richard,
Thanks for trying out the script and for the detailed description of the issue. It sounds like the script isn't activating correctly, which is usually due to a small setup issue.
Here are a couple of things to check that should resolve the problem:
1.
Check the Filename: Please make sure the script file you copied into the Userscripts folder has its original, complete name and that the filename ends with the .js extension. Sometimes the name can be changed or cut short during the download or saving process.
2.
Remove the Demo File & Restart Safari: The Userscripts app comes with a default demo.js file. This can sometimes cause conflicts. Please delete that demo file from the Userscripts folder. After you do that, it's very important to fully close Safari (by swiping it up from the app switcher) and then open it again.
The behavior you're describing is exactly what happens when the script itself isn't being loaded, so one of these steps should fix it. Please let me know if that works for you!

Hi everyone,
Just a quick note to let you know that the installation guide in the main post has been updated with clearer, step-by-step instructions. This should help resolve any setup issues.

You are correct, the focus starts at the bottom of the screen.
For a fast way to get to the top of the chat, simply touch the top of the screen with your finger. VoiceOver will focus on the contact's name in the header. From there, you can swipe right to find the "Call" and "More Options" buttons.

Hi, thank you for pointing this out. You've described a very frustrating issue with the Telegram Web client itself, and you're right, it can make navigation very confusing. When you open a chat on your phone, you don't expect the chat list to interfere in the background.
I was aware of this problem, and I specifically designed the script to solve it. Here is the solution:
The script works by turning every single message in the chat into a proper, navigable heading. This creates a clean path for VoiceOver to follow, completely ignoring the chat list that is still active in the background.
So, when you open any chat, simply set your VoiceOver Rotor to 'Headings'.
Once you've done that, you can just swipe down with one finger to move cleanly from one message to the next, just like you're reading a document. By navigating this way, you will stay within the message list and will never accidentally focus on the chat list behind it.
This is the intended way to read through chats with the script. I hope you can enjoy a much smoother and more pleasant experience!

Hi Kushal,
Thank you for reporting this. The behavior you're describing—"heading not found"—is the key indicator that the accessibility script is not running at all. When the script is active, it's impossible for VoiceOver not to find headings, because the script converts every message into one.
This is almost always caused by a small issue during the setup process. Could you please double-check these steps?
1.
Delete the Demo File: Open the Files app and go to the Userscripts folder. Please make sure you have deleted the demo.js file that comes with the app. This file can prevent the Telegram script from running.
2.
Verify the Filename: Ensure the script file you downloaded is named correctly and ends with the .js extension.
3.
Fully Restart Safari: After deleting the demo file, you must completely close Safari (swipe it up from the app switcher) and then reopen it. This forces the extension to reload the correct script.
If you follow those three steps, the heading navigation should start working as expected. Please let me know if that solves it for you!

Hi Kushal,
First, I want to give a big thank you to user26335377 for their excellent help in diagnosing the problem.
They are absolutely correct: if you are not hearing the chat types announced (like "Group" or "Channel"), it's a clear sign that the script has not loaded at all. The "heading not found" issue is just a symptom of this.
The most common reason for this, even when all other steps are correct, is being on the wrong version of Telegram Web. The script is specifically designed to work with the /a/ version.
Let's try a process to force the correct version to load:
1.
First, fully close Safari (swipe it up from the app switcher).
2.
Next, open your Userscripts folder in the Files app. Please double-check that my script file is there and that the demo.js file has been deleted.
3.
Finally, open Safari and manually type the exact address into the address bar: https://web.telegram.org/a. It is crucial to use this specific URL and not rely on a bookmark or browser history.
The page should now load with the script active. To confirm, check if VoiceOver announces the chat types. If it does, heading navigation will now work inside your chats.
I hope this solves the issue for you!

Hi Tayo,
Thanks for the question. I haven't had the chance to test the script on Safari for macOS myself, so I can't confirm if it works.
The "Userscripts" extension required for the script is also available on the Mac App Store, so it should be possible to install it.
If you're willing, could you please test it out and let us know your results? Your feedback would be very helpful for other Mac users.

That's wonderful news, Qinan!
I'm really happy to hear that the instructions helped and the script is now working perfectly for you. Thank you very much for taking the time to report back and confirm that the /a/ version was the key.
Enjoy using it!

Hi everyone,
Just a quick note to let you know that I've updated the title of this post to: "Accessible Telegram: Script to Enhance Telegram Web Accessibility for VoiceOver Users on iOS".
I made this change to better reflect the goal of the project: to let users know that this script offers a new, viable possibility for using the service, not just a minor tweak.
Thank you all for your feedback!

Thank you so much for your very kind and supportive words, Amir. I truly appreciate it.
Your feedback while testing the different versions was incredibly helpful and played a big part in making the script what it is today. I'm just so glad that we finally have a more accessible way to use Telegram.
Thanks again for all your help!

Hi Kushal,
Thank you for the excellent suggestion regarding track position control.
We have explored this possibility extensively. Unfortunately, after trying every possible method, we've concluded that it's not technically feasible to implement on the current version of the web app.
The audio player component is sandboxed in a way that prevents external scripts from programmatically controlling the playback time. Any attempts to simulate a seek command are ignored by the application.
Essentially, no matter what we tried, it didn't work.
We appreciate you taking the time to provide this valuable feedback.

Hi Qinan Su,
Thank you for the detailed bug report.
I have tested for the behavior you described, but I was unable to reproduce the issue.
My "Telegram Web Accessibility Helper" script is specifically designed to address this by ensuring voice messages retain their heading role after being played.