Chat widget JS API

The chat widget loader defines window.Cliedesk. Use it to open the chat from your own buttons, pass page data to agents and react to chat events. For your own chat UI without the widget, use the headless SDK.

Load the widget

On the WordPress site itself, turn the widget on in Settings → Channels → Chat widget. On another website, copy the embed code from the same screen. It looks like this:

<script src="https://shop.example/wp-content/plugins/cliedesk/build/widget/cliedesk-widget.js"
	data-api="https://shop.example/wp-json/cliedesk/v1/widget/" data-product="general" async></script>

Optional: data-identity="TOKEN" makes the visitor a known customer. See Signed identity.

Call it before it loads

The loader starts after the page loads. Calls made earlier wait in a queue Cliedesk.q and run when it is ready:

<script>
	window.Cliedesk = window.Cliedesk || function () {
		( window.Cliedesk.q = window.Cliedesk.q || [] ).push( [].slice.call( arguments ) );
	};
	Cliedesk( 'setContext', { plan: 'pro' } );
</script>

Queued commands: open, close, toggle, hide, show, prefill, reset, identify, setContext, track and runWorkflow. In consent mode, Cliedesk( 'consent' ) lets the widget start when your own consent banner says yes.

Methods

After the ready event, call the methods directly:

Method	What it does
open(), close(), toggle(), isOpen()	Open or close the panel, or read its state.
hide(), show()	Hide or show the launcher button. A custom launcher can still open the chat.
prefill( text )	Open on a new conversation with the text ready to send.
startConversation( { message, subject?, fields? } )	Start a conversation without the panel. Resolves to its id, or null.
sendMessage( text )	Send in the visitor’s open conversation, or start one. Resolves to true or false.
showArticle( id )	Open the help view on a help article.
search( query )	Open the help view with a search.
identify( token )	Use a signed identity token. '' goes back to a guest.
reset()	Forget the visitor, for example at sign-out.
setContext( pairs )	Up to 50 key and value pairs, sent with each message and shown to agents. null clears them.
setFields( fields )	Field values sent with the next conversation.
setLocale( locale ), setProduct( product )	Change the language or the product.
track( name, properties? )	Record a customer event (see below).
runWorkflow( id )	Ask to start a rule on the visitor’s open conversation. Needs an extension that answers it, such as the “A page asks for it” rules of Cliedesk Pro; without one it resolves to false and nothing runs.
unreadCount()	Team messages that arrived while the chat was closed.
on( event, fn ), off( event, fn )	Listen to events. on returns a function that stops listening.

setContext keys use letters, digits, space, ., _ and - (up to 40 characters). Values are cut at 200 characters. The pairs are kept for the browser session. Context and fields come from the browser, so agents see them as untrusted. Use a signed identity for data you must trust.

Any element with the data-cliedesk-open attribute opens the chat when clicked.

Events

Event	Detail
ready	—
open, close, reset	—
conversation-started (also conversation:started)	{ uid }
message (also message:received)	{ id, text } of a team reply
message:sent	{ uid, id }
article:viewed	{ id }
unread:change	{ count }

Each event is also a cliedesk:<name> CustomEvent on window.

const stop = Cliedesk.on( 'message', ( m ) => console.log( 'Team replied:', m.text ) );

Events for extensions

These window events let an extension (such as a live push channel) work with the open chat. Without one, the widget polls as usual.

Event	Who sends it	What happens
cliedesk:poll { uid? }	the extension	The open chat polls at once (only the chat with that uid; all chats without uid).
cliedesk:help-search { q, slot, product }	the widget	The help search settled on q ('' when cleared). slot is an empty box above the results; the extension may fill it with plain DOM (it is inside the widget’s shadow root).
cliedesk:presence-refresh { id? }	the extension	In the agent app: the open conversation id sends its presence beat at once (the customer typing shows now).

The poll answer of GET widget/conversations/{uid}/messages can carry more keys from the PHP filter cliedesk_widget_messages (see Hooks). When the newest team message has buttons and rich.freeText: false, the widget hides its text field and polls with asks=1; it shows the field again when the visitor answers or the poll answer has freeText: true. Polls without asks should cost an extension nothing.

Customer events

A customer event is a fact about a customer, such as “trial started”. It shows on the customer timeline. It can start rules with the trigger A customer event happens, and segment filters can use its count and first and last date.

• In the browser: Cliedesk.track( 'plan.upgraded', { plan: 'pro' } ). It works only for visitors who already have a chat session. It resolves to false otherwise.
• In PHP: cliedesk_log_event( $who, $name, $properties ). $who is a contact id, a WP_User or an email address. See Extending Cliedesk.
• From the command line: wp cliedesk event track <who> <type> --data=<json>. See WP-CLI.

Names use a-z, 0-9, _ and .. A name outside the known namespaces is stored as custom.<name>. Properties are plain values.

Widget tools (Cliedesk Pro)

With Cliedesk Pro, Cliedesk( 'registerTool', name, fn ) (also window.cliedeskPro.registerTool) runs a developer widget tool in the browser when the AI agent uses it. Register the tool on the server with cliedesk_pro_widget_tools. See Pro widget.

Analytics events (Cliedesk Pro)

With Cliedesk Pro and Settings → Developer → Analytics tracking on, the script cliedesk-pro/assets/js/analytics.js listens to the widget events above (open, conversation-started, article:viewed), to cliedesk:help:searched and to the “sent” message of the portal and request forms. It sends these events after analytics consent:

Event	Parameters
cliedesk_help_view	page_type (home, category, article), source (help_center, widget), article_id
cliedesk_help_search	source (help_center, help_search), results, search_term (only when allowed)
cliedesk_widget_open	source (widget)
cliedesk_conversation_start	channel (widget, portal, form)

In Tag Manager mode each event is dataLayer.push( { event: 'cliedesk_widget_open', … } ). In GA4 mode it is gtag( 'event', 'cliedesk_widget_open', { … } ) when the page has gtag, otherwise the same dataLayer push. Parameters never hold an email, a name or message text; search words lose emails, numbers and other signs.

Consent: the WP Consent API category from the settings (wp_has_consent() and the wp_listen_for_consent_change event), or your banner calls window.cliedesk.analytics.consent() (and window.cliedesk.analytics.revoke() when the visitor withdraws). Do Not Track and Global Privacy Control stop all events. The script loads only on pages with a Cliedesk script, with its config in window.cliedeskProAnalytics.