Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Sounds in Flex and Audio Player Manager API

There are many reasons you might want to play a sound in the Flex UI. For example:

  • Ringing to indicate an incoming call task
  • Sound notifications for new chat messages
  • Sound to indicate that participants have joined or left a conference

The Flex AudioPlayerManager API provides a mechanism to implement sounds like these in the Flex UI.

AudioPlayerManager API

The Flex AudioPlayerManager API supports playing, stopping and muting sounds.

Sounds are divided into 2 categories:

  • Repeatable media are played in a loop, like a phone ringing that goes on and on. The only way to stop repeatable media is to manually call the stop method.
  • Non-repeatable media are played once, like a beep or bleep. Non-repeatable media automatically stop after being played once.

The media to be played is defined like so:

export interface MediaData {
    url: string;
    repeatable: boolean;
}

To play media, you must specify the URL where the media file is located, and declare whether or not the sound is repeatable:

const mediaId = Flex.AudioPlayerManager.play(
{
    url: "sound-url",
    repeatable: true
},
(error: AudioPlayerError) => {
    // handle error
}
);

Handling errors

If there is an error while playing the media, a notification will be shown with the error. Some possible errors include:

Error Message Cause
NotAllowed Cannot play sound, because permissions for playback of media were not given or denied. To find out more about how to fix this error, go to Flex Docs The user hasn't interacted with the site and the browser doesn't allow sound to be played
InvalidMedia Cannot play sound. Provided media is invalid.

The provided media is not valid; this could be an incorrect file type, an incorrect URL path, or a corrupted file.

Other Error playing media.

Other exceptions. This could depend on browser implementation details, media player implementation, and so forth.

Stop media playback

To stop media, use the media id returned from the play method (described above):

Flex.AudioPlayerManager.stop(mediaId);

Mute media

To mute or unmute sounds, use the following method:

Flex.AudioPlayerManager.toggleSound(true/false);

Muting or unmuting doesn't stop current playing media. The media will keep playing, but with their volume at zero.

Repeatable and non-repeatable media

Repeatable and non-repeatable media can be played at the same time, but there can only be one repeatable and one non-repeatable media playing at a given time. Overall, this means that you can only have two media playing at once: one repeatable, and one non-repeatable media.

If the media is repeatable, calls to Flex.AudioPlayerManager.play will enqueue the media and play them one after another. You can stop a repeatable media that isn't playing (but is enqueued) to remove it from the queue. Stopping a repeatable media that is playing will stop the sound and play the next media in the queue (if the queue is not empty).

If the media is non-repeatable, it will be played only if no other non-repeatable media is already playing. Non-repeatable media are not enqueued. You can stop a non-repeatable media that is playing to stop the sound.

For example, to play a sound when a chat message is received:

Flex.Manager.getInstance().chatClient.on("messageAdded", () => {
    const mediaId = Flex.AudioPlayerManager.play({
        url: "sound-url",
        repeatable: true
    });
})

Troubleshooting

Browsers, especially Chrome, have strict policies that prevent sound playback or media autoplay for background tabs or tabs that didn't receive any user input (source: https://developers.google.com/web/updates/2017/09/autoplay-policy-changes). Some typical situations include:

  • A tab that was refreshed and never received user input
  • A tab with Flex in a separate window that was reopened automatically and never received user input
  • A tab that was opened a while ago and hasn't received focus for a while
  • A tab among other tabs that playback sounds

For media to be played, the agent must interact with the Flex UI first. Sounds that were triggered but weren't allowed to play, will start playing as soon as the agent interacts with the site.

  • Repeatable media will play the first media that was triggered. Once the first one stops playing, the next in queue will be played.
  • Non-repeatable media will play the first media that was triggered and hasn't been stopped.

Sample scenarios for repeatable medias

Screenshot 2019-08-14 at 19.04.57.png
Screenshot 2019-08-14 at 19.04.40.png

Sample scenario for non-repeatable medias

Screenshot 2019-08-14 at 19.05.33.png

There are some workarounds:

Chrome

  • Change autoplay policy: the agent can update Chrome's autoplay policy flag to one that does not require user interaction with a document to playback sounds. It can be accessed under `chrome://flags/` URI > `Autoplay policy`. Change it to `No user gesture is required`. Caveat: this flag will apply for all websites.
  • Whitelist hostname: add the hostname at `chrome://settings/content/sound` to whitelist it to play sound. Note: this does not require enterprise policies.
  • Change enterprise policies: add the hostname to the autoplay whitelist (http://dev.chromium.org/administrators/policy-list-3#AutoplayWhitelist). Note: this requires enterprise policies.

Source: https://developers.google.com/web/updates/2017/09/autoplay-policy-changes

Firefox

Whitelist hostname: add the hostname at `about:preferences#privacy` URI whitelist it to always play sound.

Source: https://support.mozilla.org/en-US/kb/block-autoplay

Safari

Allow autoplay sound for hostname: in the Safari app, choose Safari > Settings for This Website, under `Auto-Play` select `Allow All Auto-Play`

Source: https://support.apple.com/guide/safari/stop-autoplay-videos-ibrw29c6ecf8/mac

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.