> For the complete documentation index, see [llms.txt](https://docs.aisuru.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aisuru.com/en/sharing/publish-your-agent/advanced-embed-and-web-integration.md).

# Advanced embed and web integration

AIsuru's standard embed code is designed to make it easy to add an Agent to a website without building a custom frontend.

For most integrations, copy the code generated by AIsuru and add it to your page. If you need deeper control, the same component can also be configured and integrated programmatically.

> **Looking for the basic installation steps?**\
> [See Embed your Agent on a website.](broken://pages/3QUpbpKqAe5wJqA547Xm)

### The embed uses a Web Component

The AIsuru web embed is based on a standard Web Component rather than an iframe-only integration.

A Web Component can be added directly to an HTML page and configured through HTML attributes without requiring a specific JavaScript framework.

This architecture also allows deeper interaction with the host page when required.

### Why use a Web Component?

Compared with an isolated iframe-only integration, the Web Component can support:

* configuration through HTML attributes;
* direct integration with the surrounding page;
* interaction with host-page elements and the DOM;
* programmatic context and messaging;
* browser events emitted by the Agent;
* frontend styling and customization;
* more complex web-application experiences.

For a simple website integration, you do not need to use these capabilities. The generated embed code is sufficient.

### Load the component

A typical CDN installation loads the Web Component and its stylesheet before adding a `<memori-client>` element:

```html
<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@memori.ai/memori-webcomponent/dist/memori-webcomponent.js">
</script>

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@memori.ai/memori-react/dist/styles.min.css"
/>

<memori-client
  memoriName="MyAgent"
  ownerUserName="my-user"
  tenantID="www.aisuru.com"
  height="500px"
  multilingual="true"
></memori-client>
```

The exact code generated for your Agent may contain additional attributes depending on the Agent, tenant, integration, and selected layout.

### Understanding `<memori-client>`

`<memori-client>` is the custom HTML element that renders the Agent.

Its attributes identify the Agent and control supported aspects of the component's behavior.

A more customized example can look like this:

```html
<memori-client
  memoriName="MyAgent"
  ownerUserName="my-user"
  tenantID="www.aisuru.com"
  context="LOCATION:Milan,USER_TYPE:premium"
  height="100vh"
  showShare="true"
  showSettings="true"
  multilingual="true"
></memori-client>
```

### Documented configuration attributes

The exact attribute set can evolve with the frontend packages. Start from the code generated by AIsuru and use the current Frontend documentation as the technical reference for the version you are running.

Attributes and integration concepts documented across the embed and Frontend references include:

| Attribute / concept | Purpose                                                                        |
| ------------------- | ------------------------------------------------------------------------------ |
| `memoriName`        | Identifies the Agent by name                                                   |
| `memoriID`          | Identifies the Agent by its unique ID when used by the integration             |
| `ownerUserName`     | Identifies the Agent owner by username                                         |
| `ownerUserID`       | Identifies the Agent owner by ID when required                                 |
| `tenantID`          | Identifies the AIsuru tenant/environment                                       |
| `apiURL`            | Defines the backend/API endpoint when explicitly configured                    |
| `engineURL`         | Defines the engine endpoint when explicitly configured                         |
| `baseURL`           | Defines the base URL used by the integration                                   |
| `height`            | Controls the component height                                                  |
| `uiLang`            | Controls the interface language when supported by the integration              |
| `spokenLang`        | Controls the spoken/default language when supported by the integration         |
| `layout`            | Selects the layout when configured directly at component level                 |
| `multilingual`      | Enables multilingual behavior                                                  |
| `showShare`         | Controls availability of sharing controls when supported                       |
| `showSettings`      | Controls availability of the settings interface when supported                 |
| `integrationID`     | Identifies a specific integration                                              |
| `tag` / `pin`       | Legacy/documented role-persona assignment parameters used by some integrations |
| `context`           | Provides initial context to the conversation                                   |
| `initialQuestion`   | Provides an initial question/instruction when supported                        |
| `sessionID`         | Resumes a previous session when supported and valid                            |
| `authToken`         | Supplies an authenticated-user token in integrations that require it           |
| `secretToken`       | Supplies the secret/password token for private or secret Agents when supported |

> **Important:** Do not manually add identifiers or attributes unless you know what value the integration expects. The generated embed code should be your starting point.

### Developer-level UI controls

The React/frontend references expose additional controls for interface elements. These should not automatically be documented as options in the no-code Sharing Layout editor unless they are actually present there.

Developer-level controls currently documented include:

| Prop / control            | Purpose                                             |
| ------------------------- | --------------------------------------------------- |
| `showShare`               | Shows the sharing control                           |
| `showSettings`            | Shows the settings panel                            |
| `showTypingText`          | Shows typing/loading text                           |
| `showInstruct`            | Shows the instruction-mode switch                   |
| `showOnlyLastMessages`    | Limits the visible chat to the most recent messages |
| `showClear`               | Shows the clear-chat/history control                |
| `showLogin`               | Shows the login control                             |
| `showCopyButton`          | Shows the message-copy control                      |
| `showTranslationOriginal` | Shows the original text associated with translation |
| `enableAudio`             | Enables audio output                                |

Treat these as frontend capabilities. Whether the same controls are exposed in the current AIsuru Sharing Layout editor must be verified separately.

### Pass context from the page

The component can receive initial context so that the Agent knows something about the environment in which the conversation starts.

```html
<memori-client
  memoriName="MyAgent"
  ownerUserName="my-user"
  tenantID="www.aisuru.com"
  context="LOCATION:Milan,USER_TYPE:premium"
></memori-client>
```

This is useful when the same Agent is embedded in different pages, customer areas, locations, or applications.

For no-code context configured at sharing-layout level, see Advanced layout settings.

### Listen for Agent events

The web integration can emit browser events that let the host page react to the Agent's state.

For example:

```html
<script>
  document.addEventListener("MemoriNewDialogState", (event) => {
    const state = event.detail;
    console.log("New dialog state:", state);
  });

  document.addEventListener("MemoriEndSpeak", () => {
    console.log("The Agent finished speaking");
  });
</script>
```

Event-based integration can be useful when your page needs to:

* update other interface elements after an Agent response;
* display product or service information;
* synchronize the Agent with application state;
* trigger page-specific behavior.

### Send messages from the host page

Custom controls on the page can send messages to the Agent.

```html
<script>
  function sendCustomMessage() {
    window.typeMessage("Hello from a custom button!");
  }
</script>

<button onclick="sendCustomMessage()">
  Send message
</button>
```

Where supported, hidden messages can communicate information or commands without displaying the text as a normal user message:

```html
<script>
  function sendHiddenMessage() {
    window.typeMessageHidden("system:update", true);
  }
</script>
```

Verify the behavior against the frontend package version you are using before relying on programmatic or hidden-message flows.

### Resume a session programmatically

When a valid `sessionID` is supplied, supported integrations can resume the associated conversation instead of starting a new one.

```html
<memori-client
  memoriName="MyAgent"
  ownerUserName="my-user"
  tenantID="www.aisuru.com"
  sessionID="session-uuid"
></memori-client>
```

For the complete session-resume behavior and lifecycle, use the dedicated Frontend documentation.

### Style and visual customization

The Sharing Layout editor should be the starting point for normal visual configuration.

At frontend level, AIsuru also supports CSS-based customization. This is useful when you need to integrate the component into an existing design system, adapt dimensions or spacing, or coordinate it with other page elements.

The Frontend documentation provides CSS variables for common theme values such as primary colors, text colors, backgrounds, chat bubbles, buttons, drawers, and modals.

Older integrations may also target specific generated CSS classes. For example, chat bubbles or individual interface elements can be styled or hidden by selecting the corresponding class or HTML element.

Because generated markup can change, inspect the current component before relying on internal class names, and prefer supported CSS variables where possible.

#### Legacy selector examples

The previous embed-analysis documentation included examples that targeted generated classes directly, including:

```css
.memori-chat--bubble.memori-chat--with-addon {
  color: #000;
  background-color: #f0f0f0;
}

.memori-chat--ai-generated {
  color: #000;
  background-color: #f0f0f0;
}

.memori-chat--bubble.memori-chat--user-bubble {
  color: #000;
  background-color: #f0f0f0;
}

.memori-button .memori-blob figure {
  opacity: 0;
}
```

These examples show that Agent responses, AI-generated responses, user messages, and specific visual elements can be targeted separately. Re-check selectors against the current rendered component before using them in production.

### CSS, JavaScript, and Agent snippets

Advanced behavior can be implemented in different places:

* **CSS in the host page** for styles that should apply immediately;
* **JavaScript in the host page** for application-level interaction;
* **Agent snippets** for CSS or JavaScript behavior triggered by conversational conditions when that feature is appropriate.

Use the layer that best matches the behavior you are implementing instead of putting all customization inside the embed attributes.

### Mobile viewport behavior

For touch-oriented integrations where browser zoom behavior is undesirable, the legacy advanced-sharing documentation recommends reviewing the page viewport configuration.

A commonly used configuration is:

```html
<meta
  name="viewport"
  content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"
>
```

Only use this when it matches the accessibility and interaction requirements of your web application.

### When to use the generated embed and when to build a developer integration

Use the **generated embed code** when:

* you want to add the Agent to a website quickly;
* Sharing Layout options cover your requirements;
* you only need limited configuration;
* you want AIsuru to manage most of the presentation.

Consider a **developer-level integration** when:

* the Agent needs to react to custom page state;
* the page must react to Agent events;
* you need programmatic context, messaging, or session management;
* you need frontend behavior beyond the Sharing Layout editor;
* you are integrating the Agent into a larger JavaScript or React application.

### Frontend documentation

For developer integrations, also refer to the AIsuru Frontend documentation, especially the sections dedicated to:

* Web Component;
* React component;
* Style and customization;
* Client API;
* Session resume and session management.

The basic Sharing & Publishing documentation remains the recommended starting point when you only need to publish an Agent using the options provided by the AIsuru interface.