Skip to main content

​
Branded video-room backgrounds

A branded background is a virtual background image your organization registers once — a label plus an https:// image URL — that then appears in the in-call background picker of every video room in your workspace, alongside the built-in presets. Use them to put a consistent, on-brand scene behind every participant: an HQ lobby, a product wall, an event backdrop. Registered backgrounds are workspace-wide. Any participant in any room opens the in-meeting Background panel and sees their own workspace’s library listed next to the built-in images and the blur option. The image lives on your own CDN or brand-asset host; Orbit stores the URL, and each participant’s browser fetches the image directly at pick time — you keep control of your own assets and retention.

​
Where it lives

The library console sits at Voice → Video → Backgrounds. Owners and admins manage it there; over the API the same surface is the /api/v1/video/background-library routes: list (read scope), register, and remove (write scope + owner, admin, or developer role).

​
Register a background

Each entry is a name (the label shown in the picker, up to 80 characters) plus an image URL. The console and the API apply the same checks:
  • HTTPS only. Plain http:// URLs are rejected; a participant’s browser would block the mixed-content fetch and the image would silently never load.
  • Standard web formats. Serve a JPEG, PNG, or WebP. Any image host you control works — a CDN, a public bucket, your own asset store.
  • Sensible dimensions. A 16:9 image (for example 1280×720) replaces the camera scene edge to edge; other aspect ratios still work but letterbox or crop.
  • Reachable by every participant. The URL must be publicly fetchable — nothing behind VPN-only hosts — and an empty or unreachable URL shows as a muted broken tile in the picker rather than a black backdrop.
  • CORS-friendly. Because each participant’s browser fetches the image directly, your host should allow cross-origin reads; hosts that block them mark the tile as unreachable for participants.
The library holds up to 50 backgrounds per workspace. Once you’re at the cap, remove an entry before adding another. Registering the same URL twice is rejected.
The POST returns the registered asset (201), read its id (vbg_…) for removals. GET /api/v1/video/background-library lists every registered entry; DELETE /api/v1/video/background-library/:assetId removes one and returns 404 when the id was never registered.
Removing an entry is shared and instant — it disappears from the picker in every room immediately and there is no undo. The console gates removal behind a confirmation dialog for that reason.

​
Room policy: off, allowed, or required

A room’s media policy decides whether a virtual background is even an option for its participants. The virtual_background knob accepts three values: The policy lives on the room itself (POST /video/rooms-scheduled), or on a saved room template so every meeting created from that template inherits it — the room-default versus per-room behavior:
  • Room default — an operator sets the policy once on the template and every meeting spun up from it behaves the same.
  • Per-meeting override — set the policy on the individual room when it is created instead of inheriting from a template.
  • Participant choice — a participant can never force the picker open when the room says off; an allowed or required room still leaves each person free to switch their own background mid-call among the workspace library, the built-in presets, blur, and (in the dashboard room surface) a one-off upload for their own session.

​
What participants see

Every participant — guests on an invite link included — opens the Background control in the in-meeting toolbar. The panel shows, in order: background off, Blur, the built-in images, the workspace’s branded entries, and (dashboard rooms) a personal upload. Picking one applies it to that participant’s own camera only; the choice never affects anyone else in the room, and it persists on that person’s device for their next session. Guests and panelists get the same picker, so an invited external attendee also respects your brand when your policy requires a background.

​
Worked example: brand-team admin

You want your sales rooms to show the lobby backdrop behind every consultant. Do it once:
  1. Open Voice → Video → Backgrounds in the dashboard.
  2. Name the entry HQ lobby.
  3. Paste the image URL — https://cdn.acme.example/backgrounds/hq-lobby.jpg.
  4. Choose Add. The thumbnail preview confirms the image renders.
  5. Update the Rooms → Templates sales template to required on virtual backgrounds, so every room from that template now sources the library.
Every consultant’s next meeting shows HQ lobby in the same workspace section of the picker panel.

​
Worked example: invited participant

You were sent a meeting link for a branded sales call:
  1. Open the invite link and redeem it — you land in the room.
  2. Open the Background control in the meeting toolbar.
  3. Pick HQ lobby from the workspace section of the panel — the built-in Blur and presets work too.
  4. The camera preview swaps on your own tile; nobody else’s view changes.
An unreachable or non-HTTPS image URL shows a muted broken tile in the picker — register the URL again with a publicly fetchable https:// endpoint if participants see that.

​
Where to go next