Customer Agent Docs

CustomerAgentOptions

type WidgetLauncherVariableName =
  | "bg-color"
  | "color"
  | "border-color"
  | "border-radius"
  | "border-style"
  | "border-width"
  | "box-shadow"
  | "hover-bg-color"
  | "hover-color"
  | "hover-border-color"
  | "hover-border-radius"
  | "hover-border-style"
  | "hover-border-width"
  | "hover-box-shadow"

type WidgetLauncherVariables = Partial<
  Record<WidgetLauncherVariableName, number | string | undefined>
>

type WidgetHeaderOptions = {
  close?: boolean
  menu?: boolean
}

type WidgetPageOptions = {
  customerOrigin?: string
  pagePath?: string
  pageUrl?: string
}

type CustomerAgentOptions = {
  app_id: string
  anonymous_id?: string
  brand?: { name?: string }
  context?: WidgetContextJson
  context_ready?: boolean
  header?: WidgetHeaderOptions
  launcher?: {
    target?: HTMLElement | string
    placement?: "top" | "right" | "bottom" | "left"
    offset?: number
    style?: Record<string, number | string | undefined>
    variables?: WidgetLauncherVariables
  }
  locale?: string
  messages?: WidgetLocaleMessages
  mobile?: { mode?: "fullscreen" | "bottom-sheet" }
  mount?: HTMLElement | string
  open_on_init?: boolean
  page?: WidgetPageOptions
  position?: "bottom-right" | "bottom-left"
  theme?: {
    colorScheme?: "light" | "dark" | "system"
    primaryColor?: string
    radius?: number
  }
  user?: WidgetUser
}

Fields

Option	Type	Required	Effect	Notes
`app_id`	`string`	Yes	Customer Agent app identifier.	Missing values throw.
`anonymous_id`	`string`	No	Stable logged-out visitor identifier.	Used before a known user id is available.
`brand.name`	`string`	No	Messenger brand display name.	Overrides configured brand name.
`context`	`WidgetContextJson`	No	Initial user context.	Later updates can use `setContext`.
`context_ready`	`boolean`	No	Initial context readiness.	Later updates can use `setContext(..., { ready })`.
`header.close`	`boolean`	No	Controls the panel close action.	Enabled unless set to `false`.
`header.menu`	`boolean`	No	Controls the header more-options menu.	Enabled unless set to `false`.
`launcher.target`	`HTMLElement \| string`	No	Host element used as launcher.	Selector misses fall back to default launcher.
`launcher.placement`	`"top" \| "right" \| "bottom" \| "left"`	No	Desktop panel placement.	Applies to launcher anchoring.
`launcher.offset`	`number`	No	Desktop panel offset in pixels.	Negative values are clamped to zero.
`launcher.style`	`Record<string, number \| string \| undefined>`	No	Inline style fields for the default launcher container.	`color` also applies to the default launcher button.
`launcher.variables`	`WidgetLauncherVariables`	No	Default launcher button style variables.	Values are resolved from the host document before iframe application.
`locale`	`string`	No	Locale override.	Omit to use host locale resolution.
`messages`	`WidgetLocaleMessages`	No	UI message overrides.	Partial message map.
`mobile.mode`	`"fullscreen" \| "bottom-sheet"`	No	Mobile presentation preference.	See Mobile presentation.
`mount`	`HTMLElement \| string`	No	Mount target.	Selector misses fall back to `document.body`.
`open_on_init`	`boolean`	No	Opens Messenger after boot.	Does not emit `widget.opened`.
`page.customerOrigin`	`string`	No	Page origin metadata sent with conversation context.	Overrides automatic page origin detection.
`page.pagePath`	`string`	No	Page path metadata sent with conversation context.	Overrides automatic page path detection.
`page.pageUrl`	`string`	No	Page URL metadata sent with conversation context.	Overrides automatic page URL detection.
`position`	`"bottom-right" \| "bottom-left"`	No	Default launcher position.	Applies to the SDK default launcher.
`theme.colorScheme`	`"light" \| "dark" \| "system"`	No	Color scheme.	Messenger UI theme preference.
`theme.primaryColor`	`string`	No	Primary color.	CSS color string.
`theme.radius`	`number`	No	Corner radius.	Numeric radius value.
`user`	`WidgetUser`	No	Initial visitor identity.	Use `user.id` for a stable logged-in user id.

Type	Reference
`WidgetUser`	Identity and context
`WidgetContextJson`	Identity and context
`WidgetLocaleMessages`	Message keys listed below.

page.customerOrigin, page.pagePath, and page.pageUrl override the page metadata that the SDK detects from the current browser location. These fields are sent as conversation context metadata. They do not change context; user-defined context values remain under userContext.

header.close controls the panel-level close action in the top-right corner. When it is false, the Messenger does not render that close action. This is useful for mounted or WebView integrations where the host app owns navigation and dismissal.

header.menu controls the more-options menu in Messenger headers. When it is false, support and interview headers do not render the menu action. When omitted or true, the menu action is available when that header has menu items.

Mobile Presentation

mobile.mode controls the Messenger presentation selected for mobile viewports. Setting mobile.mode does not force wider viewports to use a mobile presentation.

Value	Effect
`"fullscreen"`	Uses the desktop presentation on wider viewports and fullscreen on mobile viewports.
`"bottom-sheet"`	Uses the desktop presentation on wider viewports and bottom-sheet on mobile viewports.

When a non-mounted Messenger opens in fullscreen presentation, the SDK prevents the host page from scrolling behind the Messenger. Host page scrolling is restored when the Messenger closes, shuts down, or updates away from fullscreen presentation. When mount is set, the SDK treats the Messenger as mounted content and does not lock host page scrolling.

Launcher Styling

launcher.variables customizes the SDK default launcher button inside its iframe. The option accepts only the short keys listed below; unsupported keys have no effect. Values may reference host CSS custom properties, such as "var(--primary)". The SDK resolves the value from the host document before applying it to the default launcher iframe.

launcher: {
  variables: {
    "bg-color": "var(--primary)",
    color: "var(--primary-foreground)",
    "hover-bg-color": "var(--primary-hover)"
  }
}

Variable	Effect
`bg-color`	Base background color.
`color`	Base icon/text color.
`border-color`	Base border color.
`border-radius`	Base border radius.
`border-style`	Base border style.
`border-width`	Base border width.
`box-shadow`	Base box shadow.
`hover-bg-color`	Hover background color.
`hover-color`	Hover icon/text color.
`hover-border-color`	Hover border color.
`hover-border-radius`	Hover border radius.
`hover-border-style`	Hover border style.
`hover-border-width`	Hover border width.
`hover-box-shadow`	Hover box shadow.

launcher.style is the public inline style map for the SDK default launcher container. Its color field also sets the default launcher button color inside the iframe. CustomerAgentOptions does not declare launcher.className. Class names applied to host-side elements and containers do not style the default launcher button inside the iframe. For iframe button styling, use launcher.variables or public inline style fields such as launcher.style.color.

Launcher Geometry

The Messenger panel opens from the resolved launcher position. On desktop, expanded and collapsed sizes resize from that launcher anchor while respecting viewport safe space.

WidgetLocaleMessages

Key	Default meaning	Placeholders
`add_emoji`	Emoji picker label.	None
`assistant_author_ai`	AI assistant author label.	None
`assistant_author_human`	Human support author label.	None
`attachment_label`	Attachment button label.	None
`close_chat`	Close action label.	None
`collapse_window`	Collapse action label.	None
`download_transcript`	Transcript download action label.	None
`expand_window`	Expand action label.	None
`input_placeholder`	Support composer placeholder.	None
`interview_input_placeholder`	Interview composer placeholder.	None
`interview_session_description`	Interview header description.	None
`launcher_close`	Launcher close label.	`{title}`
`launcher_open`	Launcher open label.	`{title}`
`message_aria_label`	Message ARIA label.	None
`more_options`	More options action label.	None
`relative_time_today`	Today label.	None
`relative_time_yesterday`	Yesterday label.	None
`relative_time_day`	Relative day label.	`{count}`
`relative_time_hour`	Relative hour label.	`{count}`
`relative_time_minute`	Relative minute label.	`{count}`
`relative_time_now`	Current-time label.	None
`remove_attachment`	Attachment removal label.	`{name}`
`send_message`	Send message action label.	None
`status_reply_time`	Reply-time status copy.	None
`support_chat_label`	Messenger ARIA label.	`{title}`
`welcome_message`	Initial welcome message.	None

Options

CustomerAgentOptions

Fields

Page Metadata

Header

Mobile Presentation

Launcher Styling

Launcher Geometry

WidgetLocaleMessages

On this page