Using the JAWS Scripts For Microsoft Teams
Doug Lee
Last Revised April, 2020

This Guide provides tips for using Microsoft Teams (Teams) with JAWS For Windows and these scripts. When the scripts are installed and Teams is open and focused, this document can be opened via a double press of JAWSKey+F1 (or Insert+F1). For more general information about using Teams with a screen reader, consult Using Microsoft Teams With a Screen Reader.

Development of these scripts was funded in part by this author's employer, Level Access, for which this author is most grateful.

Table of Contents

• System Requirements For JAWS Users
• Script Installation Instructions
• Key Sequences
• Using Teams With JAWS and the Scripts
  • Script Commands and Features
  • The Message Reading System
    • Message Reading Format Customization
    • Reading Specific Parts of a Message On Demand
    • Unrecognized Message Formats
  • Using the Calendar Page
• Known Issues
• Revision History

System Requirements For JAWS Users

These scripts require the following for correct operation with Teams:

• JAWS 17.0.1806 or greater. (JAWS versions prior to 17.0 do not support web site specific scripts.) The original JAWS 17.0 release did not include the GetElementXML() function that was added in the JAWS 17.0.1806 release in April, 2016.

Note: As of September, 2019, running these scripts under JAWS versions older than the JAWS 2019 August update will require the companion Script Load Manager (slman) scripts to manage Electron app script loading for your JAWS version. If you are upgrading these Teams scripts, install the Teams script upgrade before installing the Script Load Manager.

Script Installation Instructions

To install these scripts on a new system:

1. Load JAWS if this has not already been done. This will require administrative privileges on the computer.
2. Run JAWS as the user for whom the scripts are to be installed. This and the following steps must be performed for each user of the computer who will be using JAWS with these scripts.
3. Download and run, or run directly, the installer for these scripts; and follow the on-screen directions. Be sure to install the scripts in the currently running JAWS version if a JAWS version list is presented.
4. To verify successful installation, type Insert+Q while Teams is in focus. Part of the JAWS spoken response should be a revision number. If you do not hear a revision number, the scripts are not correctly loaded. If you are using an old JAWS version, it may be necessary to install or reinstall the Script Load Manager (slman) scripts to manage Electron app script loading for your JAWS version.

Key Sequences

These scripts incorporate commands that consist of sequences of keystrokes, all beginning with a common prefix, or "command keystroke." This approach allows many script commands without the risk of conflicting with application keystrokes. See the "Multi-Key Command Sequences" section of the "Common Script Elements" document for further details, including how to explore the available script commands (similar to exploring a menu system), and how to change the Command key if necessary.

By default, the Command keystroke for these scripts is [. This document may refer to this keystroke as [ or Command; so, for example, [ Tab and Command Tab both refer to typing the prefix key, then separately the Tab key. Some sequences may consist of more than two keystrokes, or "levels"; for example, [ d r would refer to typing [, then d, then finally r.

Using Teams With JAWS and the Scripts

Script Commands and Features

The scripts provide the following features, commands, and command modifications:

Message reading system

A system for improving the reading of messages. See The Message Reading System for details and relevant commands.

Automatic fix for Teams window structure problems when possible

Sometimes, Teams' accessibility information winds up owned by another window that is not part of Teams, which causes screen readers to become confused. These scripts try to detect and rectify this situation when Teams takes focus. If you hear an announcement like

Teams needs to be maximized and/or restored in order to fix a problem affecting screen readers. If this fails, restart Teams.

try flipping Teams between the Restored and Maximized states. If this does not work, restart Teams.

[ C

Moves focus to the tree of teams and channels, or to the tree of recent chats, if either is available on the current screen.

[ N and [ P

Move focus to the next and prior areas of the screen, respectively. These command sequences are duplicates of the native Ctrl+F6 and Ctrl+Shift+F6 commands and are included for those who prefer to avoid key combinations that require moving the hands away from the home row on the keyboard.

` (the grave accent key)

Moves focus to the next control that allows it. This key acts like Tab but is capable of reaching some controls that Tab may skip, such as links inside a message.

[ B

Bring up a list of buttons for selection. Press Enter on a button's name to click the button, or press Esc to close the list without activating any buttons. This command can be especially useful for finding "Hang up" and other call management buttons quickly.

[ L followed by a digit

Focuses a list by its position among displayed lists. [ L 1 focuses the first list, [ L 2 the second, etc. [ L 0 will focus the tenth list, if that many exist. The order of lists may not correspond to screen order.

[ S

Announce who is currently speaking in a call or meeting. Only tested in separate meeting windows but may work when the meeting is part of the main Teams window.

[ V

Announce who is currently sending video in a call or meeting. Only tested in separate meeting windows but may work when the meeting is part of the main Teams window.

[ T

Move focus to the first tab control on the screen, or the next one if more than one are available and one already has focus.

JAWSKey+F1 typed twice quickly

Opens this document in the default browser.

Insert+T

Says and Brailles, after the title, as many of the following as are applicable:

• the name of the displayed program area (Activity, Chats, Teams, Files, etc.).
• The sender's online status when a one-on-one chat is on screen. When the sender's name is not already in the title, it is also included.
• Any indicators ("badges") for missed events, such as chats or team messages.
• Any notification banner text on screen, such as when an automatic sign-in failed and the user must sign in manually.

If, in a one-on-one chat, the status appears as "Status unknown," it may be necessary to wait for Teams to update the status. If this condition persists for more than a minute, it may be necessary to sign into Teams.

Ctrl+JAWSKey+V typed three times quickly

Brings up, in a JAWS virtual viewer, a list of the Teams versions so far seen. Each version will be shown with the date on which it was first run with JAWS and these scripts. This is meant to simplify identification of problems arising from Teams updates, although the Teams HTML code can change without a corresponding change to the version number.

The scripts also provide the following features:

• Focus is placed on popups, such as an organizational Login page, as appropriate when Teams itself tries to focus the main window but without allowing keyboard users to navigate.
• The virtual cursor is turned off by default to simplify navigation. Use Insert+Z to enable the virtual cursor again if and when desired.
• Significant effort is included to reduce extra menu events, focus change announcements, and other extra speech resulting from using arrow keys to move among replies in a threaded conversation while using a web-based Teams instance, as opposed to using the Desktop application. These issues only occur under, and the efforts are therefor only applied during the use of, JAWS versions older than JAWS 2020.
• The SayLine JAWS command, when typed on a message list item, will
  • Speak the message instead of saying "blank."
  • Announce full messages instead of truncating very long ones.
  • Virtualize the message for review if pressed twice quickly. The normal function of this action is to spell what SayLine would say; however, spelling an entire message, with all help information provided with it by Teams, is not practical and could crash JAWS for very long messages.
• Virtualize a message on the command JAWSKey+Shift+V as is done in the standard JAWS scripts that come with JAWS 2020 (March update or later).
• Name menu buttons in the Notifications page of Settings.
• Indicate when a feed filter returns no results, as part of the name for the "Remove feed filter" button.

The Message Reading System

A Teams chat message can include several types of information: content, reactions, reply count, attachments, flags such as Edited, etc. The message reading system described in this section can simplify accessing specific parts of a message. This is accomplished in two ways:

• Automatic: By default, the scripts reformat messages so as to present information in an order that is more efficient, at least in the view of this author. The scripted command sequence [ F will cycle among available message formats. See below for information on the available message formats. The current message format will govern how each message is read during navigation with arrows through a message list.
• Manual: Typing [ followed by a number between 1 and 9, inclusive, will read a specific portion of the current message.

Message Reading Format Customization

The key sequence [ F will cycle between available message formats. The default format is "Default custom," which rearranges information in messages in a way pleasing at least to this script author. The "Native" option reverts message reading to the native format presented by Teams itself.

The "Default custom" message format presents message information in the following order:

• Any flags, such as reaction indicator and reply count.
• The message time. Use the sequence [ 1 to get the message date.
• The message sender.
• The message content.

Note that any change to the message reading format via [ F will remain in effect until changed again, even if JAWS is restarted.

Reading Specific Parts of a Message On Demand

Sequences consisting of [ followed by a digit between 1 and 9 will read specific portions of the current message:

• [ 1 reads the date of the current message.
• [ 2 reads the time that the current message was written.
• [ 3 reads the name of the sender of the message and the sender's online status when possible.
• [ 4 reads the content of the message.
• [ 5 reads any "flags" associated with the message. Some possible flags, as defined by these scripts:
  • Edited: The message has been altered since first being sent.
  • Has reactions, has attachments.
  • Replies: A count of the replies to the message. If there are new replies, this will also be indicated.
• [ 6 is reserved for reading attachment information for the message but is not yet functional.
• [ 7 reads the reaction types and counts for the current message.
• [ 8 reads the message's help text.
• The sequence [ 9 is reserved for future expansion.

Unrecognized Message Formats

From time to time, a message may appear that the scripts are unable to recognize for format alterations, separation into parts, etc. This can occur because

• The message is system-generated and neither has nor needs all of the normal elements of a user-generated message.
• Teams has changed since the scripts were written, and the message format has changed such that the scripts no longer recognize it.

Using the Calendar Page

Activate the Calendar page with Ctrl+4. Teams offers two calendar views: Day view and Agenda view. A button for the view not currently showing will appear in tab order.

The Day view appears by default and shows meetings in a table, in which Left and Right arrows move among meeting links and Enter on a link populates the Details area from the meeting. In the Agenda view, all meetings for the current week appear in a treeView. Pressing Enter on an meeting again populates the Details area with the details for that meeting. Details can be reached in either view via Tab.

Known Issues

Issues shown in this section may be fixed in future script and/or application or JAWS updates but are not addressed as of this writing. Note that specific issues may and may not be present depending on the exact version of Teams HTML or application code running.

Messages in a meeting chat that is part of a separate meeting screen may not read in exactly the same way as messages in a meeting chat that is part of the main Teams screen.

The JAWS virtual and touch cursors may sometimes provide more information than the PC cursor, especially in Settings pages where they can find hints for fields, group headings, etc.

In JAWS versions 2019 and older, arrowing through replies in a thread, and possibly in other places, could cause any of the following anomalies:

• JAWS acts like a menu is being activated and deactivated very quickly.
• JAWS gets stuck acting as if a menu is open when no menu is active.
• Focus jumps through replies in a thread to the final Reply button unexpectedly instead of moving up or down to the next message as requested.

TreeView item states (Collapsed and Expanded) are not always properly indicated.

When focus switches from outside of Teams directly into a chat message list, Braille will not necessarily mirror speech for the focused chat message until the user tabs away from and back to the list once. This is due to JAWS not calling the BrailleCallbackObjectIdentify function until the user first moves among controls in Teams.

Some list controls allow navigation with up and down arrows to move out of the list, or to wrap from one end of the list to the other.

Activating one of several unread items in the Activity app on an iOS device clears all unread activities immediately from a simultaneously running instance of Teams on Windows, even though the as-yet unexamined activities remain marked as Unread in iOS. Last verified in Teams version 1.2.00.8864 on Windows and 1.0.72 on iOS (April 25, 2019).

Revision History

This is the revision history of these scripts, most recent revision first:

Revision 173, October 07, 2020, tested in Teams app version 1.3.00.21759

• The sequence [ C for jumping to the recent chat or team tree, depending on which is on screen, works more effectively in Teams 1.3.00.26064 and other nearby versions.
• Special adjustment for chat history lists in a meeting screen for Teams version 1.3.00.26064: Messages such as conversation joins that include a long ID string instead of a person's name are corrected to include the name instead of the ID. The ID will still appear along with the name in the JAWS virtual view for those who use it, however.
• During navigation among rows in the Calls > Contacts table, the scripts reduce extra speech, remove duplicates of the same phone number on the same line, and better format phone numbers for speaking.
• In other places in Teams, such as the Activities list, the initial phrase "Profile picture of" is removed for brevity.
• Alt+Left presses the Back button in screens where it can be found.

Revision 162, September 01, 2020, tested in Teams app version 1.3.00.21759

• The [ S sequence for announcing current speakers in a meeting should work in at least Teams 1.3.00.21759. (The method used to display this information has changed among Teams versions.)
• The sequence [ V reports who is sending video. This and the previous [ S sequence have only been tested in separate meeting windows, not when the meeting is part of the main Teams window.
• Presence indicators like "in a call" become part of the Insert+T response in a popout chat just as in a main-Teams-window chat.
• The [ C sequence for moving to a chat or team tree works correctly in Teams 1.3.00.21759, where it previously moved instead to the New Chat button in the Chats app.
• Tab and Shift+Tab should less often read the names of Minimize, Maximize, and Close buttons along with other unnecessary material.
• Though Tab and Shift+Tab remain silent in a document preview window for an Office file from the Files tab of a team channel, the JAWS SayWindowPromptAndText (JAWSKey+Tab) and SayLine (JAWSKey+Up) commands announce the focused control, which Tab and Shift+Tab do move among. This fix is experimental and subject to improvement.
• Keystroke names in this document are more consistent.

Revision 150, August 18, 2020

• JAWS should be more responsive during the entry of text into an edit control, such as during the entry of a chat message. This especially affects users who leave Key Echo set to Characters and who also use a braille display.
• The sequence [ C will, when possible, move focus to the tree of teams and channels or to the tree of recent chats. One of these two controls must already be on screen for this command to work.
• When a one-on-one chat is on screen but its sender's name is not part of the window title, JAWS will include the sender's name just before the sender's online status (presence). This often happens when Teams is launched and a chat window appears initially.
• Braille should mirror speech for messages in a chat message list. This may not be true when focus switches from outside of Teams directly into the message list, until the user tabs away from and back to the list once. This exception is due to JAWS not calling the BrailleCallbackObjectIdentify function until the user first moves among controls in Teams.
• Fixed a bug that could cause some localized strings not to be spoken where expected.
• Several efficiency improvements, including both optimization of code and removal of obsolete code.

Revision 139, July 01, 2020

• Key sequences consisting of [ L followed by a digit will focus a list by its position among displayed lists. [ L 1 focuses the first list, [ L 2 the second, etc. [ L 0 will focus the tenth list, if that many exist. The order of lists may not correspond to screen order.
• The [ T sequence for moving focus among tab controls should work with more tab controls.
• [ S will attempt to announce who is currently speaking in a call or meeting. This information is likely to be out of date, however, due to the way accessibility information is managed by Teams and/or Electron. Focusing a participant's list item updates that participant's information. This is the initial reason for the above command sequences for focusing lists.
• Insert+T's reporting of sender online status is more reliable (sometimes the status was previously not included).
• JAWS should sometimes repeat less information when Teams receives focus from another application.
• Tabbing may be faster in some cases.
• For those who need to change the Command key, the left bracket ([) by default, the system is significantly improved, so that you need not type the key or key combination out as a name or string of key names. You may edit the keystroke names before accepting them, but JAWS will type them out for you now. The system is documented in more detail in the Multi-Key Command Sequence section of my Common Script Elements page.
• The installer contains version and product information visible from the Details tab in Windows Explorer, to better identify its contents. This update is being applied to all projects.
• A "directives" text file is included that provides information on how to install this set of scripts manually. See "Handling Directives Files" in the "Common Script Elements" document for further information.
• teams.jcf is no longer included in the installer and file set, but the installer inserts needed lines into it if necessary. This allows users to customize JAWS behavior in Teams without having to redo settings after every script update. The specific jcf settings inserted by the installer also appear in the directives file to help those who wish to install the Teams scripts manually.
• Screen readers respond better to activation of same-page links in this document. (This update may have slipped out in an earlier release but without being documented.)

Revision 116, April 19, 2020

• The messages for these scripts are now distributed in XML rather than jsm files so that translators can create translations with no need for script source recompilation. See the Script Translation Procedure document for details on how to translate these scripts, including how to update the XML message file.

Revision 108, April 15, 2020

• The JAWS Insert+T command will include, when applicable,
  • The sender's online status when a one-on-one chat is on screen.
  • Any notification banner text on screen, such as when an automatic sign-in failed and the user must sign in manually.
• The sequence [ 3, for reading the sender of a message, includes the sender's online status when possible.
• Sometimes, Teams' accessibility information winds up owned by another window that is not part of Teams, which causes screen readers to become confused. These scripts try to detect and rectify this situation when Teams takes focus. On failure, the scripts produce an announcement advising the user how to attempt to fix the problem manually.

Revision 99, April 14, 2020

• A bug in the processing of very long messages through JAWS that could result in messages not reading or reading incompletely is fixed.

Revision 98, April 07, 2020

• Much repetition during navigation through messages in a chat should stop.
• There is a new system for improving the reading of messages. See The Message Reading System for details and relevant commands. This system is still a work in progress. If you encounter problems or don't like the new format, you can always use the sequence [ F to switch back to native format, where messages are spoken exactly as they are provided by Teams itself. Even when native format is in effect, the commands for reading portions of the current message will still operate as described.
• The Accent key, `, will attempt to focus the next control that allows focus, regardless of whether the Tab key would reach it. This can be useful for reaching links in messages and other controls that the Tab key may skip.
• The sequence [ B brings up a list of buttons for selection. Press Enter on a button's name to click the button, or press Esc to close the list without activating any buttons. This command can be especially useful for finding "Hang up" and other call management buttons quickly.
• Some buttons with numerical names, which tend to indicate counts such as number of chat participants, are named by their mouse hover titles when possible. The count is still spoken after the title.
• Multiple removals of team members indicated in a single message will say "More than one member has been removed from the team" rather than "messages_removeMembersTeamBySystemSystemMessageOneTarget." Teams may fix this issue internally in a future update.
• If arrows, Home, End, etc., in a message list read obsolete information, this should no longer happen. This issue was never observed or reported but was found to be possible, and thus fixed anyway.
• Ctrl+Backspace is protected from temporarily freezing Teams under some conditions, as reported in the "What's New" documentation for the JAWS March 2020 update. This issue is also addressed by JAWS' built-in Teams scripts for that JAWS version.
• The VirtualizeCurrentControl command, JAWSKey+Shift+V, virtualizes the current message in these scripts as it does in the JAWS 2020 standard JAWS scripts for Teams. At this time, typing Insert+Up twice will also do this as it has in these scripts for some time. Both of these commands will virtualize the actual message as it is presented by Teams, not any reformatting of it presented via the scripts' message reading system.

Revision 71, March 10, 2020

• A significant attempt is included to minimize problems in the web-based Chrome instance of Teams during navigation among replies in a threaded conversation. In the web-based Teams version, Up and Down arrows to move among replies cause a large number of spurious menu events, focus changes, and extra speech. These issues appear to apply only in JAWS versions older than 2020 and do not apply in the Desktop Teams application. As such, the workaround code is written to apply only to those situations and to be ignored otherwise.

Revision 62, March 4, 2020

• Initial public release. Revision 61 was published on February 21; but due to an oversight, there was no link provided to the scripts even though they were available via direct link. This revision consists of the same code as revision 61.