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.

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.

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​