@gail-ai/conversation-embed

From the makers of Gail, comes a package so cool you'll want to use it on your website. You'll have your customers in awe of your AI-powered Gail assistant!

A chat embed and widget for the Gail chat channel that allows users to chat with a Gail that you have setup in the Gail Portal.

This package is a Web Component that encapsulates the Gail chat channel and widget. It is designed to be used in a variety of frameworks and environments and will work with any framework on any modern browser.

Installation

npm install @gail-ai/conversation-embed

CDN

<script src='https://unpkg.com/@gail-ai/conversation-embed' type='module'></script>

Required Props

All components accept these required props.

| Property | Type | Description | |---|---|---| | assistant-id | string | The Assistant ID | | org-id | string | The Organization ID |

<gail-chat />

A chat embed for the Gail chat channel that allows users to chat with a Gail that you have setup in the Gail Portal on your assistants page.

This will expand to fill the open space given to it so it can appear seamless on your website.

Inline Chat Example

<gail-chat
  org-id="your-org-id"
  assistant-id="your-assistant-id" />

<gail-drawer />

A drawer component for the Gail chatbot that slides in from the left or right side of the screen. Provides a chat interface that can be expanded to fullscreen.

Required Props Example Example

<gail-drawer
  org-id="your-org-id"
  assistant-id="your-assistant-id"/>

All Props Example Example

<gail-drawer
  org-id="your-org-id"
  assistant-id="your-assistant-id"
  position="right"
  default-width="400"
  default-height="600"
  chat-title="Chat with Gail">
</gail-drawer>

Optional Props

| Property | Type | Description | Default | |---|---|---|---| | button-image-url | string | The URL of the custom image to use for the drawer button. Defaults to customImageUrl when unset. | "" | | button-style | GailButtonStyle string | Optional styling overrides for the drawer toggle button chrome (shape, spacing, and inner content). Accepts a GailButtonStyle object or a JSON string with keys: style (raw CSS overrides as a string or object, applied last), padding (e.g. "10px 16px"), radius (border-radius override; defaults to a circle), and content (text/emoji that replaces the icon, treated as already-localized). Button colors still come from the colors prop. Example: '{"content":"Chat with us","padding":"10px 16px","radius":"8px"}'. Not sent to the iframe. | none | | chat-title | string | Chat Window Title | "Chat with Gail" | | default-width | number | The width of the drawer (in pixels) | 400 | | drag-positions | IconPosition[] boolean string | Enables the end user to press-and-drag the drawer toggle icon and snap it to a preset icon position. The chosen spot persists in localStorage (gail:drawer:iconPosition) so the user's preference survives reloads. Accepts false (default — dragging disabled), true (every IconPosition is a valid snap target), an IconPosition[], a JSON array string (e.g. '["bottom-right","top-right"]'), or a comma-separated string. Empty or invalid lists resolve to disabled. | false | | icon-position | "bottom-left" "bottom-right" "center-left" "center-right" "inline" "top-left" "top-right" | The position of the drawer toggle button on the page. The corner/edge presets render a fixed floating button. Use "inline" to render the button in normal document flow exactly where the <gail-drawer> tag is placed (no fixed positioning); the drawer panel still slides in from the position edge. | "bottom-right" | | icon-size | number | The size of the drawer icon (in pixels) | 50 | | position | "left" "right" | The position of the drawer on the page (left or right) | "right" | | shortcut-keys | string string[] | Optional keyboard shortcut keys that toggle the drawer open/closed when pressed with Ctrl (Windows/Linux) or Cmd (macOS). Accepts a single key string (e.g. "g"), a comma-separated string (e.g. "g, k"), a string[], or a JSON array string (e.g. '["g","k"]'). Keys are matched against event.key case-insensitively and require no other modifiers — Alt or Shift combos do not trigger. Keys that the browser/OS reserves or that are part of universal editing muscle memory (a, c, f, n, q, r, t, v, w, x, y, z) are rejected with a console.error and ignored. Suggested safe keys: g, k, i, m, b, e, /, s, p, l. Mouse click continues to work when this prop is set. When the shortcut opens the drawer, focus is moved to the iframe. | none | | visibility | VisibilityRule[] string | Optional visibility rules that hide the drawer's outer chrome based on the page URL or vertical scroll position. Accepts an array of VisibilityRule, a JSON string of that array, or a plain string (shorthand: treated as a single urlRegex hide rule). Supported rule types are "urlRegex" and "scrollPos"; scrollPos rules compare against window.scrollY. Any rule that says "hide" wins. Does not affect the iframe URL or its contents. | always visible |

<gail-widget />

A widget for the Gail chatbot that allows users to chat with a Gail that you have setup in the Gail Portal on your assistants page.

Required Props Example Example

<gail-widget
  org-id="your-org-id"
  assistant-id="your-assistant-id"/>

All Props Example Example

<gail-widget
  org-id="your-org-id"
  assistant-id="your-assistant-id"
  position="bottom-right"
  icon-size="60"
  default-width="350"
  default-height="500">
</gail-widget>

Optional Props

| Property | Type | Description | Default | |---|---|---|---| | button-image-url | string | The URL of the custom image to use for the widget button. Defaults to customImageUrl when unset. | "" | | button-style | GailButtonStyle string | Optional styling overrides for the widget button chrome (shape, spacing, and inner content). Accepts a GailButtonStyle object or a JSON string with keys: style (raw CSS overrides as a string or object, applied last), padding (e.g. "10px 16px"), radius (border-radius override; defaults to a circle), and content (text/emoji that replaces the icon, treated as already-localized). Button colors still come from the colors prop. Example: '{"content":"Chat with us","padding":"10px 16px","radius":"8px"}'. Not sent to the iframe. | none | | chat-title | string | Chat Window Title | "Chat with Gail" | | default-height | number | The height of the small chat window (in pixels) | 500 | | default-width | number | The width of the small chat window (in pixels) | 350 | | drag-positions | WidgetPosition[] boolean string | Enables the end user to press-and-drag the widget button and snap it to a preset position. The chosen spot persists in localStorage (gail:widget:position) so the user's preference survives reloads. Accepts false (default — dragging disabled), true (every WidgetPosition is a valid snap target), a WidgetPosition[], a JSON array string (e.g. '["bottom-right","top-right"]'), or a comma-separated string. Empty or invalid lists resolve to disabled. | false | | icon-size | number | The size of the widget icon (in pixels) | 60 | | position | "bottom-center" "bottom-left" "bottom-right" "center-left" "center-right" "inline" "top-center" "top-left" "top-right" | The position of the widget button on the page. The eight corner/edge presets render a fixed floating button. Use "inline" to render the button in normal document flow exactly where the <gail-widget> tag is placed (no fixed positioning); the pop-out chat window still anchors to the bottom-right corner. | "bottom-right" | | shortcut-keys | string string[] | Optional keyboard shortcut keys that toggle the widget open/closed when pressed with Ctrl (Windows/Linux) or Cmd (macOS). Accepts a single key string (e.g. "g"), a comma-separated string (e.g. "g, k"), a string[], or a JSON array string (e.g. '["g","k"]'). Keys are matched against event.key case-insensitively and require no other modifiers — Alt or Shift combos do not trigger. Keys that the browser/OS reserves or that are part of universal editing muscle memory (a, c, f, n, q, r, t, v, w, x, y, z) are rejected with a console.error and ignored. Suggested safe keys: g, k, i, m, b, e, /, s, p, l. Mouse click continues to work when this prop is set. When the shortcut opens the widget, focus is moved to the iframe. | none | | visibility | VisibilityRule[] string | Optional visibility rules that hide the widget's outer chrome based on the page URL or vertical scroll position. Accepts an array of VisibilityRule, a JSON string of that array, or a plain string (shorthand: treated as a single urlRegex hide rule). Supported rule types are "urlRegex" and "scrollPos"; scrollPos rules compare against window.scrollY. Any rule that says "hide" wins. Does not affect the iframe URL or its contents. | always visible |

Common Optional Props

These props are available on every component (gail-chat, gail-widget, gail-drawer) and behave identically across all three.

| Property | Type | Description | Default | |---|---|---|---| | allow-emoji | boolean | When true, allows emoji input and rendering in the chat. | false | | custom-image-url | string | The URL of the custom image to use as the assistant logo. | "" | | lang | "ca" "de" "en" "es" "fr" "hi" "it" "ja" "ko" "pl" "pt" "ru" "sv" "zh" | Optional language override for chat responses. | Gail/browser default | | persist-welcome | boolean | When true, keeps the welcome message visible after the first user interaction instead of collapsing it. | false | | show-welcome-message | boolean | True if the chat should show the welcome message, false will show the default input / How can I help text | true | | store-messages | boolean | When true, tells the iframe chat to persist conversation state for 24 hours so returning users can choose to resume their previous conversation. When false, every page load starts a fresh conversation. When unset, the iframe's default applies (currently: store messages for 24 hours). | true | | user-reference | string | The user reference to use for the chat, advanced feature for identifying users | "" | | user-session | string | The session id to use for the chat, advanced feature for authenticating users | null | | verbose | string | When "true", displays configuration errors on the page; otherwise errors are hidden. | "false" |

Colors

Use the colors prop on any component to theme the embed. Pass a GailColors object or a JSON string with any of the keys below. All keys are optional.

| Key | Type | Description | |---|---|---| | primary | { bg?: string; text?: string } | Accent color for buttons and highlights. Seeds widgetButton and header when those are not set, and drives the --gail-color CSS variable. | | widgetButton | { bg?: string; icon?: string; border?: string; shadow?: string; hover?: string } | Background, icon, border, shadow, and hover-background color of the floating/inline widget/drawer button. border, shadow, and hover accept any CSS color string, including alpha values such as rgba(255,255,255,0) or #FFFFFF00. hover is the button background on pointer hover and falls back to bg. Applies to gail-widget and gail-drawer only. | | header | { bg?: string; text?: string } | Background and text color of the chat window header. Applies to gail-widget and gail-drawer only. | | chatBubble | { bg?: string; text?: string } | Background and text color of the user's chat bubble. | | background | { bg?: string; text?: string } | Background and text color of the chat surface, including the host area around the embed. | | input | { bg?: string; text?: string } | Background and text color of the user input field. | | assistantText | string | Text color for assistant responses. |

Example

<gail-widget
  org-id="your-org-id"
  assistant-id="your-assistant-id"
  colors='{"primary":{"bg":"#50074c","text":"#FFFFFF"},"header":{"bg":"#50074c","text":"#FFFFFF"},"chatBubble":{"bg":"#F3E8FF","text":"#1F1147"}}'>
</gail-widget>

Translations

Use the translations prop on gail-widget or gail-drawer to localize the embed-side chrome (header tooltips and the close-confirmation dialog). Accepts a Translations object or a JSON string — missing keys fall back to the built-in English defaults shown below. translations is never sent to the iframe; the Gail iframe has its own in-iframe localization driven by the lang prop.

The gail-chat component has no header chrome or close confirmation, so translations does not apply to it.

export interface Translations {
  header?: {
    minimize?: string;
    close?: string;
    fullScreen?: string;
    exitFullScreen?: string;
  };
  closeConfirm?: {
    description?: string;
    cancelLabel?: string;
    confirmLabel?: string;
  };
}

header

Tooltips on the header control buttons (fullscreen, minimize, close). Rendered as the title attribute and read aloud by assistive tech.

| Key | Default (English) | Description | |---|---|---| | minimize | Minimize | Tooltip on the Minimize button. | | close | Close conversation | Tooltip on the Close button and aria-label of the confirmation overlay. | | fullScreen | Full Screen | Tooltip on the fullscreen toggle when the panel is not in fullscreen. | | exitFullScreen | Minimize | Tooltip on the fullscreen toggle when the panel is in fullscreen. |

closeConfirm

Copy shown inside the confirmation dialog that appears when the user clicks Close.

| Key | Default (English) | Description | |---|---|---| | description | End this conversation? You will start fresh when you open chat again. | The dialog's body paragraph. | | cancelLabel | Cancel | Dismisses the overlay and leaves the conversation intact. | | confirmLabel | Close conversation | Destroys the iframe and returns the component to its initial state. |

Example

Partial override (HTML attribute):

<gail-widget
  org-id="your-org-id"
  assistant-id="your-assistant-id"
  translations='{"closeConfirm":{"description":"¿Finalizar esta conversación? Empezarás de nuevo cuando vuelvas a abrir el chat.","cancelLabel":"Cancelar","confirmLabel":"Finalizar"}}'>
</gail-widget>

Full override (programmatic JS, e.g. when you already have a translations object in memory):

<gail-drawer id="gail" org-id="your-org-id" assistant-id="your-assistant-id"></gail-drawer>
<script>
  document.getElementById('gail').translations = {
    header: {
      minimize: 'Minimizar',
      close: 'Cerrar',
      fullScreen: 'Pantalla completa',
      exitFullScreen: 'Minimizar',
    },
    closeConfirm: {
      description: '¿Finalizar esta conversación?',
      cancelLabel: 'Cancelar',
      confirmLabel: 'Finalizar',
    },
  };
</script>