Integrating TrustYou Agent Web Chat – TrustYou Agent

Purpose

This document provides a concise technical overview of how to integrate a TrustYou Agent into a customer website. It describes the setup process, explains how the web chat client works, and includes an example implementation snippet.

The goal is to give customer development teams a clear and practical understanding of what is required to embed a TrustYou Agent.

1. Concept Overview

The TrustYou Agent Web Chat client enables website visitors to interact directly with an AI Agent. Each Agent is hosted by TrustYou and identified by a unique Agent ID.

No hosting or custom client logic is required on the customer side
The web chat client is loaded dynamically from TrustYou via a lightweight JavaScript embed
The client automatically connects to the correct Agent instance using the provided Agent ID

The script mounts the web chat into a shadow root within the customer’s page. This ensures full isolation of styles and DOM structure, preventing any interference between the website’s CSS and the TrustYou Agent interface.

2. Integration Steps

You can copy a ready-made snippet, with your Agent ID already filled in, from your Agent's Website Integration page in the backoffice.

The Agent's Website Integration page in the backoffice, showing the copyable embed code snippet and the QR code option.

Include the following JavaScript snippet anywhere on the target page (typically near the end of the <body> tag):

<!-- Start of TrustYou Agent Script -->
<script type="text/javascript">
  (function(params){
    window.$_TYagent_ = { ...window.$_TYagent_, ...params };

    const tyId = 'ty__agent_src-setup';
    const el = document.createElement('script');
    const root = document.getElementsByTagName('script')[0];
    el.id = tyId;
    el.src = 'https://guest.agent.trustyou.com/embed/a_<agent_id>';
    el.setAttribute('crossorigin', 'anonymous');

    if (!document.getElementById(tyId)) {
      root.parentNode.insertBefore(el, root);
    }
  })({
    language: "en",
    guestConfigurationIdentifier: "city_overview_munich",
    startMode: "small",
    guestContextIdentifiers: {
      reservation_id: "RES-100482",
      confirmation_number: "8891042"
    }
  });
</script>
<!-- End of TrustYou Agent Script -->

Replace <agent_id> with the unique Agent ID provided for the integration (example: a_l1234567s8).

Once included and executed, the chat widget is rendered dynamically and automatically connected to the specified Agent.

2.1 Parametrization

The widget can be parametrized to influence its initial behavior. Every parameter is optional. Note that the parameter names use camelCase -- the widget reads them exactly as written.

The following parameters are supported:

language
Defines the Agent's default language using an ISO 639-1 language code (for example: en, de).
This language is used for:
- The initial welcome message
- The displayed GDPR message (if configured)
This setting has the highest priority for determining the Agent's language. Only the guest can override it by interacting with the Agent in a different language or explicitly requesting a language change.

Language precedence order:
Integration configuration (language) > Guest preferred Browser language > English (fallback)
guestConfigurationIdentifier
The guestConfigurationIdentifier provides additional context to the Agent about the guest's current situation.
It is configured in the TrustYou backoffice and referenced during frontend integration. Typical use cases include indicating:
- A specific page or section (for example, booking flow)
- A city-, country-, or property-specific page
For this parameter to take effect, the identifier must be configured in the TrustYou backoffice.
startMode
Controls how the chat window appears when the page loads. See 2.2 Choosing a Start Mode below.
guestContextIdentifiers
A key/value map of identifiers your page already knows about the guest. The Agent uses them to look up the guest's conversation context, so it can greet the guest by name and answer questions about their stay. See 2.3 Loading a Guest Context below.

2.2 Choosing a Start Mode

startMode decides the state the chat window opens in:

Value	What the guest sees
`minimized`	Only the chat indicator. The window opens when the guest clicks it.
`small`	The chat window, already open, in its regular size in the corner of the page. This is the default for the embedded widget.
`big`	The chat window, already open and maximized over the page.

Example:

startMode: "minimized"

If you want the chat to fill a page of its own instead, use the fullscreen link from the Website Integration page (also available as a QR code) rather than the embed snippet. That page always starts maximized, so you do not need to set startMode for it.

Two separate things are at play here: whether the window is open, and how big it is when it is. startMode sets both, but the Mobile Fullscreen setting in the backoffice only touches the size.

So on a mobile device with Mobile Fullscreen switched on:

minimized still shows only the chat indicator. The guest taps it, and the window then opens maximized.
small opens maximized rather than as a corner window.
big opens maximized, the same as everywhere else.

2.3 Loading a Guest Context

A conversation context holds what TrustYou Agent already knows about a guest -- their name, their current booking, their loyalty status, and more. Your Customer Data Platform (CDP), PMS, or booking engine pushes this context to TrustYou Agent through the Integration API, together with the identifiers that point at it.

guestContextIdentifiers is how your website tells the Agent which context to load. Pass the same identifier values your upstream system sent us:

guestContextIdentifiers: {
  reservation_id: "RES-100482",
  confirmation_number: "8891042"
}

The keys are entirely up to you -- reservation_id, confirmation_number, pms_guest_id, folio_number, and so on. They only have to match the keys your system pushed with the context.

Rules for a successful match

At least two identifiers. A single identifier never resolves a context. The snippet runs in the guest's browser, where anyone can edit the values, so we require two pieces of evidence before we load someone's data.
At least five characters per value. Shorter values are ignored, and the conversation starts without a context.
All identifiers must match the same context. We match on every pair you send (AND logic), exactly as written -- values are case- and format-sensitive. RES-100482 and res-100482 are two different values.
Exactly one context must match. If your identifiers match several contexts, we treat the lookup as unresolved. Add a more specific identifier to narrow it down.

Pick identifiers that travel with the reservation. Two values from the reservation itself -- for example a reservation ID and a confirmation number -- are a better pair than a guest's last name, which is easy to guess and often shared between guests.

When the lookup fails for any reason, nothing breaks: the Agent simply starts an ordinary conversation without guest context. Guests who are not identified are never blocked from chatting.

Passing identifiers to the fullscreen link

The fullscreen chat page takes the same identifiers as URL query parameters. Every parameter except language and guest_configuration_identifier counts as a guest context identifier:

https://guest.agent.trustyou.com/a_l1234567s8?reservation_id=RES-100482&confirmation_number=8891042

The same two-identifier and five-character rules apply.

2.4 Switching Agents Based on What the Deep Link Carries

The snippet is ordinary JavaScript running on your own page, so you decide at page load which Agent to embed and what to pass it. That opens up a pattern worth knowing about.

Many properties run two Agents: a booking Agent that helps anonymous visitors find and book a stay, and a guest Agent that serves people who already have a reservation. A visitor landing on your homepage should meet the booking Agent. A guest who clicks "Manage my stay" in your pre-arrival email should meet the guest Agent, already recognized.

You can serve both from the same page. Put the guest's identifiers into the links you send out:

https://www.example.com/?reservation_id=RES-100482&confirmation_number=8891042

Then let the snippet check for them and pick the Agent to load:

<!-- Start of TrustYou Agent Script -->
<script type="text/javascript">
  (function(){
    const query = new URLSearchParams(window.location.search);
    const reservationId = query.get('reservation_id');
    const confirmationNumber = query.get('confirmation_number');
    const isIdentifiedGuest = Boolean(reservationId && confirmationNumber);

    const agentId = isIdentifiedGuest ? 'a_guest1234' : 'a_booking5678';
    const params = isIdentifiedGuest
      ? {
          language: "en",
          guestConfigurationIdentifier: "pre_arrival",
          startMode: "small",
          guestContextIdentifiers: {
            reservation_id: reservationId,
            confirmation_number: confirmationNumber
          }
        }
      : {
          language: "en",
          guestConfigurationIdentifier: "homepage",
          startMode: "minimized"
        };

    window.$_TYagent_ = { ...window.$_TYagent_, ...params };

    const tyId = 'ty__agent_src-setup';
    const el = document.createElement('script');
    const root = document.getElementsByTagName('script')[0];
    el.id = tyId;
    el.src = 'https://guest.agent.trustyou.com/embed/' + agentId;
    el.setAttribute('crossorigin', 'anonymous');

    if (!document.getElementById(tyId)) {
      root.parentNode.insertBefore(el, root);
    }
  })();
</script>
<!-- End of TrustYou Agent Script -->

The same idea works with values you hold elsewhere. If the guest is signed in, or your CDP already dropped the reservation into your page's data layer, read the identifiers from there instead of the URL -- the snippet does not care where they come from.

What the guest gets out of it

When the identifiers resolve, the guest Agent opens with a welcome message written for that specific guest, referring to their name and their upcoming stay, instead of a generic greeting. Someone who clicks your email link sees the Agent already knows who they are and why they are there.

Three things need to line up for that personalized greeting:

Your Agent has personalized welcome messages switched on. Ask your TrustYou contact if you are not sure.
The context your systems pushed carries a guest name, together with a booking or returning-guest loyalty status. Identifiers alone are not enough to personalize.
The identifiers in the link resolve to exactly one context, per the rules in 2.3.

If any of them is missing, the Agent falls back to its normal welcome message and the conversation continues as usual.

Before you ship this

Whitelist your domain for both Agent IDs (see section 4). The origin check runs per Agent.
Only ever embed one Agent per page load. The snippet guards against a double insert, but the choice of Agent has to be made before the script tag goes in.
Treat identifiers in a URL as shareable. A forwarded email link carries the reservation with it -- which is exactly why we require two identifiers and never expose anything beyond what the Agent needs to help that guest.

3. How It Works

The script dynamically loads the TrustYou Web Chat client from the TrustYou platform
TrustYou returns executable JavaScript that renders the chat UI directly into the page
The Agent ID determines which configured Agent instance (for example, property, brand, or role) is loaded
When a user opens the chat, a conversation ID is created and stored locally in the user’s browser
If the snippet carries guestContextIdentifiers, TrustYou Agent matches them against the guest contexts your systems pushed for this Agent, and binds the conversation to the single matching context

4. Domain Whitelisting

For security reasons, each TrustYou Agent can only be embedded on explicitly approved website origins.

To include the Agent on a website with a specific URL, this URL must be whitelisted in the TrustYou backoffice.

Example allowed origins:

https://www.example.com
https://booking.example.com
https://support.example.com

TrustYou configures these origins in the backend to enable proper domain validation and CORS handling.

5. Summary

Component	Responsibility	Description
Agent Hosting	TrustYou	TrustYou hosts the Agent and the web chat client
Website Integration	Customer	Embed the Agent using the provided JavaScript snippet
Domain Configuration	Customer → TrustYou	Provide the list of allowed website origins
Agent IDs	TrustYou	Provided per Agent configuration
Guest Context	Customer → TrustYou	Push guest and reservation data through the Integration API, then pass at least two matching identifiers in the snippet

What's Next

With the embed snippet in place, style the widget and confirm your Agent is ready before your first guests arrive:

Customize Your Chat Widget's Colors, Spinner, and Controls -- match the chat window to your brand
Set Up Your Brand Name, Logo, and Colors -- set the chat indicator guests see first
Agent Settings to Review Before Going Live -- run through the pre-launch checklist
Testing Your Agent with Preview -- smoke-test the Agent's answers before real guests arrive