Per-Queue Virtual Backgrounds — Administrator Guide

SmartVideo for Genesys Cloud can apply a different virtual background to the agent's video depending on which Genesys Cloud queue the interaction arrived on. You upload one background per queue and label it with that queue's ID. When an agent answers an interaction from that queue, SmartVideo applies the matching background automatically.

This builds on the existing Enforce Virtual Background setting. When enforcement is on, agents cannot select or disable the background before or during a call, so the queue-specific background is guaranteed.

The selection works for any Genesys Cloud interaction that carries a queue: web messaging (Messenger), callbacks and scheduled callbacks, voice, and chat. No extra configuration is needed on the queue itself.

Two related improvements ship together with this capability:

• You can now choose which uploaded background is the default enforced one. Previously the first uploaded background was always used.
• Custom integrations can request a specific background through a URL parameter (see Advanced).

Prerequisites

• SmartVideo is deployed with the Genesys Cloud integration (the queue ID is read from the Genesys conversation).
• You have administrator access to SmartVideo Settings.
• You have administrator access to Genesys Cloud to look up queue IDs.
• Background images are ready to upload, one per queue. Use the same format and resolution you use for your existing virtual backgrounds.

Step 1 — Collect the Genesys Cloud queue IDs

For every queue that should get its own background, you need the queue's ID (a UUID such as 3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90).

1. In Genesys Cloud, open Admin → Contact Center → Queues.
2. Open the queue. The queue ID is the UUID at the end of the browser address bar.
3. Copy the ID exactly as shown and keep it with the queue name. You will use it as the background label in Step 3.

Repeat for each queue. Queues that have no matching background use the default enforced background (Step 2).

There are no requirements on the queue itself: routing method, membership and wrap-up settings are not affected.

Step 2 — Enable and enforce virtual backgrounds

1. In SmartVideo, open Settings → SmartVideo Settings → Virtual Backgrounds.
2. Turn on Virtual Background (the feature toggle).
3. Upload at least one background if the list is empty. This is the organization-wide default.
4. Turn on Enforce Virtual Background. The toggle is only available once the feature is on and at least one background is uploaded.
5. An Enforced Background column with a radio button now appears in the backgrounds table. Select the background that should apply when no queue-specific match is found. If you select none, the first uploaded background is used.
6. Click Save.

With enforcement on, agents cannot choose or disable the background before or during a call.

Step 3 — Upload one background per queue and label it with the queue ID

1. In the same Virtual Backgrounds table, click Upload and choose the image for the first queue.
2. Edit the new row's Label and paste the queue ID from Step 1, exactly as copied. The label must be the queue ID only: no queue name, prefix or extra spaces.
3. Repeat for each queue.
4. Click Save.

Rules for labels:

• Matching is an exact, case-sensitive comparison between the queue ID and the label. Genesys queue IDs are lowercase.
• One label holds one queue ID. If several queues should share the same image, upload the image once per queue, each with its own queue ID as the label.
• Keep the Enforced Background radio button on your general default, not on a queue-specific background.

Step 4 — Verify with a test interaction

1. Ask agents who are already logged in to reload the SmartVideo page. Settings are loaded when the page initializes, so changes made in Settings are not picked up by an open session.
2. Start an interaction that routes through one of the configured queues. For example, schedule a callback on that queue or start a Messenger conversation that routes there.
3. Answer the interaction as an agent who is a member of that queue and start the video.
4. Confirm the agent's video shows the background labelled with that queue's ID.
5. Repeat with an interaction on a queue that has no matching background and confirm the default enforced background is applied.

If the wrong background appears, see Behaviour notes and troubleshooting below.

How SmartVideo picks the background

When Enforce Virtual Background is on, the agent's background is resolved once, when the video session starts, in this order. The first candidate whose label matches an uploaded background wins.

1. The selectedVB URL parameter on the SmartVideo page, if a custom integration supplied one (see Advanced).
2. The queue ID of the Genesys Cloud interaction the agent is handling.
3. The virtualBackgroundName value in the interaction's custom data, if the interaction was created through the VideoEngager REST API.
4. The background selected as Enforced Background in Settings.
5. The first uploaded background, if nothing above matched.

When enforcement is off, none of this applies: agents choose their own background from the uploaded list, as before.

Advanced — custom integrations and API-created interactions

Request a background from a custom integration

If you embed the SmartVideo agent page in your own application, add selectedVB=<label> to the SmartVideo page URL. The value is a comma-separated list of background labels, tried in order; the first one that exists is applied. This takes priority over the queue ID. The parameter is carried through SmartVideo's encoded links and into the agent video session.

Interactions created through the REST API

When your system creates the interaction with the VideoEngager API, you can set customData.virtualBackgroundName to a background label. It is used only if no selectedVB parameter and no queue match apply.

Settings API

The virtual background settings endpoint accepts two additional query parameters:

• enforceBlur (boolean): applies the enforced background to all agents.
• enforcedVBId: the ID of the uploaded background to enforce. An empty value clears the selection.

The settings response now returns enforcedVBId alongside enabled, enforceBlur and virtualBackgrounds. See the SmartVideo Settings API reference for the full endpoint definition.

Behaviour notes and troubleshooting

Other points to know

• There is no separate feature flag. Queue matching is active whenever enforcement is on and a label matches.
• The background is resolved when the video session starts. A transfer to another queue during the call does not change it.
• The queue background applies to the agent's video only. Visitors are not affected.