Add an AI Chatbot to a React or Next.js App

Before you start

This guide uses PrimeWebKit's standard website widget: one external script that loads the chatbot configured in your account. It does not install a native React and Next.jsplugin or automatically connect your site's private data. The platform-specific steps below explain where the snippet belongs and what to verify before making a live change.

• A published PrimeWebKit bot and its current widget snippet from the Widget tab.
• Access to the React or Next.js application's shared document shell, root layout, or app-wide component.
• Knowledge of the app's router and build setup so the script is added once rather than on every route transition.
• The deployed hostname in the bot's allowed-domains setting if the widget uses domain restrictions.

Installation steps

1. 1. Choose the app-wide insertion point

   Editor or file path: React: the HTML document shell used by the build; Next.js App Router: app/layout.tsx; Pages Router: pages/_app.tsx or the custom document where appropriate

   For a plain React application, place the script in the shared HTML document that wraps every route, not inside a component that mounts repeatedly. In Next.js App Router, the root layout is the shared place for app-wide elements. In a Pages Router project, choose the shared application or document layer that matches your rendering needs. Confirm the router and file names in your project before editing.

2. 2. Add the widget script once

   Editor or file path: Shared HTML shell or Next.js root layout → add one bot-specific script

   For React's HTML shell, paste the standard script tag before the closing body tag. In Next.js, import Script from next/script and render it from the root layout with an appropriate loading strategy; do not add one copy to every page component. Retain the data-bot-id from your own bot's Widget tab.

3. 3. Build, deploy, and test route changes

   Editor or file path: Your project's normal build/deploy command → open the production origin

   Run the project's normal build and deployment workflow, then test a production page and navigate between routes. The widget should not create a second launcher after client-side navigation. If the app has separate staging and production origins, allow each required hostname in the bot's settings before testing them.

Widget snippet

Copy the snippet from the selected bot's Widget tab whenever possible. The example below shows the format for your reference; replace the example identifier only with the bot ID from your own copied snippet.

import Script from "next/script";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="${env.widgetJsUrl}"
          data-bot-id="YOUR_BOT_ID"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

This illustrates the Next.js App Router pattern. Add the script once in the actual root layout, copy the real bot ID from the Widget tab, and adapt the surrounding layout to your app.

Platform-specific notes

Next.js's Script component supports loading strategies for external scripts. Keep the widget in the shared layout so it is not repeatedly mounted on each route, and choose a strategy suitable for a non-critical customer chat widget. The snippet below is a Next.js example; the actual script URL is account-configured.

React and Next.js projects vary in their router, document shell, and build tooling. Treat the paths above as common project entry points, then confirm the actual files in your repository. Do not copy a script into both the HTML shell and the root layout.

Before publishing, review any site-wide consent banner, security policy, and domain restrictions already in place. Add the widget only to the pages and hostnames where it is intended to run, and avoid copying account secrets or private customer data into the page source.

Verify the chatbot is working

Test a published page, not just an editor preview. Confirm the launcher is visible, opens when activated, and accepts a question. Ask something answered by the bot's current knowledge sources, then check that an unrelated or unsupported question is handled within the limits of the bot's instructions.

Repeat the check on another page that shares the layout and on each hostname visitors use, such as a staging host and the production domain. If the bot is restricted to allowed domains, include the exact hostname for each environment before testing. Inspect the browser console and Network panel if the script or API request fails; record the specific error rather than changing unrelated settings.

Common problems

Frequently asked questions