Customizing the Appearance of Twilio Flex with React Plugins

Twilio Flex React Contact Center UI — Complete Customization Guide --- ## Overview Twilio Flex is a programmable contact center platform whose entire UI is built in React. Customizations are delivered as Plugins — isolated JavaScript bundles that hook into Flex's component and action system at runtime. This guide covers: 1. Local development environment setup 2. Color scheme customization 3. Header branding 4. Copy and text string changes 5. Custom ringtones 6. Lifecycle from local dev to production --- ## 1. Environment Setup ### Prerequisites ```bash node --version # 18.x recommended npm --version # 9.x+ ``` ### Install Flex Plugin CLI ```bash npm install -g @twilio-labs/plugin-flex twilio plugins:install @twilio-labs/plugin-flex ``` ### Scaffold a new plugin ```bash twilio flex:plugins:create my-brand-plugin \ --install \ --flexui2 # target Flex UI 2.x (React 18) cd my-brand-plugin ``` ### Project structure ``` my-brand-plugin/ ├── public/ │ └── appConfig.js # local account SID / auth ├── src/ │ ├── MyBrandPlugin.js # plugin entry point │ ├── components/ # custom React components │ ├── theme/ # design tokens │ └── assets/ # audio files, images ├── package.json └── plugin.config.js ``` ### Configure local credentials ```js // public/appConfig.js var appConfig = { accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", flexConfigServiceUrl: "https://flex-api.twilio.com/v1/Configuration", }; ``` ### Start dev server ```bash twilio flex:plugins:start # Opens https://localhost:3000 with your plugin hot-reloaded ``` --- ## 2. Color Scheme Customization Flex UI 2.x uses **Paste Design System** with CSS custom properties exposed through the theme object. ### 2-1. Define design tokens ```js // src/theme/brandTheme.js export const brandTheme = { // Paste token overrides colorBackgroundPrimary: "#1A1A2E", colorBackgroundBody: "#16213E", colorBackgroundStrong: "#0F3460", colorTextLink: "#E94560", colorTextLinkStrong: "#FF6B6B", colorText: "#EAEAEA", colorTextWeak: "#A0A0B0", colorBorderPrimary: "#E94560", // Sidebar / navigation colorSidebar: "#0F3460", colorSidebarActive: "#E94560", // Agent state pill colors colorAgentAvailable: "#06D6A0", colorAgentBusy: "#FFB703", colorAgentOffline: "#6C757D", // Button brand colors colorButtonPrimary: "#E94560", colorButtonPrimaryHover: "#C73652", }; ``` ### 2-2. Apply the theme in the plugin entry point ```js // src/MyBrandPlugin.js import React from "react"; import { FlexPlugin } from "@twilio/flex-plugin"; import { brandTheme } from "./theme/brandTheme"; const PLUGIN_NAME = "MyBrandPlugin"; export default class MyBrandPlugin extends FlexPlugin { constructor() { super(PLUGIN_NAME); } async init(flex, manager) { // ── Theme ────────────────────────────────────────────── manager.updateConfig({ colorTheme: { overrides: brandTheme, isLight: false, // false = dark base palette }, }); // Additional customizations registered below... this.customizeHeader(flex); this.customizeStrings(manager); this.customizeRingtone(manager); } } ``` ### 2-3. Component-level style override (Paste / Emotion) ```js // src/components/AgentDesktopView/AgentDesktopView.styles.js import { css } from "@emotion/react"; export const wrapperStyles = css` background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%); border-left: 3px solid #e94560; `; ``` ```jsx // src/components/AgentDesktopView/AgentDesktopView.jsx import React from "react"; import { wrapperStyles } from "./AgentDesktopView.styles"; export const AgentDesktopView = ({ children }) => ( <div css={wrapperStyles}>{children}</div> ); ``` --- ## 3. Header Branding ### 3-1. Replace the default Flex logo ```jsx // src/components/BrandHeader/BrandHeader.jsx import React from "react"; import styled from "@emotion/styled"; import companyLogo from "../../assets/logo.svg"; const HeaderBar = styled.div` display: flex; align-items: center; height: 56px; padding: 0 24px; background-color: #0f3460; border-bottom: 2px solid #e94560; box-shadow: 0 2px 8px rgba(233, 69, 96, 0.3); `; const Logo = styled.img` height: 32px; width: auto; `; const ProductName = styled.span` margin-left: 12px; font-size: 18px; font-weight: 700; color: #eaeaea; letter-spacing: 0.5px; `; const Badge = styled.span` margin-left: 8px; padding: 2px 8px; font-size: 10px; font-weight: 600; background: #e94560; color: white; border-radius: 10px; text-transform: uppercase; `; export const BrandHeader = () => ( <HeaderBar> <Logo src={companyLogo} alt="Company Logo" /> <ProductName>Support Center</ProductName> <Badge>Live</Badge> </HeaderBar> ); ``` ### 3-2. Register the header component in the plugin ```js // inside init(flex, manager) in MyBrandPlugin.js customizeHeader(flex) { // Remove the default Flex header flex.MainHeader.defaultProps.logoUrl = ""; // Replace the entire header with the brand component flex.MainHeader.Content.remove("logo"); flex.MainHeader.Content.remove("title"); flex.MainHeader.Content.add( <BrandHeader key="brand-header" />, { sortOrder: 0, align: "start", } ); // Add agent name display on the right side of the header flex.MainHeader.Content.add( <AgentStatusBadge key="agent-status" />, { sortOrder: 10, align: "end", } ); } ``` ### 3-3. Agent status badge component ```jsx // src/components/AgentStatusBadge/AgentStatusBadge.jsx import React from "react"; import { useFlexSelector } from "@twilio/flex-ui"; import styled from "@emotion/styled"; const Wrapper = styled.div` display: flex; align-items: center; gap: 8px; margin-right: 16px; `; const Dot = styled.span` width: 10px; height: 10px; border-radius: 50%; background-color: ${({ activity }) => activity === "Available" ? "#06D6A0" : activity === "Busy" ? "#FFB703" : "#6C757D"}; `; const AgentName = styled.span` font-size: 13px; color: #eaeaea; font-weight: 500; `; export const AgentStatusBadge = () => { const workerName = useFlexSelector( (state) => state.flex.worker.attributes?.full_name ?? "Agent" ); const activity = useFlexSelector( (state) => state.flex.worker.activity?.name ?? "Offline" ); return ( <Wrapper> <Dot activity={activity} /> <AgentName>{workerName}</AgentName> </Wrapper> ); }; ``` --- ## 4. Copy and Text String Customization ### 4-1. Define string overrides ```js // src/strings/brandStrings.js export const brandStrings = { // Task list panel TaskHeaderLine1: "{{task.attributes.name}}", TaskHeaderLine2: "{{task.attributes.from}}", // No tasks placeholder NoTasks: "No active contacts — you're all caught up ✓", NoTasksTitle: "Ready for the next customer", // Incoming call IncomingCallTitle: "Incoming Call", IncomingCallAccept: "Answer", IncomingCallReject: "Decline", // Task actions TaskCanvasHeader: "Contact Details", CallCanvasWorkerName: "{{worker.attributes.full_name}}", // Wrapup / disposition WrapupTimerLabel: "Wrap-up time remaining:", CompleteTaskButton: "Complete Contact", // Agent desktop AgentDesktopCollapse: "Collapse Panel", AgentDesktopExpand: "Expand Panel", // Sidebar navigation WorkerCanvasTitle: "My Profile", QueuesStatsTitle: "Queue Dashboard", // Notifications SupervisorBarge: "{{worker.attributes.full_name}} has joined your call", // Error messages ErrorTaskNotFound: "Contact could not be loaded. Please refresh.", }; ``` ### 4-2. Apply strings in the plugin ```js // inside init(flex, manager) in MyBrandPlugin.js customizeStrings(manager) { manager.strings = { ...manager.strings, // keep all default strings ...brandStrings, // override with brand copy }; } ``` ### 4-3. Dynamic strings with template variables ```js // Custom strings support Handlebars-style {{ }} interpolation // Available contexts: task, worker, queue, call export const dynamicStrings = { // Displays resolved customer name from task attributes IncomingCallTitle: "Call from {{task.attributes.name}}", // Queue-aware greeting TaskHeaderLine2: "Queue: {{task.queueName}} · Priority: {{task.priority}}", // Duration display CallDuration: "Connected for {{call.formattedDuration}}", }; ``` ### 4-4. Locale-aware strings (i18n pattern) ```js // src/strings/index.js import { brandStrings as en } from "./brandStrings.en"; import { brandStrings as ja } from "./brandStrings.ja"; import { brandStrings as es } from "./brandStrings.es"; const localeMap = { en, ja, es }; export function getStrings(locale = "en") { return localeMap[locale] ?? localeMap.en; } ``` ```js // Usage in plugin init customizeStrings(manager) { const locale = manager.workerClient?.attributes?.locale ?? navigator.language.slice(0, 2); manager.strings = { ...manager.strings, ...getStrings(locale), }; } ``` --- ## 5. Custom Ringtone ### 5-1. Add audio assets ``` src/assets/sounds/ ├── incoming-call.mp3 # primary ringtone ├── incoming-call.ogg # fallback (Firefox) ├── task-assigned.mp3 # new chat / task alert └── call-ended.mp3 # disconnect chime ``` ### 5-2. Audio manager utility ```js // src/utils/AudioManager.js class AudioManager { constructor() { this.sounds = {}; this.currentLoop = null; } register(name, mp3Src, oggSrc = null) { const audio = new Audio(); // Use OGG if supported, else MP3 if (oggSrc && audio.canPlayType("audio/ogg") !== "") { audio.src = oggSrc; } else { audio.src = mp3Src; } audio.preload = "auto"; this.sounds[name] = audio; return this; } play(name, { loop = false, volume = 0.7 } = {}) { const sound = this.sounds[name]; if (!sound) { console.warn(`[AudioManager] Sound "${name}" not registered`); return; } sound.loop = loop; sound.volume = volume; sound.currentTime = 0; sound.play().catch((err) => { // Autoplay policy: will play after first user interaction console.warn("[AudioManager] Autoplay blocked:", err.message); }); if (loop) this.currentLoop = sound; } stop(name) { const sound = this.sounds[name]; if (!sound) return; sound.pause(); sound.currentTime = 0; if (this.currentLoop === sound) this.currentLoop = null; } stopAll() { Object.values(this.sounds).forEach((s) => { s.pause(); s.currentTime = 0; }); this.currentLoop = null; } } export const audioManager = new AudioManager(); ``` ### 5-3. Register sounds and hook into Flex actions ```js // src/MyBrandPlugin.js import incomingCallMp3 from "./assets/sounds/incoming-call.mp3"; import incomingCallOgg from "./assets/sounds/incoming-call.ogg"; import taskAssignedMp3 from "./assets/sounds/task-assigned.mp3"; import callEndedMp3 from "./assets/sounds/call-ended.mp3"; import { audioManager } from "./utils/AudioManager"; // Inside init(flex, manager): customizeRingtone(manager) { // 1. Register all sounds audioManager .register("incomingCall", incomingCallMp3, incomingCallOgg) .register("taskAssigned", taskAssignedMp3) .register("callEnded", callEndedMp3); // 2. Hook: incoming voice call reserved manager.workerClient.on("reservationCreated", (reservation) => { if (reservation.task.taskChannelUniqueName === "voice") { audioManager.play("incomingCall", { loop: true, volume: 0.8 }); } else { // Chat, SMS, etc. audioManager.play("taskAssigned", { loop: false, volume: 0.6 }); } }); // 3. Hook: call accepted — stop ringing manager.workerClient.on("reservationAccepted", () => { audioManager.stop("incomingCall"); }); // 4. Hook: reservation rejected / timed out manager.workerClient.on("reservationRejected", () => { audioManager.stop("incomingCall"); }); manager.workerClient.on("reservationTimedOut", () => { audioManager.stop("incomingCall"); }); // 5. Hook: call completed manager.workerClient.on("reservationCompleted", () => { audioManager.stop("incomingCall"); audioManager.play("callEnded", { volume: 0.5 }); }); } ``` ### 5-4. Volume control UI component ```jsx // src/components/VolumeControl/VolumeControl.jsx import React, { useState } from "react"; import styled from "@emotion/styled"; import { audioManager } from "../../utils/AudioManager"; const Wrapper = styled.div` display: flex; align-items: center; gap: 8px; padding: 4px 12px; `; const Label = styled.span` font-size: 11px; color: #a0a0b0; text-transform: uppercase; letter-spacing: 0.5px; `; const Slider = styled.input` accent-color: #e94560; width: 80px; cursor: pointer; `; export const VolumeControl = () => { const [volume, setVolume] = useState(70); const handleChange = (e) => { const val = Number(e.target.value); setVolume(val); // Update all registered sounds Object.values(audioManager.sounds).forEach((sound) => { sound.volume = val / 100; }); }; return ( <Wrapper> <Label>🔔</Label> <Slider type="range" min="0" max="100" value={volume} onChange={handleChange} title={`Ringtone volume: ${volume}%`} /> <Label>{volume}%</Label> </Wrapper> ); }; ``` --- ## 6. Complete Plugin Entry Point ```js // src/MyBrandPlugin.js import React from "react"; import { FlexPlugin } from "@twilio/flex-plugin"; import { BrandHeader } from "./components/BrandHeader/BrandHeader"; import { AgentStatusBadge } from "./components/AgentStatusBadge/AgentStatusBadge"; import { VolumeControl } from "./components/VolumeControl/VolumeControl"; import { brandTheme } from "./theme/brandTheme"; import { getStrings } from "./strings"; import { audioManager } from "./utils/AudioManager"; import incomingCallMp3 from "./assets/sounds/incoming-call.mp3"; import incomingCallOgg from "./assets/sounds/incoming-call.ogg"; import taskAssignedMp3 from "./assets/sounds/task-assigned.mp3"; import callEndedMp3 from "./assets/sounds/call-ended.mp3"; export default class MyBrandPlugin extends FlexPlugin { constructor() { super("MyBrandPlugin"); } async init(flex, manager) { this.applyTheme(manager); this.customizeHeader(flex, manager); this.customizeStrings(manager); this.customizeRingtone(manager); } // ── 1. Theme ───────────────────────────────────────────── applyTheme(manager) { manager.updateConfig({ colorTheme: { overrides: brandTheme, isLight: false, }, }); } // ── 2. Header ──────────────────────────────────────────── customizeHeader(flex, manager) { flex.MainHeader.Content.remove("logo"); flex.MainHeader.Content.remove("title"); flex.MainHeader.Content.add(<BrandHeader key="brand-header" />, { sortOrder: 0, align: "start", }); flex.MainHeader.Content.add( <VolumeControl key="volume-control" />, { sortOrder: 5, align: "end" } ); flex.MainHeader.Content.add( <AgentStatusBadge key="agent-status" />, { sortOrder: 10, align: "end" } ); } // ── 3. Strings ─────────────────────────────────────────── customizeStrings(manager) { const locale = manager.workerClient?.attributes?.locale ?? navigator.language.slice(0, 2); manager.strings = { ...manager.strings, ...getStrings(locale), }; } // ── 4. Ringtone ────────────────────────────────────────── customizeRingtone(manager) { audioManager .register("incomingCall", incomingCallMp3, incomingCallOgg) .register("taskAssigned", taskAssignedMp3) .register("callEnded", callEndedMp3); manager.workerClient.on("reservationCreated", (reservation) => { const channel = reservation.task.taskChannelUniqueName; if (channel === "voice") { audioManager.play("incomingCall", { loop: true, volume: 0.8 }); } else { audioManager.play("taskAssigned", { volume: 0.6 }); } }); ["reservationAccepted", "reservationRejected", "reservationTimedOut"] .forEach((event) => { manager.workerClient.on(event, () => audioManager.stop("incomingCall") ); }); manager.workerClient.on("reservationCompleted", () => { audioManager.stop("incomingCall"); audioManager.play("callEnded", { volume: 0.5 }); }); } } ``` --- ## 7. Deployment Lifecycle ### Conceptual pipeline overview ``` Local Dev → QA / Staging → UAT → Production │ │ │ │ localhost Flex SID Real All hot-reload Test env agents agents ``` --- ### Stage 1 — Local Development ```bash # Hot-reload dev server twilio flex:plugins:start # What happens internally: # - Webpack dev server on https://localhost:3000 # - Plugin loaded via appConfig.js (local override) # - Twilio Flex UI fetched from CDN # - Your plugin injected at runtime # - Changes reflect within ~2 seconds (HMR) ``` --- ### Stage 2 — Build and Validate ```bash # Production build twilio flex:plugins:build # Output: # build/ # └── plugin-my-brand-plugin.js (minified bundle) # Validate bundle before upload twilio flex:plugins:validate ``` --- ### Stage 3 — Deploy to Twilio Assets ```bash # Upload bundle to Twilio's serverless asset infrastructure twilio flex:plugins:deploy \ --changelog "Brand refresh: new colors, logo, ringtone" \ --description "v1.2.0 - MyBrand theme" # This command: # 1. Uploads plugin-my-brand-plugin.js to Twilio Assets # 2. Creates a new Plugin Version in Flex Plugins API # 3. Does NOT activate it yet — safe to deploy without impact ``` --- ### Stage 4 — Release Management ```bash # Create a release (bundle of plugin versions) twilio flex:plugins:release \ --plugin my-brand-plugin@1.2.0 \ --name "v1.2.0 Brand Refresh" \ --description "Tested on QA, approved by product team" # A Release is immutable — it pins exact plugin versions # You can have multiple releases and switch between them ``` --- ### Stage 5 — Activation ```bash # Activate the release → all agents see it on next page load twilio flex:plugins:release:activate <release-sid> # For gradual rollout (percentage-based), use Flex Configuration API: curl -X POST https://flex-api.twilio.com/v1/PluginService/Releases \ -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \ -d "Plugins=my-brand-plugin@1.2.0" \ -d "Percentage=10" # Start with 10% of agents ``` --- ### Stage 6 — Rollback ```bash # Instantly roll back by activating the previous release twilio flex:plugins:release:activate <previous-release-sid> # Rollback is immediate — no redeploy required # Agents see the previous version on next page load ``` --- ### Full lifecycle diagram ``` ┌─────────────────────────────────────────────────────────────────┐ │ DEVELOPMENT │ │ git branch → code → localhost:3000 → review → commit │ └────────────────────────┬────────────────────────────────────────┘ │ twilio flex:plugins:build ▼ ┌─────────────────────────────────────────────────────────────────┐ │ DEPLOY (upload only) │ │ twilio flex:plugins:deploy │ │ → Twilio Assets (plugin-my-brand-plugin.js) │ │ → Plugin Version created (inactive) │ └────────────────────────┬────────────────────────────────────────┘ │ QA sign-off ▼ ┌─────────────────────────────────────────────────────────────────┐ │ RELEASE │ │ twilio flex:plugins:release │ │ → Immutable snapshot of plugin versions │ │ → Associated with a Release SID │ └────────────────────────┬────────────────────────────────────────┘ │ UAT approval ▼ ┌─────────────────────────────────────────────────────────────────┐ │ ACTIVATION │ │ twilio flex:plugins:release:activate <sid> │ │ → All agents receive update on next load │ │ → Previous release preserved for instant rollback │ └─────────────────────────────────────────────────────────────────┘ ``` --- ### CI/CD integration (GitHub Actions example) ```yaml # .github/workflows/flex-plugin-deploy.yml name: Deploy Flex Plugin on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Node uses: actions/setup-node@v4 with: node-version: "18" cache: "npm" - name: Install dependencies run: npm ci - name: Install Twilio CLI run: | npm install -g twilio-cli twilio plugins:install @twilio-labs/plugin-flex - name: Build plugin run: twilio flex:plugins:build - name: Deploy plugin env: TWILIO_ACCOUNT_SID: ${{ secrets.TWILIO_ACCOUNT_SID }} TWILIO_AUTH_TOKEN: ${{ secrets.TWILIO_AUTH_TOKEN }} run: | twilio flex:plugins:deploy \ --changelog "Deployed from commit ${{ github.sha }}" - name: Create release env: TWILIO_ACCOUNT_SID: ${{ secrets.TWILIO_ACCOUNT_SID }} TWILIO_AUTH_TOKEN: ${{ secrets.TWILIO_AUTH_TOKEN }} run: | twilio flex:plugins:release \ --plugin my-brand-plugin@latest \ --name "Release ${{ github.sha }}" \ --description "Auto-deployed from main branch" # Manual approval gate recommended before activation # Add a GitHub Environment with required reviewers for production ``` --- ## Summary | Area | API / Approach | Key Method | |---|---|---| | Color scheme | Paste design tokens | `manager.updateConfig({ colorTheme })` | | Header branding | Component injection | `flex.MainHeader.Content.add/remove` | | Text strings | String map override | `manager.strings = { ...overrides }` | | Ringtone | Web Audio API + worker events | `workerClient.on("reservationCreated")` | | Deploy | Flex Plugins CLI | `flex:plugins:deploy` | | Release | Immutable version bundle | `flex:plugins:release` | | Activate | Switch active release | `flex:plugins:release:activate` | | Rollback | Activate previous release | Same command, previous SID | The key architectural insight is that **deploy and activate are separate steps** — you can upload and even release a plugin version without any agents seeing it, enabling safe staging and instant rollback at any time.