Widget JavaScript API

When the widget script loads it defines a single global function, window.SiteTrellis. Use it to open the chat from your own buttons, tell the agent who the visitor is, pass context about the page or session, and react to what happens in the chat. Everything here is optional: the widget works with no code at all.

Calling the API#

The signature is always SiteTrellis(command, argument1, argument2):

SiteTrellis('open');
SiteTrellis('identify', { name: 'Priya Shah', email: '[email protected]', id: 'u_1042' });
SiteTrellis('on', 'message', function (m) { console.log(m.role, m.content); });

Before the script has loaded#

The widget script loads with async, so your own code may run first. The widget supports a standard command queue: define a small stub before the script tag and any calls made early are replayed in order once the widget starts.

<script>
  window.SiteTrellis = window.SiteTrellis || function () {
    (window.SiteTrellis.q = window.SiteTrellis.q || []).push(arguments);
  };
  SiteTrellis('identify', { name: 'Priya Shah', email: '[email protected]' });
</script>
<script src="https://cdn.sitetrellis.com/v/a44108d9c4521120/widget.js" data-site="site_xxxxxxxxxxxxxxxx" async></script>

Without the stub, window.SiteTrellis does not exist until the script has run, and calling it throws an error. If you cannot add the stub, wait for the script's load event instead:

function whenSiteTrellisReady(fn) {
  if (typeof window.SiteTrellis === 'function') return fn();
  var s = document.querySelector('script[data-site]');
  if (s) s.addEventListener('load', fn);
}
whenSiteTrellisReady(function () { SiteTrellis('identify', { email: '[email protected]' }); });

Commands#

Unknown commands log a warning in the console.

Identifying visitors and passing attributes#

Attributes are simple name and value pairs. They are sent to SiteTrellis, stored with the visitor and conversation, shown to your team in the inbox, available to the prompt as {{visitor.KEY}} variables (see Build your agent), and included in lead and handoff data.

SiteTrellis('identify', {
  id: 'u_1042',              // stored as user_id
  name: 'Priya Shah',        // {{visitor.name}}
  email: '[email protected]',
  plan: 'pro',               // {{visitor.plan}}
  company: 'Northwind'
});

// Later, e.g. when the visitor browses a product:
SiteTrellis('setAttributes', { product: 'Trail Shoe 2', cart_value: 129 });

• Names must start with a letter and contain only letters, digits, underscore, dot or hyphen, up to 40 characters. Values must be strings, numbers or booleans (objects and arrays are ignored). Values are shortened to 500 characters and up to about 30 attributes are accepted in a call.
• An email that is not a valid address is dropped.
• Calls made before the chat session exists are remembered and sent when the chat starts; later calls are sent shortly after (updates within a fraction of a second are merged).
• The widget automatically sends the page address and page title when the chat starts, so you do not need to pass them yourself. They are available as {{page.url}} and {{page.title}}.

Also avoid sending anything sensitive, such as passwords or card numbers: attributes can be included in the text sent to your AI provider.

Events#

Subscribe with SiteTrellis('on', eventName, callback). The callback receives one argument, shown below. An error in your callback is caught and does not affect the widget.

Event payloads are for your page's own use (analytics, UI). Conversation contents are only available to your callbacks in the visitor's own browser; they are not otherwise sent to third parties by the widget.

Examples#

Open the chat from your own button#

<button type="button" onclick="SiteTrellis('open')">Chat with us</button>
<button type="button" onclick="SiteTrellis('sendMessage', 'Is this available in size 42?')">Ask about this product</button>

Send chat events to your analytics#

window.dataLayer = window.dataLayer || [];
SiteTrellis('on', 'conversation:started', function (c) {
  dataLayer.push({ event: 'chat_started', chat_resumed: c.resumed });
});
SiteTrellis('on', 'form:submitted', function (f) {
  if (f.form === 'lead') dataLayer.push({ event: 'chat_lead_submitted' });
});

Single-page apps#

The widget watches for address changes made by your router and re-checks the site's page rules, so include and exclude patterns keep working as visitors navigate. Update attributes as the visitor moves around:

// e.g. in a React router effect
SiteTrellis('setAttributes', { screen: location.pathname });

// On logout: forget the visitor so the next person on a shared device starts fresh
SiteTrellis('reset');

Local testing with data-api#

By default the widget derives its API address from the script address: cdn.example.com becomes api.example.com. If you run SiteTrellis yourself or are testing against a development environment, or if you serve widget.js from a different host, add a data-api attribute with the API origin (no path):

<script src="https://cdn.sitetrellis.com/v/a44108d9c4521120/widget.js" data-site="site_0123456789abcdef"
        data-api="https://api.sitetrellis.com" async></script>

Remember that the page you test from must be in the site's allowed origins (for example http://localhost:3000), or the API refuses it.

Behavior notes#

• The widget remembers an open window and the conversation across page loads when persist session is on (see Widget customization).
• If your page contains the embed snippet twice, the second copy does nothing; the first one wins.
• Calls made after destroy are queued but never run. Reload the page to restore the widget.
• The JavaScript API is a convenience, not a security boundary. All rules are enforced on the server.