> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yourhomie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Script attributes, global config objects, and language and Shopify market resolution for the homie embed.

You configure the homie embed in two ways: attributes on the `<script>` tag, or global config objects set on `window` before the script loads. At minimum, set `chatbotId`. Styling and behavior are managed from the homie platform and pulled in automatically.

```html theme={null}
<script
  src="https://cdn.yourhomie.ai/embed.min.js"
  chatbotId="YOUR-CHATBOT-ID"
  defer
></script>
```

See the [Installation overview](/en/user-guide/installation/overview) for platform-specific setup.

## Script attributes

Set these directly on the `<script>` tag.

| Attribute   | Required | Description                                                                                          |
| ----------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `chatbotId` | Yes      | Your chatbot's unique ID. The embed will not load without it.                                        |
| `domain`    | No       | The chat host origin. Defaults to `https://chat.yourhomie.ai` — you normally don't need to set this. |
| `storeId`   | No       | Store identifier forwarded to the chat (used for store-scoped catalogs).                             |
| `platform`  | No       | Set to `shopify` to enable Shopify cart integration and storefront market detection.                 |
| `lang`      | No       | Force a language (for example `de`). Overrides automatic detection.                                  |
| `country`   | No       | ISO 3166-1 alpha-2 country code for tax-correct pricing.                                             |
| `currency`  | No       | ISO 4217 currency code for tax-correct pricing.                                                      |

## window\.homieBotConfig

As an alternative to script attributes, set `window.homieBotConfig` **before** the embed script loads. This is useful when your CMS or tag manager makes it easier to set globals than attributes.

```html theme={null}
<script>
  window.homieBotConfig = {
    chatbotId: 'YOUR-CHATBOT-ID',
    storeId: 'your-store-id',
    platform: 'shopify',
    lang: 'de',
    country: 'DE',
    currency: 'EUR',
  };
</script>
<script src="https://cdn.yourhomie.ai/embed.min.js" defer></script>
```

<ParamField path="chatbotId" type="string">
  Your chatbot's unique ID. Used if no `chatbotId` script attribute is present.
</ParamField>

<ParamField path="domain" type="string" default="https://chat.yourhomie.ai">
  The chat host origin.
</ParamField>

<ParamField path="storeId" type="string">
  Store identifier forwarded to the chat.
</ParamField>

<ParamField path="platform" type="'shopify' | null">
  Set to `shopify` to enable Shopify cart and market integration.
</ParamField>

<ParamField path="lang" type="string">
  Force a language code, overriding automatic detection.
</ParamField>

<ParamField path="country" type="string">
  ISO 3166-1 alpha-2 country code for tax-correct pricing.
</ParamField>

<ParamField path="currency" type="string">
  ISO 4217 currency code for tax-correct pricing.
</ParamField>

<Info>
  Script attributes take priority over `window.homieBotConfig`. The embed also writes the resolved values back into
  `window.homieBotConfig` after it loads.
</Info>

## window\.homieUserConfig

Set `window.homieUserConfig` **before** the embed loads to forward an identity and arbitrary metadata to the chat iframe. This is an advanced option used to associate conversations with a known visitor.

```html theme={null}
<script>
  window.homieUserConfig = {
    user_id: 'user-123',
    user_hash: 'hmac-signature',
    user_metadata: { plan: 'pro', segment: 'returning' },
  };
</script>
<script src="https://cdn.yourhomie.ai/embed.min.js" defer></script>
```

<ParamField path="user_id" type="string">
  A stable identifier for the current visitor.
</ParamField>

<ParamField path="user_hash" type="string">
  A server-generated verification hash for the `user_id`.
</ParamField>

<ParamField path="user_metadata" type="Record<string, unknown>">
  Arbitrary key-value data. The embed Base64-encodes it before forwarding it to the iframe.
</ParamField>

## Language resolution

The effective language is resolved from the first available signal:

<Steps>
  <Step title="Script attribute or config">
    A `lang` script attribute, otherwise `homieBotConfig.lang`.
  </Step>

  <Step title="HTML lang">
    The `lang` attribute on the page's `<html>` element.
  </Step>

  <Step title="URL path">
    A locale segment in the current URL path.
  </Step>

  <Step title="Chatbot default">
    The chatbot's configured default language. If the resolved locale is not in the chatbot's active translations, the default is used.
  </Step>
</Steps>

## Shopify market resolution

When `platform` is `shopify`, the embed forwards the visitor's active market `country` and `currency` for tax-correct pricing. The value is resolved from:

<Steps>
  <Step title="Explicit override">
    A `country` / `currency` script attribute, otherwise `homieBotConfig.country` / `homieBotConfig.currency`.
  </Step>

  <Step title="Shopify storefront globals">
    Otherwise `window.Shopify.country` and `window.Shopify.currency.active`, which Liquid-theme Shopify shops expose.
  </Step>
</Steps>

<Note>
  Market detection from `window.Shopify` only applies when `platform` is set to `shopify`. On non-Shopify sites, only
  explicit `country` / `currency` values are forwarded.
</Note>