Discord integration¶

The PulseLMS Discord bot connects a Discord community to your PulseLMS organization. It links accounts and keeps learning and Discord in sync in both directions:

Account linking: members connect their Discord account to PulseLMS.
Role → course: a Discord role you map to a course auto-enrolls linked members.
Course → role (rewards): completing a course grants a Discord role.
Announcements: new courses and completions post to a channel.
Self-service: members browse the catalog, enroll, check XP, and verify certificates from Discord.
Onboarding & reminders: welcome new members, and DM them before a certification expires.

Everything runs through the scoped partner API, so the bot only ever sees your organization's data.

What the bot changes

By default the bot only reads Discord roles and writes enrollments to PulseLMS. If you configure completion rewards, it also grants Discord roles, which requires the Manage Roles permission (see below). Enrollment sync is additive: gaining a role grants course access, but removing a role never un-enrolls anyone (that would erase their progress).

Requirements¶

The discord and api_access feature flags enabled (Settings → Features). Gamification commands (/leaderboard, /me) also need the gamification flag.
An API key with the read and enroll:write scopes.
Manage Server permission to add the bot; Manage Roles on the bot if you use completion rewards.

Step 1: Create an API key¶

Go to Settings → API keys.
Click Create key, name it, and grant the read and enroll:write scopes.
Copy the key; it's shown once. It looks like pls_<prefix>_<secret>.

Step 2: Add the bot¶

Go to Settings → Discord in PulseLMS and click Add to Discord. The link there already carries the right scopes and permissions, so there is nothing to assemble by hand.

That screen is also where you check the connection afterwards: it shows which server is linked, whether the bot has checked in recently, how many members have linked their accounts, and the role mappings.

Role hierarchy for rewards

To grant a reward role, the bot's own role must sit above that role in Server Settings → Roles. Discord refuses to assign a role higher than the bot's highest role. The /reward add command warns you if this isn't set up.

Step 3: Connect the server¶

An administrator runs:

/setup api_key:pls_your_key_here

The bot verifies the key and confirms which organization it's bound to. Re-run /setup any time to rotate the key or move to a different organization.

Step 4: Map roles and rewards¶

Role → course (having the role enrolls you):

/map list: review the role mappings currently configured.
/map courses: list published courses and their IDs.

Mappings are managed in PulseLMS

Role mappings live in Settings → Discord, alongside everything else about your organization, so you can see and change them without opening Discord. /map add and /map remove now point you there.

Course → role reward (completing the course grants the role):

/reward add course_id:<uuid> role:@Role
/reward list / /reward remove …

When a linked member completes a rewarded course, the bot grants the role and (if configured) posts a celebration.

Step 5: Members link their accounts¶

Members can link from either end, and both produce the same result:

From PulseLMS: My account → Discord → Link with Discord. Discord asks them to approve, and they come straight back. This is the route to point people at: every member can reach My account, and there is nothing to copy or paste.
From Discord: run /link and click Link my account to sign in to PulseLMS and confirm. Codes expire after 30 minutes.

Either way the member approves the connection themselves, so nobody can link an account that isn't theirs. Once linked, their roles enroll them, completions reward them, and the self-service commands work.

Announcements¶

Point completions and new-course posts at a channel:

/announce set channel:#announcements
/announce off / /announce status

The bot posts a new course embed when a course is published, and a completion embed when a linked member finishes a course. It won't retroactively announce content that already existed when you connected the server.

Onboarding¶

/onboarding set course_id:<uuid>: every linked member is auto-enrolled in this course. /onboarding off to disable.
/onboarding welcome enabled:true|false: DM new members a link prompt when they join (on by default).

Certificate reminders¶

The bot automatically DMs linked members ~30 days before a certificate expires, so they can re-certify in time. No setup required beyond linking; it uses each course's validity period. Each expiring certificate is nudged once.

Command reference¶

Members (anyone):

Command	What it does
`/link` · `/unlink`	Connect or disconnect your PulseLMS account.
`/sync`	Enroll yourself in courses for the roles you hold.
`/courses`	Your enrollments and their status.
`/catalog`	Browse courses; Enroll buttons for open courses.
`/enroll course_id:`	Self-enroll in an open course.
`/leaderboard`	Top learners by XP.
`/me`	Your XP, level, and badges.
`/verify serial:`	Verify a certificate by its serial.
`/status`	Connection health.

Admins:

Command	What it does
`/setup`	Connect the server to your organization.
`/map`	Review role → course maps (managed in Settings → Discord).
`/reward`	Manage course-completion → role rewards.
`/announce`	Set the announcements channel.
`/onboarding`	Onboarding course + welcome DM.
`/assign member: course_id:`	Assign a course to a member.

How syncing works¶

Role gained → enrolled. On a role change (or /sync) the member is enrolled in every mapped course they now qualify for.
Course completed → rewarded. A background check (every few minutes) grants reward roles and posts completions for linked members.
Additive only. Losing a role never removes an enrollment. To revoke access, unenroll the learner in PulseLMS directly.
Idempotent. Nothing is enrolled, granted, or announced twice.
Self-enroll is respected. /enroll and /catalog only let members into courses marked open for self-enrollment; admins can /assign any course.

Troubleshooting¶

Symptom	Cause & fix
`/setup` can't verify the key	Wrong key/URL or missing `read` scope. Create a fresh key with `read` + `enroll:write`.
`/setup` says Discord is off	Enable the `discord` flag in Settings → Features.
Reward role isn't granted	The bot lacks Manage Roles, or its role is below the reward role. Fix in Server Settings → Roles.
A member's roles don't enroll them	They haven't linked their account (My account → Discord, or `/link`), or no mapping covers the role (check Settings → Discord).
`/leaderboard` or `/me` says "not enabled"	Turn on the `gamification` flag.
A command says you need Administrator	Expected. `/setup`, `/map`, `/reward`, `/announce`, `/assign`, `/onboarding` and `/status` require the Administrator permission in the server, checked by the bot itself and not only by Discord's default. Loosening the command in Server Settings → Integrations no longer grants access.
Announcements/completions don't post	Set a channel with `/announce set`, and check the bot can Send Messages there.
Removing a role didn't remove access	Expected: sync is additive. Unenroll in PulseLMS.