Add Tidio to your Astro site's shared layout with one external script. You do not need a package for Tidio. Checked with Astro 7.4.13.

In this article, you'll learn:

Find your Public key

Log in to your Tidio panel and go to Settings > Developer > Project data. Click the Public key field to select its value, then copy it.

The Project data page with the Public key field, masked private key and Visit widget SDK documentation button visible

The Public key is part of the script address that every visitor's browser loads, so you can keep it in front-end code. The private key on the same page is different: never put it in your website.

You'll find the same key inside the installation code in Settings > Live Chat > Installation, under Manual install:

<script src="//code.tidio.co/YOUR_PUBLIC_KEY.js" async></script>
Settings > Live Chat > Installation with Manual install selected, the code snippet visible, and the Copy to clipboard button.

Add the widget to Astro

Add your Public key to .env in the project root. Replace YOUR_PUBLIC_KEY with your key:

PUBLIC_TIDIO_KEY=YOUR_PUBLIC_KEY

Use this shared layout in src/layouts/Layout.astro. Keep your existing head and page content if you already have a layout. Place the Tidio script just before the closing body tag:

---
const tidioKey = import.meta.env.PUBLIC_TIDIO_KEY;
---
<html lang="en">
  <head><meta charset="utf-8" /><title>My site</title></head>
  <body>
    <slot />
    <script is:inline src={`https://code.tidio.co/${tidioKey}.js`} async></script>
  </body>
</html>

Wrap each page's content in this layout. The is:inline directive tells Astro to leave the external script as it is, so the built HTML has one async script tag with your key in its address. Set PUBLIC_TIDIO_KEY in the environment that builds your deployment too, then rebuild.

Astro builds a multi-page site by default. Every navigation loads a new document, and each document loads the script once.

Sites that use ClientRouter

Astro's ClientRouter from astro:transitions replaces the page body on every navigation. That removes the chat widget from the page, and the Tidio script does not run again, so the widget stays away until the next full page load. We saw this with the live widget on Astro 7.4.13.

Keep Astro's default navigation on a site that uses the widget. If you need ClientRouter, add data-astro-reload to your links. A link with this attribute loads a full page, and the widget loads with it:

<a data-astro-reload href="/pricing">Pricing</a>

If an AI coding assistant edits this project for you, give it the prompt from Install Tidio with an AI coding agent.

Check the installation

Open your site in a regular browser window. The chat widget appears in the corner of the page and stays there when you move between pages. Headless and automated browsers may not show the widget, so do not rely on them for this check.

Loading a page with the widget is what activates it. After that, Settings > Live Chat > Installation in your Tidio panel says Chat Widget is installed properly.

Silent walkthrough. A demo Astro site with the Tidio chat widget in the corner. Each page loads the widget, and the Checkout page hides it.

Identify logged-in visitors

In src/layouts/Layout.astro, insert this inline script immediately before the external Tidio script. Replace the example account data with your signed-in visitor's data, and only set it when that account is known. Do not publish one customer's identity for all visitors. Inline scripts run in the browser, not in Astro frontmatter:

<script is:inline>
  document.tidioIdentify = {
    distinct_id: 'unique_id',
    email: 'contact@mail',
    name: 'John Doe',
    phone: '+44 2032897807',
  };
  document.addEventListener('account:login', (event) => {
    const updateVisitor = () => window.tidioChatApi.setVisitorData(event.detail);
    if (window.tidioChatApi) updateVisitor();
    else document.addEventListener('tidioChat-ready', updateVisitor, { once: true });
  });
  document.addEventListener('account:logout', () => {
    delete document.tidioIdentify;
    if (window.tidioChatApi) window.tidioChatApi.resetVisitor();
  });
</script>

document.tidioIdentify must be set before Tidio loads. Tidio uses it to merge conversations for the same visitor. If your authentication code resolves later, use the login handler after load instead. setVisitorData updates visitor details but does not merge conversations.

The event names above belong to your application, not Tidio. After a successful login, have your authentication code dispatch:

document.dispatchEvent(new CustomEvent('account:login', {
  detail: { email: 'contact@mail', name: 'John Doe' }
}));

After logout, dispatch the event below. The handler removes the old identity before resetting the widget, so the restart does not read the previous account's data:

document.dispatchEvent(new Event('account:logout'));

Hide the widget on some pages

For the default full-page navigation used above, add this page-level inline script inside the layout wrapper on every page. It hides the widget on paths beginning with /checkout and shows it elsewhere:

<script is:inline>
  (() => {
    function updateVisibility() {
      window.tidioChatApi.display(!location.pathname.startsWith('/checkout'));
    }
    if (window.tidioChatApi) {
      window.tidioChatApi.on('ready', updateVisibility);
    } else {
      document.addEventListener('tidioChat-ready', updateVisibility, { once: true });
    }
  })();
</script>

The ready handler waits for Tidio before it changes visibility. Hiding the widget does not stop Flows from triggering. To load the widget only on a list of addresses instead, see Show the widget only on specific pages.

Troubleshooting

  • Check that PUBLIC_TIDIO_KEY contains your Public key and is present when you build. Rebuild after changing it.
  • If you see two widgets or duplicate requests, remove the second installation. Keep the external script only in the shared layout.
  • Keep window and document inside browser scripts, not the server-side frontmatter between --- fences.
  • If your Content Security Policy blocks the script, allow code.tidio.co in script-src and follow the full Tidio security policy host list.
  • Check the deployed site in a regular browser. Headless and automated browsers may not show the widget.

Further reading