Ko-fi supporters
Giving supporters a Discord role and a VRChat group role for the tier they pay at, thanking them, and taking the roles back when a monthly payment stops.
Modbot can give your Ko-fi supporters their perks. When somebody pays monthly, Modbot gives them the Discord role and the VRChat group role you chose for their tier and sends them a thank-you message. When a monthly payment does not come, Modbot takes the roles back.
Ko-fi calls Modbot, not the other way round. Modbot never signs in to Ko-fi and never asks Ko-fi for anything, so the only thing it needs from Ko-fi is a verification token. Your Modbot must be reachable from the internet at the Public address in Settings, Server, because Ko-fi sends each payment to it.
You set it up in Settings, Ko-fi, and look after the tiers and people on the Supporters page (Community). Both need Change settings.
Set it up
- In Ko-fi, open your page's settings, API, and find the Webhooks section. Copy the Verification Token.
- In Modbot, go to Settings, Ko-fi. Paste the token into Verification token and click Save. The page shows Verification token: Saved, and never shows it again. It is kept encrypted.
- Copy the Webhook address shown on that page into Ko-fi's Webhook URL box and save it there. The address is built from your Modbot's public address. If it says Public address not set, set the public address first.
- Turn the Ko-fi switch on. Until it is on, the address answers as if it were not there.
- Ko-fi has a button to send a test message. Use it, then look at the Supporters page.
A message with the wrong token is refused. Nothing else about a message is trusted until its token matches.
Ko-fi's field names (the tier's name, the kind of payment, the Discord account) come from published descriptions of the webhook, and the Discord account field has not been checked against a live payload from Ko-fi. If supporters you know are in your server show up as Not matched, the matching below still works.
Tiers and roles
On the Supporters page, each tier has a Discord role and a VRChat group role. Either can be left empty.
- A tier appears by itself the first time a payment names it, with no roles. Pick its roles to start giving them. You can also add a tier by hand with the name Ko-fi uses for it.
- Changing a tier's roles applies to everyone on it within a minute.
- A tier cannot be deleted while paid-up supporters are on it.
Only a monthly payment counts. A one-off donation, a shop order or a commission is answered and ignored.
When the roles come off
Ko-fi sends nothing when a monthly payment stops. So Modbot counts instead. A payment covers a month. If the next one has not come the set number of days after that month is up, the supporter's state becomes Ended and Modbot takes back the roles it gave. The page shows Roles end for each supporter. A payment that arrives late, after the roles came off, gives them back.
Settings, Ko-fi, Roles come off sets the number of days: 0 to 365, with 3 to start. 0 takes the roles off the moment the paid month is up. Never keeps the roles Modbot gave for good; the supporter still shows as Ended on the Supporters page. The setting is Ko-fi's own; Patreon has its own.
Modbot only takes back roles it gave itself. A role you gave by hand is never touched.
Matching a supporter to their Discord account
Roles need a Discord account. Modbot finds it three ways:
- Ko-fi's Discord link. A supporter who connected their Discord account in Ko-fi is matched as soon as they pay.
- A Modbot code. While Ko-fi is on, anybody in your Discord server can type
/supporter-code. Modbot answers privately, so only they see it, with a short code such asK7Q2MX: six capital letters and digits, with no look-alikes (no 0, O, 1, I or L). They paste the code into the message box on Ko-fi when they pay. When a payment has no Discord link and its message holds a code Modbot gave out, the supporter is matched to that code's Discord account. The code can be anywhere in the message, in capitals or not, but it must stand as a word of its own. Asking again gives the same code. Once a supporter is matched, their later monthly payments match by themselves. - The code on their receipt. Anybody else shows as Not matched. They give staff the transaction id from their Ko-fi receipt. Type it into the search box on the Supporters page to find them, press Match, search for their name in the Discord server and press Match again.
A Ko-fi Discord link wins over a code in the message. A code only matches a supporter who has no account yet, and never an account another supporter already has. Moving a supporter to another account is done by staff with Match, and the roles Modbot gave the old account are taken back from it.
A payment from a new email address with a code is a new supporter, and shows as Not matched while the account still belongs to the supporter of the old email; staff match it with Match.
/supporter-code is there only while the Ko-fi switch in Settings is on, and is not on the Discord
Commands card.
If a supporter marks their message as private on Ko-fi, Ko-fi may leave the message out of what it sends Modbot. That has not been checked. Modbot copes with a missing message: the supporter simply shows as Not matched, and staff match them by the receipt code. Modbot only looks for a code in the message and never keeps the message.
The VRChat group role goes to the VRChat account linked to their Discord account (see Account links). A supporter with no linked VRChat account shows No linked VRChat; their Discord role is given, and the VRChat role follows when they link.
The thank-you message
The message is a direct message on Discord, sent once, the first time a supporter has a Discord
account and a tier. It is set in Settings, Ko-fi. {name} becomes their name and {tier}
the tier's name. Leave it empty to send none. A supporter who changes tier is thanked again. If
somebody does not accept direct messages from the server, the page shows that on their row.
Permissions
Giving a Discord role needs the Manage Roles permission, and the bot's own role must sit above the roles it gives. The VRChat side uses Modbot's own VRChat login, which needs the group permission to give and take away roles; a refusal from VRChat is shown on the supporter's row. The Bot invite link asks for Manage Roles while Ko-fi or Patreon is on. A bot added earlier has to be added again from the new link.
A role the bot cannot give is marked in the picker, and a refusal is shown on the supporter's row.
What Modbot keeps
For each supporter: the name they paid under, their tier, their Discord account, when they paid, which
roles Modbot gave, and the transaction ids of their payments. For each person who typed /supporter-code:
their Discord account and the code Modbot gave them. Their email address is never stored:
Modbot keeps only a one-way fingerprint of it, to tell one person's payments from another's. The payment's
message is read for a code and not kept. Nothing is sent to Modbot Cloud. A purge
deletes the supporter matched to that Discord account, with their payments, and their code; no retention
window touches it.
Twitch
Letting Modbot see when your group's Twitch channel is live, show it to your team, link each stream to the event it was for, and post "We're live on Twitch".
Patreon supporters
Giving patrons a Discord role and a VRChat group role for the tier they pledge at, thanking them, and taking the roles back when a pledge ends or a charge is declined.