Embedding Neo Chat in Your Own App or Site

Embedding Neo Chat in Your Own App or Site#

The Neo SDK, the @squirro/neo-sdk package, puts the Squirro chat into a web page or app that is not part of Squirro, such as a documentation site, a customer portal, or an internal tool. Readers ask questions on your page and get the same streamed, cited answers as in the Squirro application, from one of your Squirro projects.

The integration has two parts:

  • A small proxy

    A service that you run alongside your site. It forwards chat requests to your Squirro instance and holds the Squirro credentials, which stay on your server and never reach the browser.

  • The chat itself

    Either a <neo-chat> element loaded with a script tag, or React components. The same script also provides document search and a document view, as the <neo-items> and <neo-item-detail> elements. A theme matches its colors, font, and light or dark mode to your site.

Note

Every reader of the chat works as one service account on your Squirro instance, even when readers sign in to your app. This setup suits documents that any reader may see. Squirro does not recommend it for a public site with sensitive content. See the What Readers Share page.

Bundle or SDK?#

You want to

Use

Add a dashboard with chat to the Squirro application itself.

A bundle and the chat widget. For more information, see the The Chat Widget page.

Put chat on your own site or in your own app.

The Neo SDK, described in this guide.

How It Fits Together#

The browser of the reader sends chat requests with a page token to your proxy. The proxy forwards them with a Squirro token to your Squirro instance, and streams the answer back to the browser.
The browser of the reader sends chat requests with a page token to your proxy. The proxy forwards them with a Squirro token to your Squirro instance, and streams the answer back to the browser.

Anything sent to a browser is public, so the page never holds Squirro credentials. Instead:

  1. The page gets a short-lived token of its own: an anonymous token that the proxy issues for public sites, or the session token of your app for signed-in apps.

  2. The chat sends every request to the proxy with that token.

  3. The proxy checks the token, replaces it with the real Squirro token, forwards the request to your Squirro instance, and streams the answer back unchanged.

The proxy forwards only the requests of the chat itself, plus read-only requests for the documents of the project, and it serves the files of the PDF viewer. Everything else on your Squirro instance stays out of reach.

Requirements#

On the Squirro platform side, you need the following:

  • A Squirro instance on version 3.17.4 or later, with a project that holds the documents that the chat answers from.

  • A non-personal account in the identity provider that your Squirro instance uses for single sign-on (SSO), to serve as the service account. You need administrator access to set its role and add it to the project, and the ability to sign in as it, to create its refresh token and turn off its memory. See the Get Squirro Credentials for the Proxy and Prepare the Service Account and the Project sections of the Set Up the Proxy page.

  • To turn off file storage instead of sharing it, the genai command-line tool, which Squirro Support provides on request. See the Scheduled Tasks and File Storage section of the Set Up the Proxy page.

  • To show PDF documents without a watermark, a Nutrient license key, which Squirro supplies for your deployment. To request it, see the Obtaining a License Key section of the PDF Viewer page, and list the domains that embed the widgets.

On your side, you need the following:

  • A server with Node.js 22.18 or later, which comes with npm, and network access to your Squirro instance. To check the version, run node --version. See the Where to Run the Proxy section of the Set Up the Proxy page.

  • A reverse proxy that serves HTTPS in front of the proxy, usually the web server or load balancer of your site. See the Behind a Reverse Proxy section of the Set Up the Proxy page.

  • For the React components, a React app with react and react-dom 19.3.0 or later, @tanstack/react-query 5.103.2 or later, and the other libraries that the SDK expects from the app. See the With React section of the Add the Chat to Your Page page.

  • If your site has a Content Security Policy, the ability to add the sources that the chat needs. For more information, see the Content Security Policy page.

Set Up the Integration#

Set up the integration in this order:

  1. Install the package, prepare a service account, and run the proxy behind your reverse proxy. See the Set Up the Proxy page.

  2. Add the chat to your page with a script tag or React components, check it, and match it to your site. See the Add the Chat to Your Page page.

  3. Go through the checklist before readers see the chat, and keep the SDK up to date afterwards. See the Go Live and Maintain page.

Before you go live, read what every reader shares through the service account, and where the conversations of readers are kept. See the What Readers Share page.

Once the chat works, you can answer about the page the reader is on, handle links in answers, or ask from your own buttons. See the Connecting the Chat to Your Page page. To show documents and search results without the chat, see the Show Documents without the Chat page. For every option and error code, see the Configuration Reference and Troubleshooting pages.

Contents
This page
View as Markdown