Skip to main content
This page lists the changes to the widget script (widget.js) that matter to developers. The newest change is first. The script has no version number. It always matches the API that Paperlink AI runs.
​
AI note removed
The panel does not show the AI answers note above the input now.
  • The widget_ai_note_dismissed analytics event is removed. See Analytics events.
  • The widget does not write the paperlink-widget-ai-note-dismissed:v1 storage key now. Values that are already in a browser are ignored.
  • The .pl-ai-note elements are removed from the shadow DOM.
​
Script tag only
The script tag is the only way to install the widget. The npm package @paperlinkai/chat is not supported. Its 0.1.x releases on npm do not work with the API, and version 0.2.0 was never published. If your site uses the package, replace it with the script tag. See Install with a script tag.
  • To start the widget from your code, load the script without data-api-key and call window.PaperlinkAIChat.init, for example for inline mode. See Start the widget from your code.
  • On a script tag page, the default API base URL of init is now the same as for the tag: data-api-base-url, or else the URL of the script without /widget.js. Before, the default was https://api.paperlinkai.com. For https://api.paperlinkai.com/widget.js, the result does not change.
  • New: window.PaperlinkAIChatQueue. Push a function onto it, and the script calls the function with PaperlinkAIChat when it is ready. The script also fires the paperlinkai:ready event on window.
  • New: https://api.paperlinkai.com/widget.d.ts has the TypeScript types for the script tag. See TypeScript types.
  • The standard snippet with data-api-key does not change.
​
Bot check in a frame
The widget runs the Turnstile check in a frame from the API origin (GET /v1/widget/challenge). It does not load https://challenges.cloudflare.com on your page. The frame sends the token to your page with postMessage. The widget accepts the message only from that frame and from the API origin.
  • CSP: add the API origin to frame-src. Your page does not need https://challenges.cloudflare.com in script-src or frame-src. See Content Security Policy.
  • The frame refuses pages that are not on your allowed origins. The widget_session_failed event then has the code TURNSTILE_ORIGIN_NOT_ALLOWED, and the visitor reads the allowed origins copy.
  • New widget_session_failed codes: TURNSTILE_INVALID_KEY, TURNSTILE_BAD_REQUEST, TURNSTILE_NOT_CONFIGURED, TURNSTILE_UNAVAILABLE, TURNSTILE_RATE_LIMITED and TURNSTILE_UNSUPPORTED_PAGE (a page that is not http or https, for example file://).
  • The API accepts only tokens from this frame, for your bot. The 0.1.x releases on npm run the check on your page, so their sessions fail. Use the script tag.
  • Production ignores turnstileSiteKey and data-turnstile-site-key.
​
Default API base URL
For the script tag, the default of data-api-base-url is now the URL of the script without /widget.js. Before, the default was the origin of the script. For https://api.paperlinkai.com/widget.js the result is the same, so your snippet does not change.
​
No model in done
The done event of the answer stream does not have the model field. Do not read it. In the DoneEvent TypeScript type, model is now optional. The other fields do not change.
​
Workspace with no plan
For a workspace that has no plan yet, the widget does not answer. It shows “This assistant is unavailable right now. Please contact the team directly.” and your contact card, with the error code SUBSCRIPTION_INACTIVE.
​
Resume token, #94
The widget keeps a conversation across visits with a resume token. The token lasts 30 days from last use. The widget emits the new event widget_session_resumed. An inline widget and a floating widget for the same bot share one conversation.
​
Answer feedback, #82
The widget shows thumbs for each answer. The onAnalyticsEvent handler receives the new event answer_feedback_submitted with the rating and the reason.
​
Status link, #63
Error messages link to the Paperlink AI status page. The onAnalyticsEvent handler receives the new event widget_status_link_clicked.
​
Inline mode and types, #57 and #58
The init option mode: 'inline' renders the widget inside a container element. For the types, see the “Script tag only” entry above.

Analytics events

See every event that the widget emits.

Inline mode

Render the widget inside a page element.