Skip to main content

How to customize the Copilot widget

Admins with the appropriate permission can customize the look and welcome screen of the Copilot chat widget directly from the chat.

1. Grant the Widget Configuration permission​

Customization is gated by an ACL resource. Grant it to any role that should be allowed to change the widget's appearance.

  1. Go to System → Permissions → User Roles and open the role.
  2. On the Role Resources tab, expand Stores → Settings → Configuration → AI Copilot.
  3. Enable Widget Configuration.
  4. Click Save Role.

Admins in this role will now see a gear icon in the Copilot header.

2. Open the configuration panel​

  1. Open Copilot from any admin page.
  2. Make sure you're on the welcome screen — the gear icon only appears before a conversation starts. If a conversation is active, click the New conversation button first.
  3. Click the gear icon. The configuration panel opens to the left of the chat.

The chat area on the right becomes a live preview: changes you make on the left appear immediately on the right.

3. Edit the widget​

The panel has three tabs.

Welcome​

  • Change the Assistant name shown as the welcome-screen heading.
  • Edit the Welcome message shown below the assistant name.
  • Edit the Default questions list (up to 6). Questions appear as clickable cards that start a conversation when clicked. Leave a row empty to omit it.
  • Toggle Show recent conversations to display the last 2–6 conversations as clickable items.
  • Toggle Show prompts on welcome screen and pick which prompts to feature. Use the search box to filter by title or code. A needs input tag marks prompts that will route the admin to the chat input to fill arguments.

Window​

  • Set a custom Title for the chat header.
  • Pick a Primary color (used on the send button, input glow) and a Secondary color (welcome message gradient).

Launcher​

  • Choose Position — Bottom right (default) or Bottom left.
  • Fine-tune placement with Horizontal padding and Vertical padding (pixels from the viewport edge).
  • Pick Primary color (launcher fill) and Secondary color (pulse rings).
  • Pick an Icon — Magic, Chat, Sparkle, Question, or Robot.
  • Add optional Label text — turns the round launcher into a pill with the label next to the icon.

4. Save, reset, or restore​

At the bottom of the panel:

  • Save — persists your changes to the Copilot server.
  • Reset — discards unsaved changes and returns the panel to the last saved state.
  • Restore defaults — wipes the saved configuration back to factory defaults. Asks for confirmation.

Closing the panel with unsaved changes also asks for confirmation.

note

Widget configuration is shared across all admins on the same Magento instance. If you change the Title or colors, every admin using Copilot on this store will see the new look.

Resetting on a new Magento instance​

Widget configuration is stored on the Copilot server, not in Magento's database. If you move Copilot to a new Magento instance and apply the same Recovery Token in AI Copilot settings, the widget configuration is preserved automatically.

If you want to start over on the new instance, open the configuration panel and use Restore defaults.