How to Add an AI Chatbot to Next.js App Router

To add a hosted AI chatbot to a Next.js App Router site, put its public configuration in the root layout before the embed script and load that script once with next/script. Then test the published domain, client-side navigation, and the mobile page—not just a development preview.

This guide uses Chirps as the working example. It assumes you want a customer-facing assistant on an existing site rather than building your own chat backend. If you need only a few routes to show the widget, put the installation in the layout shared by those routes instead of the application-wide root layout.

Before you edit your Next.js app

1. Create and finish setting up the assistant in Chirps. Test that it answers at least one question from the correct business sources.
2. Open the assistant’s Integration tab and copy its public assistant ID. The ID identifies the widget; it is not a server API key.
3. Set the authorized production domain in the assistant settings. If you test on a separate staging host, use the documented development allowance and turn it off when the production domain is ready.
4. Decide whether the widget belongs on every route or only on a marketing, support, or store route group.

Add the configuration and script to app/layout.tsx

Next.js supplies a Script component for third-party JavaScript. In the App Router, a beforeInteractive configuration script belongs in the root layout; the widget loader can wait until the page is interactive or the browser is idle. The following version prioritizes page content by using lazyOnload.

import Script from "next/script"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script id="chirps-config" strategy="beforeInteractive">
          {'window.chirpsConfig = { assistantId: "YOUR_ASSISTANT_ID" };'}
        </Script>
        <Script src="https://chirps.cc/embed.js" strategy="lazyOnload" />
      </body>
    </html>
  )
}

Replace YOUR_ASSISTANT_ID with the ID copied from your assistant. The public host is https://chirps.cc/embed.js; a localhost script URL will fail on a deployed site. If your root layout already contains HTML, body, fonts, or providers, add the two Script elements inside its existing body rather than replacing the layout.

The configuration must exist before the embed executes. Separating the two scripts by strategy makes that ordering explicit. Next.js documents beforeInteractive, afterInteractive, and lazyOnload and where each belongs. Use afterInteractive for the loader if immediate availability matters more than deferring third-party work, then measure the impact on your pages.

Load it once, in the right layout

Do not paste the same embed into both the root layout and a page component. The widget is meant to persist as users navigate within the site, while each layout should own one copy of its script. If you need it only on a subset of routes, create or use a route-group layout and include the loader there. Test navigating into and out of that group, because route changes can remount layout segments.

A page-specific placement also needs to respect the Script strategy: Next.js requires beforeInteractive in the root layout. For a route-group-only installation, use one client-side loader or another ordered pattern appropriate to that layout; do not move a beforeInteractive script into an arbitrary page and assume it will behave the same way.

Test the deployed site, not only localhost

Common Next.js installation problems

The script loads, but the widget does not appear

Check the browser network panel for the embed and widget configuration requests. A 403 or domain-related response usually means the site host is not authorized for that assistant. Also inspect page visibility settings and browser extensions that block third-party widgets. Chirps has a troubleshooting guide for these checks.

It works locally and fails after deployment

The public domain and staging domain are different origins. Confirm the assistant is allowed on the exact published host and that your site’s Content Security Policy permits the required Chirps script and network connections. Do not loosen a site-wide security policy blindly; add only the origins the integration actually uses and retest.

The chat launcher appears twice

Search your project for embed.js and chirpsConfig. Remove any duplicate loader in a page, tag manager, CMS custom-code slot, or nested layout. Keep one owner for the installation.

The launcher covers a mobile call-to-action

Open the page with the mobile browser keyboard visible and with consent banners active. A widget can be technically functional while blocking a purchase or signup button. Adjust the page’s sticky controls or the widget placement, then verify the full flow on a physical phone.

Keep the assistant useful after installation

Embedding is only the delivery step. Train the assistant on current pages, review its sources, test a missing-answer path, and configure a real human route. The website crawl checklist helps when the widget appears but misses business information. If you are comparing platform install paths, the general embed guide covers other site builders.

Ready-to-publish checklist

• The public assistant ID is correct and no secret API key is embedded in the browser.
• The production domain is authorized; staging access is deliberate.
• One copy of the embed loads on every intended route.
• A full chat, source link, lead or booking path, and human route have been tested.
• The launcher does not cover navigation, consent, checkout, or mobile actions.
• The page’s performance has been measured after installation.