Skip to main content

Widget Appearance & Channels

The SendSeven website widget — both the live-chat / support widget and the newsletter widget — is configured through a set of fields stored in the widget's config. You edit them in the widget editor (Settings → Widgets); if you manage widgets through the API, they are the keys inside the widget config object.

This guide is a reference for the appearance and layout options, the visitor-facing size control, the agent-type transparency indicator, the reactions toggle, how RCS appears as a widget channel, and the trust rules for data your page passes through SendSevenConfig.

For the widget's messaging capabilities (media support, buttons, handoff) see the Live Chat guide. For attaching a bot see Deploy a Bot to a Widget.

Every option is backwards-compatible

All of the fields below are optional and default to the widget's previous behavior. Existing embeds are unaffected — you do not need to change your embed snippet or re-save a widget to keep it working exactly as it does today. Adopt these options only when you want the new behavior.

Appearance & layout options​

FieldTypeAllowed valuesDefaultEffect
bubbleLayoutstringclassic, panelclassicContainer style. classic is the floating rounded panel anchored in the page corner (today's behavior). panel docks the widget as a sticky, full-height side panel.
cardLayoutstringlegacy, inline, hero, gridlegacyHow card content is rendered inside the widget. legacy is today's rendering; inline, hero, and grid are alternative card presentations.
cornerRadiusnumber0–40 (px)12Border radius of the widget panel, in pixels. 0 gives square corners; higher values round them more.
defaultSizestringcompact, tall, fulltallThe size the widget opens at on desktop. See Size presets below.
showAgentTypebooleantrue, falsetrueShow the agent-type indicator in the widget header. See Agent-type indicator.
allowReactionsbooleantrue, falsetrueWhether visitors can react to messages. See Message reactions & replies.
launcher_iconstringdefault, whatsapp, telegram, messenger, instagram, sms, email, message_circle, chat_dots, sparkles, help, headset, phone, life_buoy, hand_wavenullIcon on the closed bubble (launcher) button. null or omitted shows the default icon. Note the snake_case key.

Support widget layout​

These keys shape the support widget's home screen, channel list and launcher. All are optional. A missing key or null keeps the previous look (shown as "When unset"). An empty string counts as null; any other value outside the list returns 422.

FieldTypeAllowed valuesWhen unsetEffect
homeLayoutstringmenu, composermenumenu opens on the channel list. composer opens on a message box first.
channelButtonStylestringoutline, filled, minimal, brandoutlineStyle of the channel buttons.
channelDisplayModestringfull, icons-only, tilesfullHow the channel list is laid out.
launcherModestringpanel, speed_dialpanelpanel opens the widget. speed_dial fans the channel buttons out from the bubble.
prechatModestringform, composerformWhere the pre-chat details are asked: a separate form step, or fields inside the message box.
desktopHandoffbooleantrue, falsefalseOn desktop, a click on a messenger channel shows a QR code and a web link instead of trying to open the app. See Desktop hand-off.
aiThinkingDisplaystringtyping, statusstatusHow the widget shows that an AI agent or bot is working on a reply. typing shows plain typing dots only. status shows a bubble with changing status text and the sources being checked.

Defaults for new support widgets. When you create a support widget and leave a key out, SendSeven fills it in: desktopHandoff is true and aiThinkingDisplay is typing; with live chat on, homeLayout and prechatMode are composer; with live chat off, channelButtonStyle is brand. A value you send, even null or false, always wins. Updates never add defaults, and newsletter widgets get none.

Desktop hand-off​

With desktopHandoff on, every messenger channel in the widget's public settings carries a handoff object:

{
  "channel_type": "whatsapp",
  "identifier": "4915123456789",
  "handoff": {
    "link": "https://wa.me/4915123456789?text=Hi%2C%20I%20need%20help%21",
    "web_link": "https://web.whatsapp.com/send?phone=4915123456789&text=Hi%2C%20I%20need%20help%21",
    "qr": "data:image/png;base64,iVBORw0KGgo..."
  }
}
FieldDescription
linkThe link a phone opens. The QR code contains this link.
web_linkThe messenger's separate web app, only for WhatsApp (WhatsApp Web). null for the other channels.
qrQR code for link as a PNG data URI.

Each channel gets its own handoff, also several channels of the same type. Email, live chat and SMS sender names made of letters (they can't receive replies) never get one.

Online team​

The live-chat status the widget checks lists up to five team members who are online and available for live chat, those with a profile picture first:

{
  "available": true,
  "online_agents": 3,
  "estimated_wait_time": 30,
  "within_schedule": true,
  "next_open_at": null,
  "agents": [
    { "name": "Anna", "avatar_url": "https://.../anna.png" },
    { "name": "Jonas", "avatar_url": null }
  ]
}

Only the first name (or live chat nickname) and the profile picture are shared, never email addresses, IDs or last names. agents is empty while live chat is unavailable. Members who are set to away or turned live chat off in their profile are not listed.

Size presets & the visitor resize control​

defaultSize sets how large the widget opens on desktop:

PresetApproximate sizeNotes
compact340 × 480 pxA small, unobtrusive panel.
tall380 px × ~70% of viewport heightThe default — a comfortable reading height.
full400 px × full viewport heightMaximum vertical space.

The visitor can cycle between these sizes at any time using a resize control in the widget header. Their choice is remembered in the browser's localStorage and restored on their next visit, so a returning visitor sees the size they last chose rather than the configured default.

Mobile is always full-size

On mobile devices the widget always opens full-screen, regardless of defaultSize. The size presets and the resize control apply on desktop only.

Agent-type transparency indicator​

When showAgentType is true (the default), the widget header tells the visitor who they are talking to:

  • AI Agent — an AI assistant is answering.
  • Automation — an automation/flow is handling the conversation.
  • Human — a member of your team has taken over.

This is a transparency indicator: it makes automated conversation partners clearly identifiable to the visitor, in line with the transparency expectations of the EU AI Act. The label updates live — for example, when a bot escalates and a teammate takes over, the header switches from AI Agent to Human without a page reload.

Set showAgentType to false to hide the indicator.

Message reactions & replies​

allowReactions controls the React button on individual messages inside the widget:

  • true (default) — visitors can add an emoji reaction to a message.
  • false — the React button is hidden.

This toggle gates reactions only. Reply (replying to a specific message) is always available and is not affected by allowReactions.

New workspaces no longer start with an auto-created default widget. Instead, you create the widgets you need from a preset gallery in the widget editor — pick a starting preset (for example a support bubble or a newsletter signup) and customize it with the options above. Existing widgets are unchanged.

RCS as a widget channel​

The widget can offer RCS (Rich Communication Services) as a channel, alongside WhatsApp, Telegram, Messenger, Instagram, Email and SMS. RCS is offered only when your workspace has an active RCS channel, and whether it appears for support, for newsletter opt-in, or both is driven by the RCS agent's declared use case.

For RCS as a full messaging channel (capabilities, sending, delivery model), see the RCS channel guide.

Why RCS is different from other channels​

Every other messenger channel has a public click-to-chat URL — WhatsApp's wa.me, Telegram's t.me, Messenger's m.me. RCS has none. The officially supported website/QR entry point for an RCS business agent is an sms: deep link that carries the agent's messaging service id, which has the form {agent_id}@rbm.goog.

Tapping the link opens the visitor's default messaging app. On a device that is RCS-capable and whose carrier has your agent launched, it upgrades to a branded RCS conversation with your agent. Otherwise it opens plain SMS (when a fallback number is configured) or shows the messaging app's built-in error.

There are two deep-link formats:

FormatShapeWhen it is used
Service id onlysms:{service_id}?body={message}No SMS fallback configured. On a non-RCS device this shows the messaging app's error.
With SMS fallbacksms:+{fallback}?service_id={service_id}&body={message}A fallback number is configured. On a non-RCS device the message is sent as a plain SMS to that number.

The @ in the service id must be percent-encoded in the URL so the phone's URI parser does not read it as an address separator.

Support widget: supportSignupOptions.rcs​

On a support widget, RCS appears under supportSignupOptions.rcs. The sms: deep link is pre-built on the server (with a default "Hi, I need help!" message), because a support entry point has no per-visitor list choice:

{
  "supportSignupOptions": {
    "rcs": {
      "direct_link": "sms:sendseven_x_agent%40rbm.goog?body=Hi%2C%20I%20need%20help%21",
      "qr_code_base64": "data:image/png;base64,iVBORw0KGgo...",
      "launched": true
    }
  }
}
FieldTypeDescription
direct_linkstringThe ready-to-use sms: deep link.
qr_code_base64stringA QR code for the same link, as a base64-encoded PNG data URI — ideal for print or on-screen scanning.
launchedbooleanAdvisory only — see The launched flag.

Newsletter widget: availableChannels.rcs​

On a newsletter widget, RCS appears under availableChannels.rcs. Here the deep link is built on the client, because the opt-in message depends on which list(s) the visitor is subscribing to (the body is start {slug1}_{slug2}, exactly like the WhatsApp newsletter opt-in). The widget receives the pieces it needs to assemble the link:

{
  "availableChannels": {
    "rcs": {
      "service_id": "[email protected]",
      "fallback_number": null,
      "launched": true
    }
  }
}
FieldTypeDescription
service_idstringThe RCS agent's messaging service id ({agent_id}@rbm.goog). The widget uses it to build the sms: link client-side.
fallback_numberstring | nullAn optional SMS-capable fallback number. When null, the widget emits the service-id-only format; when present, it emits the SMS-fallback format so non-RCS devices still reach you by SMS.
launchedbooleanAdvisory only — see below.

The launched flag is advisory​

launched reflects whether the RCS agent is launched on at least one carrier. It is advisory only — it does not remove the RCS option. The channel/chip still shows even when launched is false, so you can surface RCS to visitors before carrier launch is complete. Use the flag if you want to decide, in your own front-end, whether to present RCS publicly yet.

Data passed through SendSevenConfig​

Your website can hand context to the live chat widget before the chat starts, for example the page topic or the plan a visitor is looking at, so your team and your AI agents do not have to ask for it again. Because this data comes from the visitor's browser, SendSeven applies fixed trust rules to it.

<script>
  window.SendSevenConfig = {
    name: "Ada Lovelace",
    email: "[email protected]",
    custom: {
      interest: "pricing",
      contact_type: "prospect"
    }
  };
</script>

Keys in custom can be a custom field's key, its display name or its id. SendSeven matches them to your custom fields on its servers when the chat starts, in this order: id, then key, then display name. A display name or key that two of your fields share is not matched, so prefer the key. The public widget configuration only lists the custom fields of the widget's pre-chat form, never your full list of custom fields.

Trust rules​

  • Always unverified. The visitor can change anything on the page, so these values are stored as Visitor-provided. Agents and AI agents see them as unverified, and they never verify an email address or phone number.
  • Only existing fields are accepted. A custom key is used only when it matches an active custom field. Unknown keys, inactive fields, empty values and nested objects are ignored. At most 50 keys are read, and each value is limited to 2000 characters.
  • Values must fit the field. Each value is validated against the field type and its validation rules. A select or multiselect field only accepts its defined options. A value that does not fit is not saved.
  • Trusted values are never overwritten. A value set by your team, the API, an import, an integration, a Flow or a contact token is kept. Injected data can fill an empty field and can replace a value that was itself visitor-provided or set by AI.
  • Signed chats only fill empty fields. When the chat is linked to a contact through a contact token or identity verification, injected custom data only fills fields that are empty.
  • Contact details are claims. An injected name is used only when the contact has no name yet. An email or phone never replaces a saved primary address or number, and a value that belongs to another contact creates a merge suggestion for your team instead of linking the chat to that contact. contactId is never trusted.

Limit injected data to the widget's form fields​

By default, SendSevenConfig.custom can set any active custom field. As an optional hardening step you can limit it to the custom fields of the widget's pre-chat form. Values for other fields are then not saved to the contact.

In the widget editor, open Advanced → Custom data from your website and choose Only pre-chat form fields. Through the API, set customDataScope in the widget config:

customDataScopeEffect
all_fields (default)Any active custom field can be set.
form_fieldsOnly custom fields that are part of the widget's pre-chat form (required or optional fields) can be set.

An unrecognized value is treated as form_fields. The trust rules above apply in both modes.

The same settings section, and the embed code dialog, show a notice: "This data can technically be changed by the visitor. For trusted data, use contact tokens."

Data that must be trusted

For a plan, an account status, an order or anything an AI agent should rely on, send the data from your backend with a contact token, or sign the visitor's identity with identity verification. See Customer context for how the sources fit together.

Next Steps​