About Chat#

A chat consists of an unordered list of possible chat items, wrapped in a section which has the accessible role of log.

Accessibility#

The log role has an implicit aria-live property value of polite, meaning that it comes for free. It also has an implicit aria-relevant property value of additions text. Together this means any additional text, or chat items added to the list will automatically be politely announced by a screen reader

Base#

<section role="log" class="slds-chat">
  <ul class="slds-chat-list">
    <li class="slds-chat-listitem"></li>
  </ul>
</section>

Structuring a chat#

To correctly structure and communicate a chat, you should first follow the basic structure (see above) that forms any chat log and can contain any type of chat item.

Each slds-chat-listitem comes with 4 modifier classes, each one needing to be applied based on the type of chat item you are display in the list item:

The modifiers are used to apply any specific styling to the type of chat item it represents, including spacing, position and layout.

Starting and ending a chat#

When each chat session is started or stopped, it is represented with a bookend. The bookend displays when the chat was stopped or started and by who.

Chat started bookend#

<div class="slds-chat-bookend">
  <span class="slds-icon_container slds-icon-utility-chat slds-chat-icon">
    <svg class="slds-icon slds-icon_x-small slds-icon-text-default" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#chat"></use>

Chat stopped bookend#

<div class="slds-chat-bookend slds-chat-bookend_stop">
  <span class="slds-icon_container slds-icon-utility-end_chat slds-chat-icon">
    <svg class="slds-icon slds-icon_x-small slds-icon-text-default" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#end_chat"></use>

Chat messages#

Chat messages are comprised of the message text, and message meta data including the persons name and time at which the message was sent. Chat messages come in 3 forms:

Inbound messages#

Use of aria-label

Each message meta data wrapper has aria-label added, which we can use to form more human sounding messages as they arrive, "Hi, my CloudWidget only speaks French said Taylor Watson-Rice at 4:59 PM". A screen reader, when aria-label is applied to an element, will only announce the contents of the label, not the text content held in it.

<section role="log" class="slds-chat">
  <ul class="slds-chat-list">
    <li class="slds-chat-listitem slds-chat-listitem_inbound">
      <div class="slds-chat-message">

Consecutive inbound messages#

Consecutive messages only display name and time meta data once

<section role="log" class="slds-chat">
  <ul class="slds-chat-list">
    <li class="slds-chat-listitem slds-chat-listitem_inbound">
      <div class="slds-chat-message">

Inbound with avatar#

Inbound messages can optionally display the customers avatar. When displaying an avatar in inbound messages, be sure to apply the slds-chat-message_faux-avatar modifier to any consecutive slds-chat-message containers, to ensure correct alignment where the avatar is missing.

Aria Hidden Avatars

Because every inbound message already includes the user's name, the user's avatar is redundant and therefore should be treated as decorative. For this reason, we hide the avatar using aria-hidden="true" on the <span>with class="slds-avatar" to avoid redundancy for screen reader users.

<section role="log" class="slds-chat">
  <ul class="slds-chat-list">
    <li class="slds-chat-listitem slds-chat-listitem_inbound">
      <div class="slds-chat-message">

Receiving a file attachment#

During a chat an agent can request the customer upload a file attachment to be sent to the agent.

<section role="log" class="slds-chat">
  <ul class="slds-chat-list">
    <li class="slds-chat-listitem slds-chat-listitem_inbound">
      <div class="slds-chat-message">

It is also possible to display an image preview when sending a supported file format, such as a JPEG. This is accomplished by using the File component within Chat.

Contrast

When using actions without a title, it's important to use the slds-file__title_scrim class in conjunction with slds-file__title to ensure proper contrast. Without this, it can be difficult for users to see the action icons when the image being sent is predominantly light in color.

<section role="log" class="slds-chat">
  <ul class="slds-chat-list">
    <li class="slds-chat-listitem slds-chat-listitem_inbound">
      <div class="slds-chat-message">

Non-image file formats are also supported by using the File component.

<section role="log" class="slds-chat">
  <ul class="slds-chat-list">
    <li class="slds-chat-listitem slds-chat-listitem_inbound">
      <div class="slds-chat-message">

Both file and image transfers support messages with and without titles; however, titles are generally not recommended when transferring images.

<section role="log" class="slds-chat">
  <ul class="slds-chat-list">
    <li class="slds-chat-listitem slds-chat-listitem_inbound">
      <div class="slds-chat-message">

When sending or receiving a portrait-orientation image, use the slds-file__figure_portrait in conjunction with the slds-file__figure class. This will properly display the entire image within the chat message.

<section role="log" class="slds-chat">
  <ul class="slds-chat-list">
    <li class="slds-chat-listitem slds-chat-listitem_outbound">
      <div class="slds-chat-message">

Customer is typing#

Whilst chatting with customers, agents can see when a customer is typing a response by using the Dynamic Icon, Typing.

Assistive text

It's important to set descriptive assistive text to the typing icon, as this is the only means a screen reader user will know a customer is currently typing. The assistive text, because it is text content, will be announced as the icon is added to the DOM. As an example, we use "Customer is typing"

<section role="log" class="slds-chat">
  <ul class="slds-chat-list">
    <li class="slds-chat-listitem slds-chat-listitem_inbound">
      <div class="slds-chat-message">

Sneak peek#

We can take that experience one step further when the sneak peek feature is enabled. This allows agents to see what customers are typing in real time, as they type it.

aria-hidden

When the sneak peek feature is active, we take care to try and reduce the verbosity a screen reader user will encounter. As they will hear the final message once it is typed, we have found it is preferred to use aria-hidden="true" on the text they are currently typing, to reduce noise.

<section role="log" class="slds-chat">
  <ul class="slds-chat-list">
    <li class="slds-chat-listitem slds-chat-listitem_inbound">
      <div class="slds-chat-message">

Outbound messages#

Outbound messages come in 2 forms. Ones that are written by the agent in the current chat session, and ones which have been written by other agents who have dealt with the customer during the same chat session.

Outbound message by current agent#

<section role="log" class="slds-chat">
  <ul class="slds-chat-list">
    <li class="slds-chat-listitem slds-chat-listitem_outbound">
      <div class="slds-chat-message">

Outbound message by another agent#

<section role="log" class="slds-chat">
  <ul class="slds-chat-list">
    <li class="slds-chat-listitem slds-chat-listitem_outbound">
      <div class="slds-chat-message">

Consecutive outbound messages#

For consecutive outbound messages the same rules apply to both types, as consecutive inbound messages.

<section role="log" class="slds-chat">
  <ul class="slds-chat-list">
    <li class="slds-chat-listitem slds-chat-listitem_outbound">
      <div class="slds-chat-message">

Delivery Status Messages#

Unsupported Message Type (Inbound)#

If a customer tries sending a message that is not supported, it will appear as an unsupported message type.

<section role="log" class="slds-chat">
  <ul class="slds-chat-list">
    <li class="slds-chat-listitem slds-chat-listitem_inbound">
      <div class="slds-chat-message">

Message Delivery Failure (Outbound)#

If the agent attempts to send a message that can't be delivered, a message delivery failure indication appears beneath the original message text, along with an option to resend.

Role alert

Message delivery failures have the addition role="alert" to their container. A chat log has an aria-live="polite" value, but we would like to inform agents of errors immediately. The role="alert" attribute comes with an implicit aria-live value of assertive which will achieve this.

<section role="log" class="slds-chat">
  <ul class="slds-chat-list">
    <li class="slds-chat-listitem slds-chat-listitem_outbound">
      <div class="slds-chat-message">

Displaying events during a chat session#

During a chat session a number of events can occur and these are displayed to the agent, with descriptions and sometimes messages.

Basic chat event#

The basic type of events that can occur include:

• Rasing a flag
• Lowering a flag
• A whisper
• File request
• File sent
• File request cancelled
• Transfer request
• Transfer accepted
• Transfer cancelled
• Transfer declined

<section role="log" class="slds-chat">
  <ul class="slds-chat-list">
    <li class="slds-chat-listitem slds-chat-listitem_event">
      <div class="slds-chat-event">

Chat event with an agent message#

Sometimes an agent might add a message to an event for another agent to read.

<section role="log" class="slds-chat">
  <ul class="slds-chat-list">
    <li class="slds-chat-listitem slds-chat-listitem_event">
      <div class="slds-chat-event">

Chat event - error#

In the event of an error occurring during the chat, an error event can be displayed to the agent. This is done by adding the .slds-has-error modifier class.

Role alert

Event errors have the addition role="alert" to their container. A chat log has a aria-live="polite" value, but we would like to inform agents of errors immediately. The role="alert" attribute comes with an implicit aria-live value of assertive which will achieve this.

<section role="log" class="slds-chat">
  <ul class="slds-chat-list">
    <li class="slds-chat-listitem slds-chat-listitem_event">
      <div class="slds-chat-event slds-has-error" role="alert">

Putting it all together#

<section role="log" class="slds-chat">
  <ul class="slds-chat-list">
    <li class="slds-chat-listitem slds-chat-listitem_bookend">
      <div class="slds-chat-bookend">

Past Chats#

An agent has the ability to view past chats with particular customers. In this instance the exact same components and markup for all types of chat items can be used, with just 4 differences:

• A single modifier class of .slds-chat_past is added to the .slds-chat container
• Each chat message .slds-chat-listitem container looses it's .slds-chat-listitem_inbound or .slds-chat-listitem_outbound modifier class
• Each chat message .slds-chat-message__text looses it's .slds-chat-message__text_inbound or .slds-chat-message__text_outbound modifier class
• .slds-chat-message__meta moves to before .slds-chat-message__text in DOM order

<section role="log" class="slds-chat slds-chat_past">
  <ul class="slds-chat-list">
    <li class="slds-chat-listitem slds-chat-listitem_bookend">
      <div class="slds-chat-bookend">