> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talqui.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript API

> Control the Talqui chat on your website with window.$talqui: open it from your own button, identify the user, send context and listen to events.

Once the [snippet](https://docs.talqui.chat/guides/chat-sdks/web.md) is on the page, `window.$talqui` controls the chat. It uses the same commands and events as the [React Native](https://docs.talqui.chat/guides/chat-sdks/react-native.md) and [Flutter](https://docs.talqui.chat/guides/chat-sdks/flutter.md) SDKs.

## Use `$talqui` before it is ready

The snippet loads `async`, so your code may run before the chat. Declare `$talqui` as an array and push commands into it: they run in order as soon as the chat loads.

```html theme={null}
<script>
  window.__TALQUI_TID = "YOUR_TENANT_ID";
  window.__TALQUI_PCID = "YOUR_CONNECTION_ID";
  window.$talqui = window.$talqui || [];
  $talqui.push(["setContact", { name: "Ana Souza", email: "ana@example.com" }]);
  $talqui.push(["setSessionMeta", { plan: "pro" }]);
  $talqui.push(["on", "messageReceived", function (event) { console.log(event.preview); }]);
</script>
<script src="https://webchat.talqui.chat/t.js" async></script>
```

After loading, every command is also a method: `$talqui.open()`. The `push` form keeps working, so both styles are safe at any time.

## Methods

### Open and close the chat

Opens, closes or toggles the chat window.

```js theme={null}
$talqui.open();     // or $talqui.push(["open"])
$talqui.close();    // or $talqui.push(["close"])
$talqui.toggle();   // or $talqui.push(["toggle"])
```

### Show and hide the balloon

Hides the chat balloon, for pages that open the chat from their own button. `hide()` also closes the chat.

```js theme={null}
$talqui.hide();   // or $talqui.push(["hide"])
$talqui.show();   // or $talqui.push(["show"])
```

### Identify the user

Tells the chat who the visitor is. With a `userHash`, the visitor becomes that user and finds their history on any device. See [Identify users](https://docs.talqui.chat/guides/chat-sdks/identify-users.md).

```js theme={null}
// Example 1: name and email only
$talqui.identify({ name: "Ana Souza", email: "ana@example.com" });

// Example 2: a logged-in user, with the hash computed by your backend
$talqui.identify({ userHash: "9f2c…", name: "Ana Souza", email: "ana@example.com", phone: "+5511999990000" });
```

> [!WARNING]
>
> A `userHash` different from the current one switches the chat to that user: the previous visitor's conversation is dropped from the page first. Never put a hash computed for one user on another user's page.

### Update contact details

Sets the name, email or phone without switching users. When these cover the fields your pre-chat form requires, the form is skipped.

```js theme={null}
$talqui.setContact({ name: "Ana Souza", phone: "+5511999990000" });
```

### Attach data to the contact or the conversation

`setContactMeta` describes the person and stays on their contact. `setSessionMeta` describes this conversation. See [Metadata](https://docs.talqui.chat/guides/chat-sdks/metadata.md) for the rules.

```js theme={null}
$talqui.setContactMeta({ plan: "pro", seats: 12 });
$talqui.setSessionMeta({ order_id: "4821", step: "checkout" });
$talqui.setSessionMeta({ step: null }); // null removes a key
```

### Suggest a message

Puts text in the message box. The visitor still decides to send it. Up to 1,000 characters.

```js theme={null}
$talqui.prefill("Hi, I need help with order #4821");
```

### Forget the visitor on logout

Clears the identity, the contact details and the metadata on this browser, starts a fresh anonymous visitor and closes the chat. Call it when the user logs out of your site.

```js theme={null}
$talqui.reset();
```

> [!WARNING]
>
> Without `reset()`, the next person who logs in on the same browser sees the previous user's conversation.

### Listen to events

```js theme={null}
function onReply(event) {
  console.log(event.operatorName, event.preview);
}

$talqui.on("messageReceived", onReply);
$talqui.off("messageReceived", onReply);
```

`on("ready", callback)` also fires right away when the chat has already loaded.

## Events

| Event | When | Callback argument |
| - | - | - |
| `ready` | The chat loaded | `{ webchatVersion }` |
| `chatOpened` | The chat window opened | `{}` |
| `chatClosed` | The chat window closed | `{}` |
| `sessionStarted` | A conversation started | `{ sessionId }` |
| `messageSent` | The visitor sent a message | `{ messageId, type }` |
| `messageReceived` | Your team, a bot or an AI agent replied | `{ messageId, type, preview, operatorName }` |
| `unreadChanged` | The unread count changed. Replies count as unread while the chat is closed or the tab is in the background. | `{ count }` |
| `resetDone` | `reset()` finished | `{}` |
| `error` | A command was rejected | `{ code, message }` |

`preview` holds the first 140 characters of a text reply and is empty for media. `operatorName` is the first name of the person who replied, or `null` for bots.

## Reads

| Read | Returns |
| - | - |
| `$talqui.isOpen()` | Whether the chat window is open |
| `$talqui.getUnreadCount()` | Replies the visitor hasn't seen yet |
| `$talqui.version` | The WebChat version |
| `$talqui.help()` | Prints the commands and events in the console |

## Errors and warnings

The API never throws into your page. An unknown command, an invalid argument or an unknown event name prints a `[talqui]` warning in the console with a link to this page. An exception thrown by one of your callbacks is logged and never breaks the chat.

If another script already uses `window.$talqui` for something else, the chat leaves it alone and the API stays disabled; the console says so.

## Example: open the chat from your own button

Hide the balloon, open the chat from a button in your header and show the unread count on it.

```html theme={null}
<button id="help">Help <span id="help-badge" hidden></span></button>

<script>
  window.$talqui = window.$talqui || [];
  $talqui.push(["hide"]);
  $talqui.push(["on", "unreadChanged", function (event) {
    var badge = document.getElementById("help-badge");
    badge.textContent = event.count;
    badge.hidden = event.count === 0;
  }]);

  document.getElementById("help").addEventListener("click", function () {
    $talqui.push(["open"]);
  });
</script>
```

## Example: identify after login in a single-page app

```js theme={null}
async function onLogin(user) {
  // Your backend computes the hash; never compute it in the browser.
  const { talquiHash } = await fetch("/api/me/talqui-hash").then((r) => r.json());
  $talqui.identify({ userHash: talquiHash, name: user.name, email: user.email });
  $talqui.setContactMeta({ user_id: user.id, plan: user.plan });
}

function onLogout() {
  $talqui.reset();
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.