Widget JavaScript API
Identify visitors, pass data and events, and control the chat widget from your own code. No token needed.
The widget puts a global asktrix object on your page. Use it to tell us who the visitor is, to attach data from your app, and to open or hide the chat from your own buttons.
Install
Copy the snippet from Settings → Channels → Installation. It looks like this:
<script async src="https://asktrix.org/widget.js" data-workspace="YOUR_WORKSPACE_ID"></script>
| Attribute | Required | Meaning |
|---|---|---|
data-workspace |
yes | Your workspace ID |
data-locale |
no | Language of the widget, e.g. de. Only applies when the widget language is set to "Detect automatically". Without it, the widget uses the browser language and falls back to English. |
The widget renders in a Shadow DOM, so your CSS doesn't leak into it and its CSS doesn't leak into your page.
Wait until it's ready
The script loads asynchronously. Code that runs earlier can queue callbacks:
window.asktrixReady = window.asktrixReady || [];
asktrixReady.push((trix) => {
trix.identify({ email: "[email protected]", name: "Jane Doe" });
});
Callbacks pushed after the widget is ready run immediately. The widget also dispatches an asktrix:ready event on window, with the API in event.detail.
You can also queue plain calls before the script loads, with a small stub:
window.asktrix = window.asktrix || function () { (asktrix.q = asktrix.q || []).push(arguments); };
asktrix("consent", true);
Every method can be called by name like this, asktrix("open"), or directly, asktrix.open(). Methods that change something return the API, so calls chain:
asktrix.identify({ email: "[email protected]" }).setData({ plan: "pro" }).open();
Visitor data
These need the Start plan or higher. On Free they're accepted and ignored.
identify({ email, name, phone })
Sets the contact's email, name and phone number. All fields are optional. Empty values are skipped, so calling it on every page view is fine.
asktrix.identify({ email: "[email protected]", name: "Jane Doe", phone: "+49 151 123456" });
Identification isn't verified. A visitor can call identify() with any email in the browser console. Don't use it to grant access to anything, and don't show sensitive account data in the chat based on it alone.
setData(data)
Stores custom data on the contact. Values must be strings, numbers or booleans. Keys you've set before are overwritten, others stay. Strings are cut at 500 characters. A contact holds at most 200 keys.
asktrix.setData({ plan: "pro", mrr: 49, trial: false });
The data shows in the inbox side panel under Attributes and in the REST API as customData.
addLabels(...labels)
Adds labels to the contact. Labels are lowercased. At most 30 per call.
asktrix.addLabels("vip", "beta");
track(event, data?)
Records an event on the contact's timeline, for example a signup or a purchase. data is a flat object with up to 20 keys.
asktrix.track("upgraded", { from: "start", to: "team" });
Campaign journeys can start on events.
Control the widget
| Method | Does |
|---|---|
open(), close(), toggle() |
Opens or closes the chat window |
show(), hide() |
Shows or hides the chat button |
send(text) |
Sends a message as the visitor |
isOpen() |
true while the chat window is open |
isVisible() |
true while the chat button is shown |
user() |
{ email, name, phone } as known to the widget |
Open the chat from your own link:
<a href="#" onclick="asktrix.open(); return false;">Talk to us</a>
If the widget is hidden by a rule under When & where it shows, the methods do nothing.
Events
on(event, callback) returns a function that removes the listener.
| Event | Payload |
|---|---|
message |
A reply from your team or Trix: { id, conversationId, from, type, content, createdAt }. from is teammate or ai. |
open |
none |
close |
none |
const off = asktrix.on("message", (m) => console.log(m.from, m.content));
// later
off();
Consent and cookie banners
By default the widget starts a chat session as soon as the page loads. If Settings → Channels → Identity & protection → Start session only when widget is opened is on, nothing is stored until the visitor opens the chat.
If you use a consent manager, tell the widget the visitor's decision:
asktrix.consent(true); // a session may start before the chat is opened
asktrix.consent(false); // no automatic session; opening the chat still works
identify(), setData(), addLabels() and track() never start a session on their own while none is allowed. They wait until the visitor opens the chat or gives consent, and then they're sent.