Set up MeritForge in Microsoft Teams
MeritForge for Microsoft Teams lets people give Sparks without leaving Teams, celebrates Sparks, Badges, and work anniversaries in a channel, and tells people in Teams when they are recognized. Balances, company values, and every recognition rule stay in MeritForge.
Setting it up usually involves two people: a MeritForge Owner or Admin, and whoever manages Microsoft Teams in your company (often IT). If that is not the same person, send them this page.
Before you start
- Your company has a MeritForge organization, and you are one of its Owners or Admins.
- Someone with Teams admin rights can upload apps in the Teams admin center.
- Until MeritForge is listed in the Teams Store, the app is uploaded as a custom app, so custom apps must be allowed in your organization (Teams admin center → Teams apps → Manage apps → Actions → Org-wide app settings).
MeritForge asks for no Microsoft Graph permissions and no admin consent. It works through its Teams bot and only sees the teams where the app is installed.
1. Download the MeritForge app package
MeritForge Owner or Admin. In MeritForge, open Admin → Organization → Integrations → Microsoft Teams and select Download Teams app package. You get a small zip file. Send it to your Teams admin if that is someone else.
2. Upload the app to Teams
Teams admin. In the Teams admin center, go to Teams apps → Manage apps → Upload new app, and choose the zip file. Check that MeritForge is listed as Allowed.
3. Install it for everyone
Teams admin. Still in Manage apps, select MeritForge → Edit installs → Everyone → Apply. (Organizations that have not moved to Microsoft’s app-centric management use Teams apps → Setup policies → Global → Installed apps → Add apps instead.)
This step matters: making the app available only lets people add it themselves. Installing it puts Give a Spark in everyone’s Teams without them doing anything. It can take a few hours to reach everyone; restarting Teams helps.
Then add the app to the teams where you want recognition announced: Manage apps → MeritForge → Add to team, or from the team itself in Teams.
4. Connect your Microsoft tenant to MeritForge
- MeritForge Owner or Admin: on the same Microsoft Teams page in MeritForge, select Create connection code. The code works once and expires after 30 minutes.
- Anyone in your company with Teams: in Teams, open Apps → Built for your org → MeritForge → Open. This opens a private chat with MeritForge. Send the message shown in MeritForge, for example
connect ABCD-1234. - MeritForge answers “Connected!” and the page in MeritForge shows your tenant.
For security, the code only works in a private chat with MeritForge; codes posted in a channel are ignored.
5. Connect your people
MeritForge matches people automatically by email: when the app is added to a team, and again every day, members whose Teams email matches their MeritForge email are connected. To run it right away, select Sync members now on the Microsoft Teams page.
Someone whose MeritForge email is different (for example a personal address) connects once, in either of these ways:
- In Teams, they open Give a Spark and select Connect my account.
- Or they open the private chat with MeritForge (Apps → Built for your org → MeritForge → Open), send the word
link, open the link MeritForge replies with, sign in to MeritForge, and confirm. This only works in the private chat, not in a channel.
They get an email confirming the connection.
6. Choose where to celebrate (optional)
On the Microsoft Teams page in MeritForge, turn on Announcements in Teams and choose a channel. Every Spark and Badge is posted there, mentioning the people involved. Work anniversaries are posted too when your Jubilee settings publish them in the Great Hall.
Using MeritForge in Teams
- Give a Spark from the message box (+ → MeritForge) or from any message’s … menu.
- Or type
spark(orchispa) to MeritForge in its private chat, or@MeritForge spark @Ana @Luisin a channel to start with those people already chosen. - People get a private message in Teams when they receive Sparks, and a reminder before their monthly Sparks run out. Each person can turn these off in MeritForge → Settings → Connected apps.
Troubleshooting
| What you see | What to do |
|---|---|
| Someone doesn’t see MeritForge under + or in the … menu | The app is not installed for them yet. Check step 3 (Edit installs → Everyone), wait a few hours, and restart Teams. They can also add it themselves from Apps → Built for your org. |
| Give a Spark shows “Something went wrong” right after an app update | Teams kept an old copy. Remove MeritForge where it was added (the team, or the person’s apps) and add it again. |
| Someone gets MeritForge’s messages but can’t give Sparks | Same as the first row: the bot can message everyone in teams where it is installed, but Give a Spark needs the app installed for that person. |
| “Connect your Teams account” when giving a Spark | Their emails don’t match. They select Connect my account in that dialog, or send the word link in their private chat with MeritForge and confirm on the page that opens (step 5). |
| MeritForge ignores the connection code | Send it in the private chat with MeritForge, not in a channel, and use a code less than 30 minutes old. |
| Nothing is posted in the announcement channel | Check that MeritForge is still added to that team; the Microsoft Teams page in MeritForge shows the last announcement problem. |
Updating the app
When MeritForge adds Teams features, download the app package again (step 1) and upload it in the Teams admin center as an update of the existing MeritForge app. If Give a Spark stops working afterwards, see the troubleshooting table.
Disconnecting
On the Microsoft Teams page in MeritForge, select Disconnect Teams. MeritForge stops acting for your tenant and every member’s Teams connection ends; Sparks already given stay in MeritForge. To remove the app from Teams as well, a Teams admin removes it in Manage apps.
Need help?
Contact MeritForge support with your organization name and what you see. See the Privacy Policy for the Microsoft Teams data MeritForge uses.