Skip to main content

How to Embed a User Interface

Embedding branchly User Interfaces into your website can be accomplished in a few simple steps (5 minutes).

General Steps​

To embed an User Interface, you need to include a script and a container div element in your HTML. You need to replace the id, data-token and src based on your interface and application.

tip

Info: Please go to the user interface in the dashboard and copy & paste the code snippets from there to make sure you use the correct script and container/div. Then change any attributes you need.

1. Insert the Script​

Place the appropriate script within the <body> tag at the bottom or in the <head> of your HTML document.

<script async
  type="module"
  src="<link to script.js>"
></script>

2. Add the Container Div Element​

The div element should be placed where you want the User Interface to appear on your page. Replace <YOUR TOKEN> with the actual token that identifies your Application. You can style the container using CSS to set the desired width and height or specify additional options. The id attribute depends on the User Interface.

<div
  id="<container id for interface>"
  data-token="<YOUR TOKEN>"
></div>

3. Set the Language Tag​

An Application is designed to support multiple languages and regions. To ensure the correct content is displayed, you must specify a valid locale using the two-letter ISO language and country code format.

Option 1: Use the Site-wide Language Tag

You can use the global lang attribute in your site's <html> tag, like so:

<html lang="en_US"> 
<!-- Example for English/United States -->```

Option 2: Specify the Language Tag in the Container

Alternatively, you can set the lang attribute directly in the container div element, which will override the site-wide setting:

<div
  id="<container id for interface>"
  data-token="< YOUR TOKEN >"
  lang="de_DE">
</div>

tip

Tip: Make sure to register your locales and embed locations in the branchly dashboard settings.

4. (Optional) Update Content Security Policy​

If you use a content security policy (CSP), please ensure that your policy includes our domain branchly.io to enable the branchly interfaces to load correctly,. This update allows all necessary scripts, APIs, and assets to execute.

Chat Widget​

Both the script and the div should be placed inside the website’s <body> tag.

script​

<script async
type="module"
src="https://chat-widget.branchly.io/assets/index.js">
</script>

div​

<div
id="branchly-chat-widget-container"
data-token="<YOUR TOKEN>"
data-custom-styles="false"
>
</div>

Optional attributes:

  1. To show the user up to 3 suggested questions, when the widget is in a closed state, set the chat-chat-popup attribute to questions. Each of the questions above the chat bubble serves as an entry point to the chat and clicking on it will start a conversation. You can differentiate for this setting to work only of large screens or also for small screen sizes.

    <div
      id="branchly-chat-widget-container"
      data-token="<YOUR TOKEN>"
      data-chat-widget-popup-lg="questions"
      data-chat-widget-popup-sm="questions"
    ></div>

  2. You can control whether the chat bubble opens by default, when a user visits your web site. This is determined by the data-open-default parameter within the <div> Element.

    <div
      id="branchly-chat-widget-container"
      data-token="<YOUR TOKEN>"
      data-open-default="true"
    ></div>

  3. You can adjust styles (as CSS) already when embedding the Container in your website. A common use case is if you need to adjust the z-index so that other elements on your website do not interfere with the chat widget, when it is opened.

    <div
      id="branchly-chat-widget-container"
      data-token="<YOUR TOKEN>"
      style="z-index: 9999999999"
    ></div>

  4. If you need additional styling, you can customize the chat widget by targeting its class names in your CSS. If you prefer to use the widget’s built-in fixed styles and avoid conflicts with your site’s design, set data-custom-styles="false" on the widget container.

    <div 
      id="branchly-chat-widget-container" 
      data-token="<YOUR TOKEN>"
      data-custom-styles="false"
    ></div>

Custom element <branchly-chat-widget>​

The chat widget is also available as a standalone HTML custom element. Instead of loading the script and adding a container div, you place the element directly in your HTML. It is simpler to embed and reuse across pages and behaves more consistently and predictably.

<script async type="module"
  src="https://chat-widget.branchly.io/assets/index.js"
></script>

<branchly-chat-widget
  data-token="<YOUR TOKEN>"
></branchly-chat-widget>

By default the element renders into its shadow root, keeping the widget's styles isolated from your page. Set data-custom-styles="true" on the element to render into the light DOM instead, so you can style the widget with your site's CSS (the same option as on the container div).

The same optional attributes as on the container div are supported on the element, e.g. data-open-default="true" and the suggested-questions attributes data-chat-widget-popup-lg / data-chat-widget-popup-sm.

<branchly-chat-widget
  token="<YOUR TOKEN>"
  data-custom-styles="true"
  data-open-default="true"
></branchly-chat-widget>

Chat​

script​

<script async
type="module"
src="https://chat-embed.branchly.io/assets/index.js">
</script>

div​

<div
id="branchly-chat-embed-container"
data-token="<YOUR TOKEN>"
>
</div>

Search Interface​

script​

<script async
type="module"
src="https://search-interface.branchly.io/assets/index.js">
</script>

div​

You can embed the search interface using a <div> element with the data-view-mode attribute. There are two options available:

  1. Search Button: Use the search-button mode to display a button styled as a search input that, when clicked, opens the search interface in a modal. This option is ideal for making the search interface available across the entire site.
  2. Inline Search Interface: Use the inline mode to embed the search interface directly into the page without modal behavior. This is suitable for pages where you would like to display search results directly.
<div 
id="branchly-search-interface-container" 
data-token="<YOUR TOKEN>"
data-view-mode="search-button">
</div>

By default, the interface container has predefined styles. If you want to use your own custom styles or override our styling and classes, add the data-custom-styles="true" attribute to the container element before adding any custom styles. You can still style the search entry point (the search button that opens the modal) without this attribute.

<div 
  id="branchly-search-interface-container" 
  data-token="<YOUR TOKEN>"
  data-view-mode="search-button"
  data-custom-styles="true">
</div>

Custom Trigger Button​

Instead of using the built-in search entry button, you can turn any element on your page into a trigger that opens the search interface. Add the data-branchly-search-trigger attribute to the element along with your application token:

<button
  data-branchly-search-trigger
  data-token="<YOUR TOKEN>">
  Search
</button>

When the search interface script loads and finds an element with this attribute:

  • Clicking the element opens the search interface in a modal (the Ctrl/⌘ + K shortcut keeps working as well).
  • The built-in search entry button is not rendered, so your own element fully replaces it.
  • If the page has no branchly-search-interface-container yet, a hidden one is created automatically from the trigger element. An existing container is left untouched, so you can combine a custom trigger with the regular container embedding.
  • Optional attributes you set on the trigger — such as data-custom-styles and lang — are forwarded to the created container.

This is useful when you want the search entry point to match your site's own design system rather than the default branchly button.

Form​

script​

<script
  type="module"
  src="https://form.branchly.io/assets/index.js">
</script>

div​

<div
  id="branchly-form-container"
  data-token="<YOUR TOKEN>"
>
</div>

Set the data-token attribute to your application token. The container requires a lang attribute — either on the container itself or site-wide on your <html> tag (see Set the Language Tag) with a valid locale such as de_DE or en_US.

Navigator​

script​

<script async
type="module"
src="https://embed.branchly.io/assets/index.js">
</script>

div​

<div
id="branchly-embed-container"
data-token="<YOUR TOKEN>"
>
</div>