Extending Cliedesk

Other plugins extend Cliedesk with PHP functions from cliedesk/src/functions.php. They exist as soon as Cliedesk loads, so you can call them in any plugins_loaded callback. Keys use a-z, 0-9 and _. If your registration fails, Cliedesk turns off only your item. The rest keeps working.

Check that Cliedesk is active first:

add_action( 'plugins_loaded', function () {
	if ( ! function_exists( 'cliedesk_register_action' ) ) {
		return;
	}
	// Register your items here.
} );

Registries

Function	What it adds	Where it shows
cliedesk_register_action( $key, $args )	An action (label, callback, fields, capability, contact, customer, flags)	Rule steps and card buttons. It becomes the Action ext.{key}.
cliedesk_register_trigger( $key, $args ) + cliedesk_trigger( $key, $id, $values )	A rule trigger (label, subject: conversation or contact)	Rule editor
cliedesk_register_condition( $key, $args )	A rule condition (label, type: bool, text, number, choice; choices; callback)	Rule editor (not views)
cliedesk_register_record_source( $key, $args )	External records (label, plural, capability, find, get, schema)	Customer sidebar and records
cliedesk_register_context_panel( $key, $args )	A sidebar panel that shows a card	Conversation and contact sidebar
cliedesk_register_widget_card( $key, $args )	A card on the chat widget Home (title, render, audience: all, users, guests)	Chat widget
cliedesk_register_report_metric( $key, $args )	A number (label, unit: count, seconds, percent; formula; value)	Reports overview as ext_{key}
cliedesk_register_settings_section( $key, $args )	A settings form (title, fields: bool, int, string, enum)	Settings → Developer → Add-on settings
cliedesk_register_lab( $key, $args )	An experiment (label, description, default)	Settings → Developer → Labs

Read a value with cliedesk_get_setting( 'ext_{key}.{field}' ). Never store secrets in add-on settings. Check a lab with \Cliedesk\Extension\Labs::enabled( $key ). An admin switches labs on or off for the site, and each change is audited.

Actions and flags

cliedesk_register_action( 'acme_ticket', array(
	'label'    => 'Open an Acme ticket',
	'fields'   => array( 'queue' => array( 'label' => 'Queue', 'type' => 'text' ) ),
	'callback' => fn( array $subject, array $input ) => array( 'ticket' => acme_open( $subject['conversationId'], $input['queue'] ) ),
) );

The callback gets {conversationId} (or {contactId} with 'contact' => true) and the step input. It can return variables that later reply and note steps use as {vars.name}. Throw to fail the run. The default capability is cliedesk_manage_automation.

Flags: readonly, destructive, customer and ai_tool. Free stores ai_tool with the action, but Free has no AI and no AI tool list. The AI tool registry is part of Cliedesk Pro.

Context panels

cliedesk_register_context_panel( 'acme_loyalty', array(
	'title'      => 'Loyalty',
	'capability' => 'cliedesk_view_contacts',
	'places'     => array( 'conversation', 'contact' ),
	'render'     => fn( array $subject ) => array(
		'blocks' => array( array( 'type' => 'fields', 'items' => array(
			array( 'label' => 'Points', 'value' => acme_points( $subject['contactId'] ) ),
		) ) ),
	),
) );

render gets {conversationId?, contactId} and the viewer, and returns a card. It runs only when the panel is shown, and only for people with the capability. An error or an invalid card shows inside this panel only. Panels in an iframe with a JS bridge come with Cliedesk Pro.

Cards

One card format is used in sidebar panels, in agent replies (shown in the chat widget and the customer portal) and on the widget Home.

• title (up to 120 characters) and an optional badge: { text, tone }. Tones: neutral, info, success, warning, danger.
• blocks (up to 20): text, fields (label and value pairs), list, image (an https url and alt), buttons (up to 6; each has a label and either an https url or an action with fixed input) and form (an action, a submit label and up to 10 inputs of type text, number, select or bool).

An invalid card is refused with field errors, for example blocks.2: An image needs an https address.

Buttons and forms run actions registered with cliedesk_register_action(). In the sidebar, they run as the agent. In a reply, the card goes in the reply’s rich parts as rich.card. The customer’s button or form then runs exactly the action and input written in the card, with the permissions of the agent who sent it. Email and other plain channels get a text version of the card.

Customer events

cliedesk_log_event( $user, 'license.activated', array( 'plan' => 'pro', 'seats' => 5 ) );

$who is a contact id, a WP_User or an email address. The function returns the event id, or null when nobody matched. See Chat widget JS API for the browser and the rules side.

Hooks

Every recorded event fires cliedesk_event_recorded and cliedesk_event_{type}. Filters change the widget config (cliedesk_widget_config), notifications (cliedesk_notification_content) and email templates (cliedesk_email_template). The full list is in Hooks and filters. In the app, Settings → Developer → Setup Health → Hooks for developers lists them; with WP_DEBUG on, it shows the attached callbacks.

Modules

A larger extension can be a module. Implement \Cliedesk\Extension\Module (id(), dependencies(), register( ModuleContext $context )) and add it on the cliedesk_register_modules action with $registry->add( $module ). register() must only register things: no queries, no HTTP. An exception there disables only that module. The module API is frozen within extension API 1 (CLIEDESK_EXTENSION_API).

See also: Internal REST API, WP-CLI and the contributor guide in README.