LifterLMS Custom Engagement Triggers: Award Achievements From Code

How the LifterLMS engagement engine works, how to register a custom engagement trigger that admins can configure, how to fire it reliably, and how to award certificates and achievements directly from code.

  • Add as a preferred source on Google
Illustration for “LifterLMS Custom Engagement Triggers: Award Achievements From Code”

LifterLMS engagements award achievements, award certificates and send emails when a student does something: enrolls, completes a lesson, passes a quiz, finishes a course. The built-in list covers the common moments. A LifterLMS custom engagement trigger lets you add your own, such as "reached 50% of a course", "completed their profile" or "submitted a project in another system", and configure the reward in the normal admin screen.

This guide is for developers. It explains how the engagement engine decides what to award, shows how to register new triggers with the filters LifterLMS provides, and how to award a certificate or achievement directly from code when a configurable trigger is more than you need. All hooks were checked against LifterLMS 10.3.

If you are new to engagements, start with our overview of LifterLMS engagements and automated emails, then come back here.

How the engagement engine works

An engagement is an llms_engagement post with four settings in the Engagement Settings box: Triggering Event, an optional related post (such as Select a Course), Engagement Type with Select an Engagement, and Engagement Delay in days. They are saved as post meta: _llms_trigger_type, _llms_engagement_trigger_post, _llms_engagement_type, _llms_engagement and _llms_engagement_delay.

At runtime the LLMS_Engagements class does four things:

  1. Listens to a list of action hooks, returned by the lifterlms_engagement_actions filter. The defaults include lifterlms_lesson_completed, lifterlms_course_completed, lifterlms_quiz_passed, llms_user_enrolled_in_course and lifterlms_user_registered.
  2. Parses each hook into a trigger type, a user ID and an optional related post ID. Third parties do this with the lifterlms_external_engagement_query_arguments filter.
  3. Finds published engagements whose trigger type matches and whose related post is either the same post or "any".
  4. Runs the handler for each one immediately, or schedules it with Action Scheduler when there is a delay. The handlers are lifterlms_engagement_award_achievement, lifterlms_engagement_award_certificate and lifterlms_engagement_send_email.

The labels in the Triggering Event dropdown come from llms_get_engagement_triggers(), which is filterable with lifterlms_engagement_triggers. So a complete custom trigger needs a label, a hook to listen to, and a parser for that hook.

Built-in triggers and their gaps

Built-in triggerRelated post
Student creates a new accountNone
Student enrolls in a course / purchases a courseCourse
Student completes a lesson, section, course or course trackLesson, section, course or track
Student completes, passes or fails a quizQuiz
Student enrolls in or purchases a membershipMembership
Student Purchases an Access PlanAccess plan

What is missing are progress milestones, inactivity, profile or onboarding steps, events in other systems (a CRM stage, a live class attended, a form submitted), and combinations such as "completed all three courses in a track before a date". The source even contains a commented-out "days since last login" trigger marked as a to-do. Those are the cases for custom triggers.

Registering a custom engagement trigger

The plugin below adds two triggers. "Student completes their profile" has no related post. "Student reaches 50% of a course" is tied to a course, so admins can choose a specific course or leave it blank for any course.

<?php
/**
 * Plugin Name: LLMSX Custom Engagement Triggers
 */

defined( 'ABSPATH' ) || exit;

// 1. Add the triggers to the "Triggering Event" dropdown.
add_filter(
	'lifterlms_engagement_triggers',
	function ( $triggers ) {
		$triggers['llmsx_profile_completed'] = 'Student completes their profile';
		$triggers['llmsx_course_halfway']    = 'Student reaches 50% of a course';
		return $triggers;
	}
);

// 2. Show the "Select a Course" field for the course-based trigger.
add_filter(
	'llms_engagement_controller_values_course',
	function ( $values ) {
		$values[] = 'llmsx_course_halfway';
		return $values;
	}
);

// 3. Save the chosen course. Core only stores it for its own triggers.
add_action(
	'save_post_llms_engagement',
	function ( $post_id ) {
		$nonce = isset( $_POST['lifterlms_meta_nonce'] ) ? sanitize_text_field( wp_unslash( $_POST['lifterlms_meta_nonce'] ) ) : '';
		if ( ! wp_verify_nonce( $nonce, 'lifterlms_save_data' ) ) {
			return;
		}
		if ( 'llmsx_course_halfway' !== get_post_meta( $post_id, '_llms_trigger_type', true ) ) {
			return;
		}
		$course_id = isset( $_POST['_faux_engagement_trigger_post_course'] ) ? absint( $_POST['_faux_engagement_trigger_post_course'] ) : 0;
		update_post_meta( $post_id, '_llms_engagement_trigger_post', $course_id ? $course_id : 'any' );
	},
	20
);

// 4. Make the engagement engine listen to our action hooks.
add_filter(
	'lifterlms_engagement_actions',
	function ( $hooks ) {
		$hooks[] = 'llmsx_profile_completed';
		$hooks[] = 'llmsx_course_halfway';
		return $hooks;
	}
);

// 5. Translate each hook's arguments into trigger type, user and related post.
add_filter(
	'lifterlms_external_engagement_query_arguments',
	function ( $parsed, $action, $args ) {
		if ( in_array( $action, array( 'llmsx_profile_completed', 'llmsx_course_halfway' ), true ) ) {
			$parsed['trigger_type']    = $action;
			$parsed['user_id']         = absint( $args[0] );
			$parsed['related_post_id'] = isset( $args[1] ) ? absint( $args[1] ) : '';
		}
		return $parsed;
	},
	10,
	3
);

Step 3 is easy to miss. The engagement meta box only saves the related post for core trigger types; for anything else it stores an empty value. An engagement with an empty related post never matches an event that carries a post ID, so without this step a course-based custom trigger silently does nothing.

Your parser runs for every listened hook, so check $action and return $parsed unchanged for anything that is not yours.

Firing the trigger from your own code

Registering a trigger tells LifterLMS what to listen for. You still need to fire the action at the right moment. This example fires the halfway trigger once per course from the core lifterlms_lesson_completed action, and the profile trigger the first time the account form is saved with a phone number:

<?php
// Fire "llmsx_course_halfway" once, the first time a student passes 50%.
add_action(
	'lifterlms_lesson_completed',
	function ( $user_id, $lesson_id ) {
		$lesson    = llms_get_post( $lesson_id );
		$course_id = $lesson ? absint( $lesson->get( 'parent_course' ) ) : 0;
		if ( ! $course_id ) {
			return;
		}

		$flag = 'llmsx_halfway_' . $course_id;
		if ( get_user_meta( $user_id, $flag, true ) ) {
			return;
		}

		$progress = llms_get_student( $user_id )->get_progress( $course_id, 'course', false );
		if ( $progress >= 50 ) {
			update_user_meta( $user_id, $flag, 1 );
			do_action( 'llmsx_course_halfway', $user_id, $course_id );
		}
	},
	20,
	2
);

// Fire "llmsx_profile_completed" once, when the account form is first saved with a phone number.
add_action(
	'lifterlms_user_updated',
	function ( $user_id, $posted_data, $location ) {
		if ( 'account' !== $location || empty( $posted_data['llms_phone'] ) ) {
			return;
		}
		if ( ! get_user_meta( $user_id, 'llmsx_profile_completed', true ) ) {
			update_user_meta( $user_id, 'llmsx_profile_completed', 1 );
			do_action( 'llmsx_profile_completed', $user_id );
		}
	},
	10,
	3
);

Two points matter for reliability:

  • Fire once. Achievements and certificates have a duplicate check, so the same template is not awarded twice for the same user and related post. Engagement emails are only deduplicated when the trigger has a related post, so a trigger without one, like the profile trigger, would send its email every time it fires. Guard your own actions with a flag, as above.
  • Enrollment is checked. When a related post is a course or membership, the handler refuses to award anything if the student is not enrolled in it. That is usually what you want, but it surprises people testing with an admin account.

Events from other systems work the same way. A webhook receiver, a form plugin hook or a scheduled job calls do_action( 'llmsx_your_trigger', $user_id, $post_id ), and the engagement engine does the rest. For inactivity triggers, run a daily Action Scheduler job that finds students who have not logged in for a set number of days and fires your action for each one.

Awarding achievements and certificates directly

Sometimes you do not need an admin-configurable trigger. You know exactly which certificate to award and when: an instructor approves a project, or a student completes a course in an external system. Call the engagement handler directly:

<?php
/**
 * Award a certificate template to a student from code.
 *
 * Runs the same checks as an engagement: the user and template must exist,
 * the template must be published, the student must be enrolled in the
 * related course, and the same certificate is not awarded twice.
 */
function llmsx_award_certificate( $user_id, $template_id, $course_id ) {
	$result = LLMS_Engagement_Handler::handle_certificate(
		array( $user_id, $template_id, $course_id, null )
	);

	if ( is_array( $result ) ) {
		foreach ( $result as $error ) {
			llms_log( $error->get_error_message(), 'llmsx-awards' );
		}
		return false;
	}

	return $result; // An LLMS_User_Certificate instance.
}

LLMS_Engagement_Handler::handle_achievement() takes the same arguments for achievements. The fourth argument is the engagement post ID; null is accepted for awards that do not come from an engagement, as when an admin awards a certificate manually. Awards made this way appear on the student's dashboard and in reporting like any other.

Do not create llms_my_certificate posts with wp_insert_post(). The handler also writes the link row in wp_lifterlms_user_postmeta, runs the duplicate check, copies the template's settings and fires the hooks that send notifications.

Controlling and customising awards

A few more filters are useful once custom triggers are in place:

  • llms_proccess_{$type}_engagement (note the spelling) lets you veto an award or email just before it is processed, for example to skip certificates for staff accounts. Return an array of WP_Error objects to block it.
  • llms_earned_{$type}_dupcheck changes the duplicate rule, for example to allow a yearly recertification of the same template.
  • lifterlms_engagement_types and lifterlms_external_engagement_handler_arguments let you add a new engagement type altogether, such as posting to Slack or tagging a contact in a CRM, handled by your own action.

Our LifterLMS hooks and filters guide covers the wider hook system these sit in, and the code reference on the LifterLMS Developer Hub documents each class.

Troubleshooting

  • Nothing is awarded. Check that the engagement and the certificate or achievement template are both published, the trigger type in the dropdown matches your trigger key exactly, and your parser returns both trigger_type and user_id.
  • Works for "any course" but not a specific one. The related course was not saved. Look at _llms_engagement_trigger_post on the engagement post.
  • Delayed awards never arrive. They run through Action Scheduler. Check LifterLMS > Status > Scheduled Actions for pending or failed lifterlms_engagement_award_* actions and confirm WP-Cron is running.
  • Award blocked during testing. The test user is not enrolled in the related course, or has already earned that template.

Frequently asked questions

Can I trigger an engagement from Zapier or another system?

Yes, with a small receiver: a REST route or webhook endpoint that verifies the request and calls your custom action. The LifterLMS REST API can also enroll students and update progress, which fires core triggers.

Can a custom trigger send an email instead of a certificate?

Yes. The trigger is independent of the engagement type, so the same trigger can send an email, award an achievement or award a certificate, depending on how the engagement is configured.

Will custom triggers survive LifterLMS updates?

They use public filters and actions, not edits to core files, so they survive updates. Keep them in a small custom plugin and retest after major releases.

Next steps

List the moments in your students' journey that deserve recognition but have no built-in trigger, and start with the one that matters most to completion. Build it as a small plugin, test it on staging with a real student account, then expose it to your team through the normal engagement screen.

If you want a set of custom triggers, rewards tied to external systems, or a full gamification layer, our LifterLMS plugin development team builds them to survive updates. Contact us with the moments you want to reward.

Add LifterLMS Expert to your preferred sources

Add lifterlmsexpert.com as a preferred source on Google, or open this article in your AI assistant to use it as a source.

  • Add as a preferred source on Google
Free consultation

Prefer expert help over DIY?

Skip the trial and error. Get specialist LifterLMS help and ship faster.

Talk to a LifterLMS Expert Explore our services

Replies within one business day