Website widget

One script tag adds a chat launcher to your site. It renders in a Shadow DOM, so your CSS and the widget's never collide. About 11 KB gzipped.

Install#

<script
  src="https://parleyai.app/widget.js"
  data-parley-app="pk_live_…"
  async
></script>

Then add your site's origin under Applications → Website → Allowed origins. Requests from other origins are rejected. Development keys also accept localhost.

/widget.js always serves the latest 1.x release. Pin /widget/v1/widget.js if you prefer an explicit major version.

JavaScript API#

Commands can be queued before the script loads:

window.parley = window.parley || [];
parley.push(["identify", { userId: "usr_123", email: "ada@example.com", userHash }]);

Once loaded, call window.Parley directly:

Name	Type	Description
Parley.open() / close() / toggle()		Control the panel.
Parley.identify({ userId, userHash?, email?, name?, attributes? })	Promise	Identify the visitor.
Parley.logout()	Promise	Forget the visitor on this browser.
Parley.track(name, properties?)	Promise	Record an event.
Parley.trigger(eventName)		Fire event-based invitations.
Parley.on(event, callback)	() => void	Events: ready, open, close, unread.

Proactive invitations#

Invitations are configured in the dashboard, not in code. Each has a message, a page pattern (/pricing*), and a trigger:

Time on page — e.g. after 20 seconds.
Scroll depth — e.g. at 60%.
Custom event — when your code calls Parley.trigger("viewed_pricing_table").

At most one invitation shows per page view, never while the panel is open. Frequency can be once per visitor, once per session or weekly. Dismissing an invitation quiets all invitations for three days. Invitations are desktop-only unless you enable mobile.

Example

# Message:   Need help choosing a plan?
# Pages:     /pricing*
# Trigger:   Time on page — 20 seconds
# Frequency: Once per visitor

Privacy#

The widget stores an anonymous id, a session token and invitation preferences in localStorage. It sets no cookies and loads no third-party scripts. It only creates a session — and a customer record — when the visitor opens the chat.

The widget follows the visitor's light/dark preference unless you force one under Appearance.