# Live chat on your website

The Texa Desk chat bubble on any website: install, settings, who the visitor is, identity validation, events.


Live chat puts a chat bubble on your website. Every chat lands in Texa Desk, where your team
(and Texa AI, if you turn it on) answers it. This page covers adding it to any website, telling
it who the visitor is, and checking that nobody pretends to be someone else.

## Add it to your website {#install}

In Texa Desk, open **Settings → Inboxes → Add inbox → Website** and give it your website's
name and address. The last step shows your code. You can copy it again at any time from the
inbox's **Configuration** tab. It looks like this:

```html
<script>
  (function(d,t) {
    var BASE_URL="https://desk.texadesk.com";
    var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
    g.src=BASE_URL+"/packs/js/sdk.js?v=2";
    g.async = true;
    s.parentNode.insertBefore(g,s);
    g.onload=function(){
      window.texaSDK.run({
        websiteToken: 'your-website-token',
        baseUrl: BASE_URL
      })
    }
  })(document,"script");
</script>
```

Paste it on every page, just before `</body>`. Most website builders have a place for it:

| Where your site is built | Where the code goes |
|---|---|
| WordPress | Use our plugin (below), or paste the code with the free plugin **WPCode** (**Code snippets → Header & footer → Footer**). |
| Wix | **Settings → Custom code → Add custom code**: body end, all pages. Needs a paid Wix plan with a connected domain. |
| Shopify | **Online store → Themes → ⋯ → Edit code → `theme.liquid`**, just before `</body>`. |
| Squarespace | **Settings → Advanced → Code injection → Footer**. |
| Webflow | **Site settings → Custom code → Footer code**, then publish. |
| Google Tag Manager | A new **Custom HTML** tag, triggered on **All pages**. |
| Your own code (React, Next.js, Vue…) | Load it once in your main layout, the same way as any other script. |

### WordPress plugin {#wordpress}

1. [Download the plugin](https://api.texadesk.com/docs/downloads/texa-desk-chat.zip).
2. In WordPress, go to **Plugins → Add New → Upload Plugin**, choose the file and activate it.
3. Open **Settings → Texa Desk chat** and paste your website token: the value after
   `websiteToken:` in the code above. Save.
4. Optional: paste the **Secret key** from the inbox's Configuration tab too. People signed in
   to your WordPress site then chat as themselves, with identity validation, and the chat forgets
   them when they sign out.

Open your website and the chat bubble appears in the corner. Send a test message and it shows
up in Texa Desk under that inbox.

## Settings

Set `window.texaSettings` before the code runs to change how the chat looks:

```html
<script>
  window.texaSettings = {
    position: "left",          // "left" or "right"
    locale: "fr",              // the chat's language
    useBrowserLanguage: true,  // or follow the visitor's browser
    type: "expanded_bubble",   // a wider bubble with a label
    launcherTitle: "Chat with us",
    darkMode: "auto",          // "light", "dark" or "auto"
    hideMessageBubble: false
  };
</script>
```

## Tell it who the visitor is

When a visitor is signed in on your website, pass their details so your team sees who they are
and their past chats follow them across devices:

```js
window.addEventListener("texa:ready", function () {
  window.$texa.setUser("user-1042", {   // your own id for this person
    name: "Ada Obi",
    email: "ada@example.com",
    phone_number: "+2348012345678",
    identifier_hash: "..."              // see Identity validation below
  });
});
```

Call `window.$texa.reset()` when they sign out, so the next person on that device starts a new
chat.

Other commands on `window.$texa`:

| Command | What it does |
|---|---|
| `setCustomAttributes({ plan: "Gold" })` | Saves facts about the person on their contact |
| `deleteCustomAttribute("plan")` | Removes one |
| `setConversationCustomAttributes({ order: "A-77" })` | Saves facts on the current chat |
| `setLabel("vip")` / `removeLabel("vip")` | Adds or removes a label on the chat |
| `setLocale("fr")` | Changes the chat's language |
| `setColorScheme("dark")` | `"light"`, `"dark"` or `"auto"` |
| `toggle("open")` / `toggle("close")` | Opens or closes the chat |
| `toggleBubbleVisibility("hide")` | Hides or shows the bubble (`"show"`) |
| `popoutChatWindow()` | Opens the chat in its own window |
| `reset()` | Forgets the visitor (on sign-out) |

## Identity validation {#identity-validation}

Without it, anyone who knows how the code works could call `setUser` with someone else's id and
read their chats. Identity validation stops that: your server signs the visitor's id with a
secret key, and Texa accepts the id only with the right signature.

1. In Texa Desk, open the inbox's **Configuration** tab and copy the **Secret key** under
   Identity validation. Keep it on your server. Never put it in a web page or an app.
2. On your server, make `identifier_hash`: an HMAC-SHA256 of the visitor's id with the secret
   key, written as hex.
3. Send the hash to the page and pass it to `setUser` with the same id.

<!-- tabs -->
```js
// Node.js
const crypto = require("crypto");
const identifierHash = crypto
  .createHmac("sha256", process.env.TEXA_CHAT_SECRET)
  .update(String(user.id))
  .digest("hex");
```

```python
# Python
import hashlib, hmac, os
identifier_hash = hmac.new(os.environ["TEXA_CHAT_SECRET"].encode(),
                           str(user.id).encode(), hashlib.sha256).hexdigest()
```

```php
// PHP (WordPress too: get_current_user_id())
$identifier_hash = hash_hmac('sha256', (string) $user_id, getenv('TEXA_CHAT_SECRET'));
```

```ruby
# Ruby
identifier_hash = OpenSSL::HMAC.hexdigest("sha256", ENV["TEXA_CHAT_SECRET"], user.id.to_s)
```
<!-- /tabs -->

Turn on **Require identity validation for all conversations** once your website sends the hash
for every signed-in visitor. From then on a `setUser` without a valid hash is refused.

If the secret key is ever exposed, press **Rotate key** and put the new key on your server. Hashes
made with the old key stop working at once.

## Events

The chat tells your page what happens, so you can react to it:

| Event | When |
|---|---|
| `texa:ready` | The chat has loaded and `window.$texa` is ready |
| `texa:on-message` | A message arrives in the chat (`event.detail` has it) |
| `texa:on-start-conversation` | The visitor starts a new chat |
| `texa:opened` / `texa:closed` | The chat window opens or closes |
| `texa:error` | Something went wrong, such as a refused identity |

```js
window.addEventListener("texa:on-message", function (event) {
  console.log("New message", event.detail);
});
```

## In a mobile app

To show this chat inside an iOS or Android app, turn on **Enable widget in mobile apps** on the
inbox's **Configuration** tab. Apps don't send a website address, so without it the chat is
refused when you limit it to your own domains. For Texa AI that works inside your app and in
your customers' accounts, see [Your website and app](/guides/website-and-app).

## Older code

Code that calls `window.chatwootSDK`, `window.$chatwoot`, `window.chatwootSettings` or listens
for `chatwoot:` events keeps working. New code should use the `texa` names above.