Skip to main content
Webchat v3 is designed to adhere to accessibility standards, specifically WCAG 2.2 Level AA (Web Content Accessibility Guidelines). These guidelines offer detailed recommendations for making web content more accessible to people with various disabilities, including visual, auditory, physical, speech, cognitive, language, learning, and neurological impairments. Cognigy encourages conversation designers to build solutions with accessibility in mind. Ensure that your Webchat is designed to be accessible to everyone, including individuals with varying accessibility needs. This page outlines the following recommendations for implementing essential accessibility features: These measures are intended to make it easier for everyone to use your Webchat.

Label UI elements

Label all UI elements in your Webchat to explain their purpose clearly. Provide users with descriptive labels for each interactive element, including links, text on buttons, and forms. Make sure the visible and non-visible text is meaningful to help users navigate Webchat effectively. Include alternative (alt) text to describe images for users who can’t see them. Screen readers announce this text when users hover over or focus on the element. For example, include alternative text in the Say, Question, or Optional Question nodes for images and other output types that contain images.
Example alt text configured for an image output

ARIA labels

Webchat v3 has ARIA labels that give screen readers and other assistive technologies access to non-visible text. By default, the ARIA label texts are in English, but you can translate them to other languages or change them in the embedding configuration.

Adaptive cards

When you use the Adaptive Card output type in the Say, Question, or Optional Question nodes, ensure that each field in Microsoft adaptive cards contains a title with meaningful text and that the text has a hierarchical structure. Add the following parameters to the JSON of the adaptive card:
  • Add the speak parameter to ensure that screen readers announce a short summary of the adaptive card when it’s received or focused. Without this parameter, screen readers announce each element, which can be hard to follow.
  • Each field contains the label parameter with meaningful text to title the field.
  • Meaningful text blocks contain the style parameter with a value of heading. Headings help all users navigate and understand information more quickly as they create a hierarchical structure in an adaptive card. They improve content accessibility for visually impaired users, as screen readers announce them differently from regular text.
Adaptive card with labeled form fields and heading hierarchy

Add transcripts and captions for media files

If your agent includes media content, such as a video clip or an audio track, support users with different accessibility needs in understanding this material. For video and audio, provide the same content in an alternate format, such as a transcript and captions.

Audio

Provide an audio track along with its transcript. In the Say, Question, or Optional Question nodes, for the Audio output type, add the audio file and paste the transcript into the Audio Alternate Text field. To convert your audio into text, you can use third-party tools such as Transkriptor and Sonix. The audio transcript can have the following format:
The transcript should accurately reflect the number of speakers and their lines, include all the voice content present in the audio, and account for any background music. In Webchat, users can download the transcript in .txt format. In the audio widget, they click menu > Download transcript.
Audio widget with a download transcript button

Video

Provide a video clip along with its transcript and captions. In the Say, Question, or Optional Question nodes, for the Video output type, add the video file, and provide the alternate text (a downloadable transcript) and the URL for captions.
Video output type settings with alternative text and captions URL fields

Transcript

In the Say, Question, or Optional Question nodes, for the Video output type, paste a video transcript into the Video Alternate Text field. To convert your video into text, you can use third-party tools such as Transkriptor and Sonix. The video transcript can have the following format:
In Webchat, users can download the transcript in .txt format. In the video widget, they click the Download transcript button.

Captions

Captions are designed to make content accessible to people who are deaf or hard of hearing, and they include not only spoken dialogue but also relevant non-verbal audio cues. In the Say, Question, or Optional Question nodes, for the Video output type, paste a URL that links to the captions into the Video Captions Url field. To create captions, you can use YouTube. Upload a video, and after the captions are generated, go to Subtitles in YouTube Studio. Click the video, and then select Download to export the captions in .vtt format. Alternatively, you can use Veed.io and Kapwing to generate, edit, and export captions in .vtt format. The file that includes captions should have the following .vtt format:
In Webchat, users activate captions in the video widget by clicking menu > Captions.

Increase text visibility

Text resizing

Webchat supports relative font sizes, so users can adjust the font size to their needs using their browser settings. If you customize the font size in your Webchat widget, make sure that both the Webchat CSS customization and the HTML code of your website work properly with relative font sizes. To do this:
  • Use relative font size units, for example, em or rem, instead of px in the Webchat CSS customization options.
  • Avoid absolute pixel values in the HTML tag embedding the Webchat widget or set font-size to 100%. These approaches allow font sizes to adapt to user preferences. For more details, refer to the Webchat v3.25.0 release notes.

Guarantee color contrast

By default, Webchat v3 adheres to color contrast guidelines, ensuring a clear difference in brightness between text and its background. This means that if a dark color is used as the primary background in Webchat, the text is automatically light, and vice versa. However, if you customize the Webchat widget’s home screen, for example, with a colorful background image, ensure that the text and icons in the foreground remain visible. Use the Colors section on the Layout tab in the endpoint settings or the CSS customization options to ensure color contrast. To ensure color contrast for text, follow these guidelines:
  • The minimum contrast ratio for normal text is 4.5:1. Avoid using text smaller than 12px.
  • For larger text, the contrast ratio should be at least 3:1.
To verify the color contrast in your Webchat, use an online contrast checker, such as the WebAIM Contrast Checker. You can determine the contrast ratio of your Webchat using the browser DevTools. For Chrome DevTools, follow these steps to check the color contrast ratio:
  1. Open Chrome DevTools by right-clicking the web page and selecting Inspect, or by pressing Ctrl + Shift + I (Windows/Linux) or Cmd + Option + I (Mac).
  2. In the Elements panel, hover over the HTML elements to highlight sections of the page or click the specific element you want to inspect.
  3. In the Styles panel on the right, find the color property for the text or the background-color property for the background.
  4. Click the color swatch next to the color or background-color value to open the color picker.
  5. Look for the Contrast Ratio section below the color values in the color picker. The contrast ratio is displayed, showing whether the colors meet the WCAG guidelines:
    • Passes: shows a checkmark ✅ if the ratio meets AA or AAA standards for normal or large text.
    • Fails: shows a prohibited symbol 🚫 if the ratio doesn’t meet AA or AAA standards for normal or large text.
  6. Use the color picker to adjust the color values. This tool updates the contrast ratio in real time, helping you find a compliant color combination. Alternatively, click the eyedropper icon, pick a color from anywhere on your screen, and use the WebAIM Contrast Checker to check the color compatibility.
Chrome DevTools color picker showing contrast ratio check results

Revise extensions

If you built a custom node using the extension framework, make sure that the node follows accessibility standards.

More information

Last modified on November 11, 2026