Website widget

The website widget puts a chat button in the corner of your site. Visitors open it, ask a question and get an answer from your documents, with the documents it came from listed underneath. You set it up in the assistant’s Widget section.

Add the widget to your site

1. Create a website key. In Widget, select Create website key. Give the key a Name, and under Websites list every address the widget will run on, such as https://www.example.com and https://help.example.com. Select Create key.

2. Copy the snippet. Add it to your website now shows one line of code with your website key in it:

   <script src="https://answers.snoowl.com/widget.js" data-snoowl-key="YOUR_SITE_KEY" async></script>

3. Paste it before </body> on every page where the chat button should appear. If your site shares one template or layout across pages, add it there once.

The snippet never changes when you change the widget’s look, so you only paste it once. Pasting it twice on a page still shows one button.

Website keys

A website key starts with ansp_. Because the key sits in your page’s source, where anyone can read it, it’s limited in three ways:

• It works only from the websites you list. A browser on any other site is refused, and the widget doesn’t appear there.
• It can only ask questions, send feedback and load the widget’s look. It can’t call the rest of the API.
• It’s shared by everyone using the widget at once, so its limits apply to all your visitors together.

Websites

Add each address exactly as it appears in the browser’s address bar, with https:// and without a path: https://www.example.com, not www.example.com or https://www.example.com/help. Upper and lower case don’t matter, and a trailing slash is ignored. There are no wildcards: list https://example.com and https://www.example.com separately if your site answers on both. Addresses must start with https://, apart from http://localhost addresses for testing. A key can list up to 20 websites.

Limits

Field	What it does	Default
Per minute	Answers the widget may give in each clock minute, shared by all visitors. 1 to 600.	60
Monthly cap	Answers the widget may give in each calendar month (UTC). Leave empty for no cap.	No cap

Set a monthly cap on every website key. The key is public, so the cap is your ceiling on what anyone can spend through your website.

The line under the snippet shows the key’s websites and limits. To change them, select the key’s Limits in the Endpoint section. A key’s name and type can’t be changed. If you have several website keys, choose which one the snippet uses with Website key. Keys covers revoking a key.

The look

Set the look in the Look card and select Save. Saved changes show on your website within a minute, with no change to the snippet. Preview shows the real widget with your unsaved changes.

Setting	What it does	Limit	Default
Title	Shown at the top of the chat.	60 characters	Empty, which shows the Assistant’s name from settings, or the assistant’s name in the list if that’s empty too
Colour	The button, header and accents. Text on the colour turns dark or light to stay readable.	A hex colour such as #5b5bd6	#5b5bd6
Greeting	The first message in the chat.	300 characters	”Hi! Ask me anything about our product.”
Starter questions	Buttons shown before the first question, so visitors can tap instead of type.	4 questions, 80 characters each	None
Size	Small, Medium or Large chat window.		Medium
Position	Bottom left or Bottom right.		Bottom right
Show sources under answers	Lists the documents each answer came from.		On

The widget answers with the assistant’s saved Model and Tone, shown above the preview. Change them in Assistant settings.

Note

Questions you ask in Preview are real answers. They’re charged and appear in Conversations as Playground answers.

Try it on your live site

To see the widget on your own website before you paste the snippet, select Try on your site in the Preview card.

1. Drag the Snoowl preview button to your browser’s bookmarks bar.
2. Open your website and click the bookmark. The chat button appears in the corner, with the look shown in the Widget section, unsaved changes included.

No bookmarks bar? The same dialog gives a line of code to paste into your browser’s developer console on your site instead.

Nothing on your site changes, and only you see the preview. The preview uses a temporary key that starts with ansv_:

• it works on any website, for 24 hours;
• it allows 20 answers a minute and 100 answers in all;
• making a new preview stops the previous one;
• its answers are charged like Playground answers, and appear in Conversations as Site preview.

What visitors see

• A round chat button, fixed 20 pixels from the bottom corner you chose, above everything else on the page.
• A chat window with your title, the greeting, and your starter questions until the first question is asked. On screens 480 pixels wide or narrower, the window fills the screen.
• A question box that takes up to 2,000 characters. Enter sends the question, Shift+Enter starts a new line, and Escape closes the window.
• Progress while the answer is written: “Searching the docs…”, then “Reading the best matches…”, then “Writing an answer…”.
• The answer, with bold, code, bullet lists and numbered steps shown as formatting.
• Sources under answered questions, when Show sources under answers is on. Each source shows the document’s name. A source from a web page opens that page in a new tab.
• “Was this helpful?” with thumbs up and down. Visitors can change their vote. Votes appear in Conversations and feed Unanswered.
• “Powered by Snoowl” at the bottom of the window.

The widget follows the visitor’s light or dark system setting and their reduced-motion setting. It draws itself in a shadow root, so your site’s styles don’t change it and its styles don’t touch your site.

The conversation follows the visitor from page to page in the same browser tab, up to the last 30 messages, and is cleared when the tab is closed. The last six messages go with each new question, so follow-ups work. Each tab gets its own session ID, which groups that conversation in Conversations.

Content Security Policy

If your site sends a Content-Security-Policy header, allow Snoowl Answers in it:

• script-src https://answers.snoowl.com loads widget.js;
• connect-src https://answers.snoowl.com lets the widget ask questions.

The widget also adds its own stylesheet inside its shadow root. A style-src policy without 'unsafe-inline' may block that stylesheet, and the widget then appears unstyled.

Troubleshooting

The widget doesn’t show an error on your page when it can’t start. It writes one line to the browser’s developer console instead. Open the console on your page and look for a line starting [Snoowl].

What you see	What to check
[Snoowl] widget.js needs data-snoowl-key	The snippet lost its data-snoowl-key attribute. Copy it again from Widget.
[Snoowl] widget not shown: This key isn't allowed from this website	Add the page’s exact address, as shown in the address bar, to the key’s websites. Check www. and https://.
[Snoowl] widget not shown: This endpoint key isn't valid, or it was revoked	The key was revoked or mistyped. Create a website key and paste the new snippet.
No [Snoowl] line and no button	Your site may block outside scripts. Check your Content-Security-Policy, or try a staging page.
The button appears, but answers show an error	The widget shows the reason in the chat. “Too many questions this minute” or “reached its monthly cap” means a key limit. “The workspace’s balance is used up” means your balance needs a top-up (see Billing).
Changes to the look don’t show	Check that you selected Save in the Look card. Saved changes can take up to a minute to reach your site; then reload the page.