> For the complete documentation index, see [llms.txt](https://help.meltingspot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.meltingspot.io/english/manage-spot/embed/multi-domains.md).

# Multi-domains and member redirection

Is your Spot embedded in several places? Declare, for each member, the embed URLs they should be redirected to.

When your Spot is embedded in several places, for instance in your product and on your website, or in a product with one URL per customer (`company1.acme.com`, `company2.acme.com`…), MeltingSpot needs to know **which page to send each member to** when they click a link: notification email, widget content, short link…

This page explains how to declare these URLs for each member, and how MeltingSpot picks the final URL.

{% hint style="info" %}
**Prerequisites**: embed must be activated with a base URL, and the [redirection settings](/english/manage-spot/embed.md#redirection-settings) must be set to `All users` or `SSO users only`. With `No redirection`, the URLs declared for your members are ignored.
{% endhint %}

## Concepts

### Spot base URL and member embed URLs

* **The Spot base URL** is unique. It is set in the `Embed` tab of your Spot settings and is the default URL for all members.
* **A member's embed URLs** belong to that member only. They are a list of URLs, each identified by a **key**:

```json
{
  "default": "https://company1.acme.com/academy",
  "website": "https://www.acme.com/community"
}
```

Keys only exist at member level: there is no list of keys to declare at Spot level. The same key can therefore point to a different URL for each member (for instance `default` pointing to `company1.acme.com` for one member, and to `company2.acme.com` for another).

### The `default` key

`default` is the **only reserved key**. It is used:

* when no key is requested, which is the case for **all notification emails**;
* when the requested key does not exist for the member.

{% hint style="success" %}
We recommend you always set a `default` URL for every member you declare URLs for.
{% endhint %}

### Custom keys

You are free to name the other keys (`company1`, `website`, `customContext`…). They are **case-sensitive**: `Website` and `website` are two different keys.

A custom key is only used when it is passed through the `domain` parameter of a widget, the embed or the Coach (see [Choosing the key](#choosing-the-key-the-domain-parameter)).

### URL format

Each URL must be the full `https://` URL **of the page that hosts the embed** of your Spot, not just the domain. It is the same rule as for the Spot base URL: the embed scripts must be installed on that page.

To open the right resource, MeltingSpot adds its path to the `ms_url` parameter of the URL. The embed script reads this parameter and displays the matching page. Other parameters already in the URL are kept.

```
Member URL  : https://company1.acme.com/academy
Target Live : /lives/<liveId>
Final URL   : https://company1.acme.com/academy?ms_url=%2Flives%2F<liveId>
```

{% hint style="warning" %}
MeltingSpot does not check the format of the URLs you declare. If the URL picked for a member is not a valid URL, they are redirected to the standalone version of the Spot (`https://go.meltingspot.io/spot/{spotId}`).
{% endhint %}

## Declaring a member's URLs

Two methods are available. They don't behave the same way:

|          | JWT token (SSO)                             | API                                  |
| -------- | ------------------------------------------- | ------------------------------------ |
| Members  | Members who log in via SSO                  | All members                          |
| When     | At each SSO login                           | At any time                          |
| Behavior | **Merge**: add, update or remove key by key | **Replace** all of the member's URLs |

{% hint style="info" %}
Admins cannot view or edit these URLs from the Spot's audience table. Use the API to read them.
{% endhint %}

### Via the JWT token (SSO)

Add the `domains` parameter to the user's SSO token (see [Generate an SSO token](/english/manage-spot/sso.md#generate-an-sso-token)):

* `set`: a `{ key: URL }` object of URLs to add or replace;
* `unset`: an array of keys to remove.

```javascript
const userData = {
  sub: user.id,
  firstName: user.firstName,
  lastName: user.lastName,
  email: user.email,
  domains: {
    set: {
      default: 'https://company1.acme.com/academy',
      website: 'https://www.acme.com/community',
    },
    unset: ['oldWebsite'],
  },
};
```

Rules applied at each SSO login, for new and existing members alike:

* keys in `set` are added, or replaced if they already exist;
* keys in `unset` are then removed: a key present in both `set` and `unset` is therefore **removed**;
* keys already stored that are neither in `set` nor in `unset` are **kept**;
* if the `domains` parameter is missing, the member's URLs don't change.

For instance, with the token above:

```
Before: { "default": "https://app.acme.com/academy", "oldWebsite": "https://old.acme.com", "partner": "https://partner.acme.com/academy" }
After:  { "default": "https://company1.acme.com/academy", "website": "https://www.acme.com/community", "partner": "https://partner.acme.com/academy" }
```

{% hint style="warning" %}
Limits: 50 keys maximum in `set`, 255 characters maximum per URL, 50 keys maximum in `unset`. If the `domains` parameter doesn't follow this format, **the whole token is rejected** and the login fails.
{% endhint %}

### Via the API

Use the member update endpoint with the `embedBaseUrls` field:

```bash
curl -X PUT "https://openapi.meltingspot.io/v1/spotMembers/{spotMemberId}" \
  -H "Authorization: <your API key>" \
  -H "Content-Type: application/json" \
  -d '{
    "embedBaseUrls": {
      "default": "https://company1.acme.com/academy",
      "website": "https://www.acme.com/community"
    }
  }'
```

{% hint style="warning" %}
**The API replaces all of the member's URLs**: keys missing from the body are removed. To add a key without losing the others, first read the member's current URLs, then send back the full object.
{% endhint %}

* If the `embedBaseUrls` field is omitted, the member's URLs don't change.
* If you send `{}` or `null`, all of the member's URLs are removed.
* If the field is not an object whose values are all strings, the API returns a `400` error.

To read a member's URLs, use `GET https://openapi.meltingspot.io/v1/spotMembers/{spotMemberId}`: the response contains the `embedBaseUrls` field (`{}` if the member has none).

## Choosing the key: the `domain` parameter

Custom keys are only used when the `domain` parameter is passed. Otherwise, the `default` key applies.

| Source                                                         | Links affected                                           |
| -------------------------------------------------------------- | -------------------------------------------------------- |
| [Widget](/english/manage-spot/widget/implementation.md) script | Clicks on widget content, links shared from the widget   |
| Embed script                                                   | Links generated from the embed (share buttons…)          |
| Coach SDK                                                      | Links of the contents and widgets displayed by the Coach |
| Short link generated from one of these sources                 | The key is stored in the short link                      |
| Notification emails                                            | No key: the `default` key applies                        |

In each of these scripts, add the key to use:

```javascript
domain: 'website',
```

{% hint style="success" %}
Typical use: on each page that embeds a widget or your Spot, set the key matching that page. For instance `domain: 'website'` on your website: a member who clicks a content stays on your website, while their notification emails take them to their `default` URL.
{% endhint %}

## Redirection algorithm

For each link, MeltingSpot computes the member's destination URL as follows:

1. If embed is deactivated, if the base URL is empty, or if redirection is set to `No redirection`: the member is sent to `https://go.meltingspot.io/spot/{spotId}/…`.
2. If redirection is set to `SSO users only` and the member has **never logged in via JWT SSO**: they are sent to `https://go.meltingspot.io/spot/{spotId}/…`.
3. Otherwise, MeltingSpot picks the first available URL, in this order:
   1. the member's URL for the key passed through `domain`;
   2. the member's URL for the `default` key;
   3. the Spot base URL.
4. MeltingSpot adds the resource path to the `ms_url` parameter of the picked URL. If that URL is not valid, the member is sent to `https://go.meltingspot.io/spot/{spotId}/…`.

{% hint style="info" %}

* An empty URL (`""`) is treated as missing.
* Changes to a member's URLs or to the embed settings can take up to one minute to apply.
  {% endhint %}

### Short links

If [short links](/english/manage-spot/customize-your-spot.md#short-links) are activated, emails and `Share` buttons produce a `https://mltngs.pt/s/…` link. This link is **the same for all members**: the destination is computed **when the link is clicked**, for the logged-in member, using the algorithm above.

* A short link generated from a widget, the embed or the Coach configured with a `domain` parameter stores this key. It applies to every member who clicks, falling back to their `default` key if they don't have it.
* Other short links, including those in emails, have no key: the `default` key applies.
* If the member is not logged in, they go through the login page before being redirected.

If short links are deactivated, the link copied from a `Share` button is the URL of the page you are on: every member who clicks it lands on that same embed.

## Full example

Spot configuration: base URL `https://www.acme.com/academy`, redirection set to `All users`.

Members' embed URLs:

* **Alice**: `{ "default": "https://company1.acme.com/academy", "website": "https://www.acme.com/community" }`
* **Bob**: `{ "website": "https://www.acme.com/community" }`
* **Chloe**: no URL

Redirection to a Live (`/lives/<liveId>`):

| Situation                                                 | Alice                                                                          | Bob                                                                       | Chloe                                                     |
| --------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | --------------------------------------------------------- |
| Notification email                                        | `https://company1.acme.com/academy?ms_url=%2Flives%2F<liveId>`                 | `https://www.acme.com/academy?ms_url=%2Flives%2F<liveId>` (Spot base URL) | `https://www.acme.com/academy?ms_url=%2Flives%2F<liveId>` |
| Click in a widget with `domain: 'website'`                | `https://www.acme.com/community?ms_url=%2Flives%2F<liveId>`                    | `https://www.acme.com/community?ms_url=%2Flives%2F<liveId>`               | `https://www.acme.com/academy?ms_url=%2Flives%2F<liveId>` |
| Click in a widget with `domain: 'company2'` (unknown key) | `https://company1.acme.com/academy?ms_url=%2Flives%2F<liveId>` (`default` key) | `https://www.acme.com/academy?ms_url=%2Flives%2F<liveId>` (Spot base URL) | `https://www.acme.com/academy?ms_url=%2Flives%2F<liveId>` |

With redirection set to `No redirection`, all three members land on `https://go.meltingspot.io/spot/{spotId}/lives/<liveId>` in every case.

## Good to know

* **My member lands on go.meltingspot.io although I declared URLs for them. Why?**\
  Check that redirection is not set to `No redirection`. In `SSO users only` mode, check that the member has already logged in via JWT SSO. Finally, check that the picked URL is a valid URL.
* **What happens if the key passed doesn't exist for the member?**\
  The member is redirected to their `default` URL, or to the Spot base URL if they don't have one.
* **What happens for a member I haven't declared any URL for?**\
  They are redirected to the Spot base URL (or to `go.meltingspot.io` in `SSO users only` mode if they have never logged in via JWT SSO).
* **Can the JWT token remove all of a member's URLs?**\
  Yes, by listing all their keys in `unset`. To start over from an empty list, you can also send `"embedBaseUrls": {}` through the API.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.meltingspot.io/english/manage-spot/embed/multi-domains.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.