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. Settings → Discord repeats this warning beside the reward list, but nothing can check it for you in advance: Discord only refuses at the moment the bot tries to grant the role.

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): set these up in Settings → Discord, under Courses that grant a role.

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

Rewards are managed in PulseLMS too

/reward add, /reward remove and /reward list no longer change or show anything. They reply with a link to your Settings page.

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¶

Announcements are configured in PulseLMS, under Settings → Discord:

Announcement channel: where the bot posts. Only channels the bot can post an embed into are listed, and Send a test message proves it can actually post there before you rely on it. Being able to pick a channel is not the same as being allowed to post in it, because Discord permissions are per channel.
What to announce: independent switches for Course completions, New courses, Certificate reminders and Welcome new members.

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.

/announce no longer sets anything

Every /announce subcommand, status included, replies with a link to your Settings page.

Onboarding¶

Also in Settings → Discord:

Onboarding course: every member who links their account is enrolled in this course automatically. Set it to None to turn it off.
Welcome new members: DM a link prompt to everyone who joins the server. This is on by default. Turn it off if the server is a community or a showcase rather than a training space, or people who joined for something else will be asked to link an LMS account they have no use for.

/onboarding no longer sets anything

/onboarding set, off, welcome and status all reply with a link to your Settings page instead of changing or reporting the setting.

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`	Points at Settings → Discord; changes nothing.
`/announce`	Points at Settings → Discord; changes nothing.
`/onboarding`	Points at Settings → Discord; changes nothing.
`/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.