Add live chat to Astro

Before you start

• An Astro site with a layout component that every page uses, often src/layouts/Layout.astro.
• Your snippet from Websites in the Pidge inbox.

<script>window.$pidge = []; window.PIDGE_WEBSITE_ID = "YOUR-WEBSITE-ID";</script>
<script src="https://app.pidge.chat/client/l.js" async></script>

Your own copy is in the Pidge inbox under Websites, in Code for your website, with your website ID already filled in. If you've set up a chat domain, it loads from there instead.

Add the snippet

1. Open your shared layout.
2. Paste these two lines inside <head>, with your website ID. Note is:inline on both, and window.$pidge || [] in the first.

<script is:inline>window.$pidge = window.$pidge || []; window.PIDGE_WEBSITE_ID = "YOUR-WEBSITE-ID";</script>
<script is:inline src="https://app.pidge.chat/client/l.js" async></script>

3. Build and deploy as usual.

Why is:inline

Astro processes any <script> that has no attribute other than src. It bundles it and turns it into a module, and modules wait until the page has been read. The loader is async and can run first. Then it finds no website ID and stops, without an error. is:inline tells Astro to leave the script exactly as written, so the two lines run in order. The second line has async, which already keeps Astro's hands off it, but is:inline makes that plain to the next person reading the layout.

If your site uses view transitions

With <ClientRouter /> in your layout, Astro swaps the whole <body> on every page change. The chat bubble lives in the body, so it disappears after the first click. The script doesn't run again, because it's still in the head. Add this to the layout's <head>, after the snippet:

<script is:inline>
  document.addEventListener("astro:before-swap", () => {
    window.__pidgeChat = document.querySelector("[data-pidge]");
  });
  document.addEventListener("astro:after-swap", () => {
    const chat = window.__pidgeChat;
    if (chat && !chat.isConnected) document.body.append(chat);
  });
</script>

It moves the same chat into the new page, so a conversation that's open stays open. transition:persist doesn't help here: it keeps elements that are written in both pages' HTML, and the bubble is added by the script after the page loads.

Without <ClientRouter />, every page is a normal page load and you don't need this.

Open the chat from a button

<button type="button" onclick="window.$pidge.push(['do', 'chat:open'])">Chat with us</button>

A plain onclick keeps working after view transitions. A listener added in a bundled <script> runs once, so it would need to be re-added on astro:page-load. The widget commands list everything else you can push.

List your domains in Pidge

The chat only connects on domains you've listed for the website. In the inbox, open Websites and put each domain on its own line in Domains. Subdomains are included, so example.com also covers www.example.com.

If your host gives the site a second address, like yoursite.netlify.app, list that full address too if people visit it there.

To try the chat while you develop, add localhost to the list too. Pidge matches the host name, so any port works. 127.0.0.1 isn't accepted, so open your dev server at localhost.

Check that it works

1. Open your site in a private window, so you're seeing what a visitor sees.
2. The chat bubble should be in the bottom corner. Send yourself a message and answer it from the inbox.
3. In the inbox, the website's Not installed yet label goes away after the first visit from a listed domain.

If the bubble shows but the chat won't connect, the domain you're on isn't in the website's list in Pidge. If there's no bubble at all, the snippet isn't on the page, or the platform is still serving an older copy of it.

With view transitions, also click through two or three pages and check the bubble is still there.

Astro's own guides: docs.astro.build/en/guides/client-side-scripts/ and docs.astro.build/en/guides/view-transitions/

Other platforms

• WordPress
• Shopify
• Squarespace
• Wix
• Webflow
• Ghost
• Framer
• Next.js
• Carrd
• Plain HTML

Stuck, or did a step look different on your screen? Tell us in the chat on this page.