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

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",
    guest_configuration_identifier: "city_overview_munich"
  });
</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. Currently, 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)
guest_configuration_identifier
The guest_configuration_identifier 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.

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

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