Remote appearance

Open the editor

As an organization admin, open Settings → your app → Chat design. Members cannot change app settings.

Remote appearance configures existing SDK components. It does not change your app’s support entry point, upload fonts, replace the chat layout, or run custom code. Set local values in Swift or Kotlin using the Appearance guide. Published appearance applies to iOS and Android apps alike.

The actual editor with example app defaults. Its phone is a web preview; verify the published result in your app.

Draft, preview, and publish

1. Select Conversation, Welcome, or Action cards above the phone preview to edit messages, welcome elements, or review, offer and link cards.

2. Click an element in the phone or select it under Elements. On smaller screens, use the Element menu. Edit its Properties.

3. Choose Language for the translation to edit. Choose Light or Dark to inspect device appearance, and Fit or 100% for preview zoom.

4. Choose Save draft to store your work without changing customer chats, or Publish changes to save and publish the current editor contents together. Publishing does not require saving a draft first.

5. Verify the result in your app after an appearance fetch completes and you open the chat again.

The header distinguishes Unsaved changes, Draft changes, Up to date, and App defaults. Save draft is enabled when the editor differs from its saved draft; Publish changes is enabled when it differs from the published document. There is no automatic saving or publication.

The editor starts from your app’s own design. Once your app runs Reception SDK 1.3 or later and has opened chat, settings you leave unset show the colors, text, icon and switches set in Reception.shared.appearance, as your app last reported them. Publish only what you want to change; your app keeps its own values for everything else. Before the first report, unset settings show the built-in defaults.

The preview’s device appearance selector does not publish a color-scheme override. If Appearance is set to Always light or Always dark, that explicit setting also takes precedence over the preview’s Light/Dark selection. Language, preview state, and zoom are editor controls, not customer settings.

Save conflicts

If another admin or browser tab saved first, the dashboard reports that the app changed or is no longer available instead of overwriting newer settings. Your current edits remain in the open editor. Copy any text and color values you want to retain before reloading, then review the latest draft and reapply your changes. Failed saves also retain the current editor contents for retry.

Available controls

Every remote property is optional. Use app default removes a dropdown override. Clear a text or color field to inherit its local value. Explicitly choosing a default-looking value still publishes an override.

To use your app’s own theme or Swift variables, assign appearance values in Swift and leave the corresponding dashboard overrides unset. The dashboard accepts explicit color values, not Swift variable names. Existing color overrides can be cleared with App colors and then Publish changes; after the updated configuration is fetched and activated, those colors inherit your app’s local values again.

Accent and outgoing bubbles

Select Outgoing messages or Send button, then edit Accent & outgoing bubbles. This corresponds to Reception.shared.appearance.accentColor. It colors outgoing bubbles and accented controls, including the enabled send button and cards without their own color override. Without a local or remote override, it uses the app accent color.

Text on accent

In Outgoing messages or Send button, Text on accent corresponds to onAccentColor. It colors text and symbols on accent surfaces. The SDK default is white; check contrast against both accent variants.

Chat background

Select Background to edit Chat background. This corresponds to chatBackground; the SDK default is the system background.

Incoming bubbles

Select Incoming messages to edit Incoming bubbles. This corresponds to incomingBackground; the SDK default is the secondary system background.

Incoming text

In Incoming messages, Incoming text corresponds to incomingForeground. The SDK default is the primary label color.

Light and dark color values

Each of the five colors has independent Light and Dark fields. Enter an opaque six-digit hex color such as #6954C8. Three-digit hex, alpha values, and color names are not accepted. The color popover offers saturation/brightness, hue, Hex/RGB input, swatches, and Reset to app default for the selected color and mode. Arrow keys adjust the saturation/brightness field; Shift increases the step.

Under Start with a palette, Ocean, Iris, Forest, and Graphite set paired light/dark accent colors and white text on accent. They preserve other settings. App colors clears all five remote color overrides while preserving text and behavior settings. These actions modify the draft until published.

Chat title

Select Chat title. This corresponds to title and accepts up to 80 characters per translation. Without overrides, the SDK displays localized “Support”.

Welcome heading

Switch the preview to Welcome, then select Welcome heading. This corresponds to welcomeTitle and accepts up to 160 characters per translation. Its built-in English text is “Questions, feedback, or a bug?”

Welcome message

In Welcome, select Welcome message. This corresponds to welcomeText and accepts up to 1,000 characters per translation. Its built-in English text is “You're chatting directly with our team.” Welcome text appears in the empty chat, not above an existing conversation.

All three text fields are trimmed when saved. Blank text removes that translation, and placeholder text is not saved unless entered. Choose from the 48 supported languages.

To show one text in every language, turn on Same text in every language under the field. The dashboard then saves it for all 48 languages, so it also works with older SDK versions, and later edits change every language at once. Turning it on replaces the field's other translations; turning it off keeps the text only for the language selected in Language.

The composer placeholder is a built-in localized SDK string. Selecting Send button edits accent colors; there is no custom composer-text option.

Appearance

Under Chat settings, Appearance corresponds to preferredColorScheme:

Font style

Font style corresponds to fontDesign and offers System, Rounded, Serif, and Monospaced. Use app default retains the app’s custom font or local design. System font designs preserve Dynamic Type.

An explicitly selected Font style uses that system font, even when the app sets a custom fontFamily. Use app default restores the app’s font. The dashboard cannot upload or select custom font files, and your local Swift configuration remains unchanged.

Close button

Close button corresponds to showsCloseButton: choose Show, Hide, or Use app default to inherit the local value. The SDK default is false. This adds an optional control when the SDK chat is presented as a sheet; it does not add dismissal UI to a chat embedded in your navigation. The sheet’s native drag indicator remains available.

Close icon

When Close button → Show is selected, Close icon offers Cross ×, Chevron down ⌄, and Arrow down ↓. These map to local .xmark, .chevronDown, and .arrowDown. An explicitly selected symbol replaces the app’s local close image or symbol. Use app default retains the local choice; the SDK default is .xmark. A dashboard custom close image takes precedence over the selected symbol.

The Close button element is selectable only when the draft explicitly shows it. Hiding it removes that selection from the editor without deleting its stored icon setting.

Older messages

Older messages corresponds to fadesOlderMessages: choose Fade bubble color or Keep the same color. Use app default inherits the local setting, whose SDK default is true. Fading lightens older outgoing text bubble fills toward white. Increase Contrast disables this fading even when enabled in appearance settings.

Team photos and names

As an admin, open Settings → your app → Team replies. Show team photos and Show team names are independent switches, both off by default.

• Show team photos: shows the teammate's uploaded profile photo beside the last reply in each group, with an initial when the photo is unavailable. A neutral placeholder reserves the same space while team details load, so replies do not shift sideways. Turning team photos off removes this space.

• Show team names: shows the teammate's first name above each group of replies.

Teammates upload their photo in Settings → Account. Only current organization members with a profile name appear.

A switch publishes its setting immediately and updates the saved editor draft. In Chat design → Chat settings, the same options are Team photos and Team names; editor changes need Publish changes. Reopen chat after the app fetches the update to see it. Use an SDK version that supports team display.

Team photos and names enabled for an example support conversation.

Welcome icon

In the Welcome preview, select Welcome icon. Choose a symbol or upload a Custom image. Icon color sets light and dark colors for symbols. The default is the gray two-bubble icon; the browser preview approximates the native symbols.

Size (16–160 pt, default 44) and Horizontal and Vertical position (up to 120 pt either way) apply to both symbols and images. Drag the icon in the preview to move it; Center explicitly sets both offsets to zero, even if the app moves the icon locally. Use app position removes the position override. Moving the icon never moves the welcome heading or text, and its size scales with Dynamic Type.

Image corner radius (0–80 pt, default 0) rounds welcome images while preserving their aspect ratio. It also applies to an image supplied locally by your app; SF Symbols are unaffected. The radius scales with Dynamic Type and cannot exceed half the image's shortest edge. An explicit 0 makes the corners square, overriding local rounding. Use app corner radius removes only this override and restores the local radius.

To use an image from your app's asset catalog instead, set welcomeIcon in Swift and leave the dashboard icon unset.

Review, offer and link cards

In the Action cards preview, select Review card, Offer card or Link card. Each has its own:

• Button icon and Trailing icon: choose a symbol or an image from your asset library. Defaults are a star and arrow up right for reviews, a gift and chevron for offers, and a link and arrow up right for links (a chevron when the link opens a screen in your app).

• Icon size: 8–28 pt for both icons, default 12, scaled with Dynamic Type.

• Button color and Button text & icons: light and dark colors. Unset, the button uses the accent colors.

If a symbol is unavailable on the device, the SDK uses the default icon. Set button labels and send cards through Reviews, Paywall cards or Links. Link cards need SDK 1.7 or later; older SDKs ignore the link card style. A card without text shows only its button.

Custom images

Welcome, card and close icons can use an image from your organization's asset library. Custom close icon appears when Close button → Show is selected. Choose opens the library; Upload adds a file to it, and the × on an image deletes it. Images keep their own colors; color settings apply to symbols. Choose Remove to return to the symbol.

Library images load from Reception when the chat opens. For an image bundled with your app, set welcomeIcon or closeImage in Swift and leave the dashboard image unset.

The library is shared by all your apps and managed by admins:

• Non-animated SVG, PNG, JPEG or WebP, up to 2 MB per file. Reception converts each file to a transparent PNG of at most 512 px, because iOS can't draw SVG from a URL, and never stores the original.

• The library holds 50 MB of converted images. When it's full, uploads stop until you delete files.

• An image used by any app, in its draft or published appearance, can't be deleted until you replace it there.

Hide elements

Visibility for Chat title, Welcome heading, Welcome message, and Welcome icon has three choices: Use app default, Show, and Hide. Cards have the same choices under Button icon visibility and Trailing icon visibility. Notification status is the “You’ll get a notification when we reply.” line under the person’s latest message once push works on their device; Use app default follows hidesPushStatus in your app. Hidden title, welcome elements and the notification status line stay faintly visible in the preview so you can select them again.

Show overrides local hiding, including hidesTitle, hidesWelcomeTitle, hidesWelcomeText, and hidesPushStatus. For a locally hidden welcome icon without a remote symbol or image, it restores the built-in symbol. Hide overrides any local or remote icon choice. Use app default removes the visibility override and follows the app again.

Restore defaults

Restore default under Properties clears the selected element's overrides, including visibility. For titles and welcome text, it clears every translation. Outgoing messages and Send button share accent colors, so restoring either resets both. Choose Publish changes to apply.

Precedence and fallback

For each supported property, resolution is valid active remote value → local Reception.shared.appearance value → SDK default. Remote appearance must be enabled, and a fetched document must be activated before its values participate. Explicit visibility, font style, close-symbol, and centered-position choices follow the same rule.

Reading Reception.shared.appearance returns your local settings, not the merged appearance displayed by the chat. Remote settings never mutate that property. There is no public getter for the merged appearance.

Per-mode color fallback

A remote light color overrides only the light mode. If its dark value is missing or invalid, dark mode uses the corresponding local color, or the SDK default if none was set. The SDK does not reuse the remote light value for dark mode. A local asset color keeps its own adaptive behavior in any mode that inherits it.

Per-language text fallback

For each text field, the SDK tries the canonical selected app-language tag, then its supported language match, case-insensitively. The selected language comes from Reception.shared.languageOverride when set, otherwise the host app’s iOS-selected localization, or on Android the app’s language as described in Language on Android. See Language for all supported identifiers and matching rules.

For example, an app using de-AT can use a matching de-AT override, then de. If neither has valid text, it keeps the local title or localized SDK default. A published English title does not replace missing German text. An unsupported app language has en as its supported match and can therefore use an English remote override.

Blank or overlong remote text is skipped. Text fields fall back independently: a published title does not require a published welcome message. Local custom strings remain your app’s responsibility to translate and reassign when its language changes.

Changing Reception.shared.languageOverride immediately re-resolves translations in the active remote document and built-in strings. This does not require fetching a new document. The dashboard’s Language menu only chooses what you edit or preview; it never changes a customer’s language.

Explicit values versus inheritance

Hide overrides a local showsCloseButton = true. Follow app clears a local forced dark or light scheme. System overrides a local rounded design or custom font family. Show can reveal an element hidden in Swift, and Center overrides a local icon offset. To retain a local value, choose Use app default, not the option that happens to resemble the SDK default.

Fetching, activation, and offline use

The SDK refreshes published appearance while your app is active, including before the first send. This does not register a support device. Publishing does not update every device instantly.

Newly fetched settings take effect the next time chat opens. An open chat keeps its current remote appearance, and opening never waits for a download. If the first opening uses defaults, allow the app to synchronize online and reopen.

Local appearance edits, language changes, light/dark changes, and toggling remote appearance can still update visible chat immediately.

The last valid appearance is available offline and survives logout. Without a saved appearance, the SDK uses local settings and built-in defaults. If an appearance update cannot be downloaded, the chat keeps its previous styling.

Disable or enable remote appearance

Reception.shared.usesRemoteAppearance defaults to true. Set it on the main actor during app setup to choose local-only behavior. This example belongs in your host app’s Reception setup code, before opening the chat:

import SwiftUI
import Reception

@MainActor
func useLocalSupportAppearance() {
    Reception.shared.usesRemoteAppearance = false
    Reception.shared.appearance.accentColor = .indigo
    Reception.shared.appearance.fontDesign = .rounded
}

Disabling remote appearance uses local settings and stops automatic appearance updates. It preserves the saved appearance and your dashboard publication.

To enable it again, run this in your app’s main-actor setup or settings action:

Reception.shared.usesRemoteAppearance = true

Enabling it restores the saved remote appearance and automatic updates. Newly fetched settings still take effect on the next opening. There is no public force-refresh method.

On Android, the same switch is Reception.usesRemoteAppearance:

Reception.usesRemoteAppearance = false
Reception.appearance.accentColor = ReceptionColor(Color(0xFF4F46E5))
Reception.appearance.fontDesign = Reception.FontDesign.SERIF

Android draws dashboard symbols with the matching Material Symbols icon and uploaded images as they are. Font style → Rounded draws the default font on Android, which has no rounded system font. Sizes and offsets in points apply as density-independent pixels (dp).

Restore defaults

Restore defaults clears the whole editor document. It does not immediately change the saved draft or live appearance. Choose Save draft to retain the reset for later, or Publish changes to publish the empty document. A published reset follows the same fetch-and-next-opening timing as any other change.

An empty remote document restores your app’s local values, including local custom colors and strings. It restores pure SDK defaults only where the app has no local override. For a smaller reset, clear one text translation or color mode, choose Use app default for one behavior, or use App colors to remove all color overrides.

The editor keeps the current draft and publication, not a historical revision list. To return to an earlier custom appearance, re-enter those settings and publish them.

Verify a change and diagnose invisible edits

In a test app, publish a distinctive title for its selected language. Keep the app open and online, then close and reopen chat. Check an empty chat, an existing conversation, and both light and dark modes.

For general integration and connection problems, see Troubleshooting.