Modbot Docs
Integrations

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.

Modbot can give your Patreon patrons their perks, the same way it does for Ko-fi. When somebody pledges, Modbot gives them the Discord role and the VRChat group role you chose for their tier and sends them a thank-you message. When the pledge ends, or a charge is declined, Modbot takes the roles back.

Patreon calls Modbot when a pledge changes: that is the webhook, and it is all Modbot needs to count patrons. Your Modbot must be reachable from the internet at the Public address in Settings, Server, because Patreon sends each message to it.

Patreon's message does not say which Discord account a patron is. For that Modbot also asks Patreon, with a Patreon client you register once (see Register a Patreon client). With it, Modbot looks up each new patron's Discord account, and once a day reads every current patron, which brings in patrons from before Modbot and anything a webhook that never arrived left out.

You set it up in Settings, Patreon, and look after the tiers and people on the Supporters page (Community), which lists Ko-fi and Patreon supporters together and shows which site each came from. Both need Change settings.

Set it up

  1. In Patreon's developer portal, open Webhooks and add a webhook for your campaign.
  2. Copy the Webhook address shown in Modbot under Settings, Patreon into the webhook's URI. If it says Public address not set, set the public address first.
  3. Pick these triggers: members:pledge:create, members:pledge:update, members:pledge:delete, members:create, members:update and members:delete. Patreon sends members:update when a charge goes through or fails, so that one matters most.
  4. Save the webhook and copy its secret. In Modbot, paste it into Webhook secret and click Save. The page shows Webhook secret: Saved, and never shows it again. It is kept encrypted.
  5. Turn the Patreon switch on. Until it is on, the address answers as if it were not there.
  6. Patreon has a button to send a test message. Use it, then look at the Supporters page.

Patreon signs every message with the secret. A message with no signature or a wrong one is refused, and nothing in it is read.

These steps come from Patreon's published webhook documentation and have not been checked against Patreon's current screens.

Register a Patreon client

  1. Signed in to Patreon as the creator, open Patreon's developer portal and go to Clients & API Keys.
  2. Click Create Client. Give it a name and a description, set the API version to 2, and give the redirect URI your Modbot's public address. Modbot never sends anybody there; Patreon only asks for one.
  3. Save it. Patreon shows four keys: Client ID, Client Secret, Creator's Access Token and Creator's Refresh Token.
  4. In Modbot, under Settings, Patreon, Patreon client, paste each into its box and click Save. The page shows Saved beside each and never shows them again. They are kept encrypted.
  5. Within half a minute Modbot reads your patrons for the first time. Last catch-up shows when it finished, or Problem says why it could not.

The creator's tokens read your own campaign. Modbot uses them for four requests only: a new access token (below), the list of your campaigns (it keeps the first one's id), a campaign's members with their tiers and the apps each connected to Patreon, and one member at a time. It never changes anything on Patreon.

Patreon's access token runs out after about a month. Modbot asks Patreon for a new one with the refresh token a few days before it does, and saves the new pair; the first time, it does so at once, because the age of a pasted token is not known. Saving a new key starts over: the campaign is found again and the catch-up runs at once.

Modbot sends Patreon at most one request a second. If Patreon answers that Modbot is asking too much, Modbot does not ask again: it stops for at least 15 minutes (longer if Patreon says so), shows Patreon is limiting Modbot's requests under Problem, and tries again after that. If a key is refused, Problem says which kind, and the catch-up tries again the next day, or as soon as you save a new key.

These steps come from Patreon's published API documentation and have not been checked against Patreon's current screens.

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 patron is at it, with no roles. Pick its roles to start giving them. Its name is the tier's title on Patreon, and it is renamed here if you rename it there.
  • A patron who is entitled to several tiers is counted at the one that costs the most.
  • A patron who is entitled to no tier is not counted. One who was counted and then loses every tier is ended, like a pledge that ended.
  • 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.

The thank-you message is the one under Settings, Ko-fi. It is the same for both sites.

When the roles come off

What Patreon saysWhat Modbot does
The patron is activeGives the tier's roles. They last for the month the last paid charge covers; until Patreon charges them, a month from when the pledge was first seen.
A charge was declinedThe roles stay until the number of days set under Settings, Patreon has passed since the declined charge, then come off.
The pledge ended (deleted, or a former patron), or the patron lost every tierThe roles stay until the paid month is up and the same number of days more, then come off.

Under Settings, Patreon, Roles come off sets that number of days: 0 to 365, with 3 to start. Never keeps the roles Modbot gave for good; the supporter still shows as Ended on the Supporters page, and 0 takes the roles off the moment the paid month is up. The setting is Patreon's own; Ko-fi has its own.

A later message that says the patron is active again gives the roles back, and they are thanked again. Cancelling a free or gifted membership sends no pledge-deleted message.

Modbot only takes back roles it gave itself. A role you gave by hand is never touched.

Matching a patron to their Discord account

Roles need a Discord account, and Patreon's message does not say which one. A new patron is looked up within half a minute: Modbot asks Patreon for the apps the patron connected to their Patreon account, and takes their Discord account from it. The daily catch-up asks again for every patron who still has none, so a patron who connects Discord later is matched by the next one.

Patreon only reports a Discord account for a patron who connected one to their Patreon account. Anybody else, and anybody whose account another supporter already has, shows as Not matched on the Supporters page until staff press Match, search for their name in the Discord server and press Match again. Their later charges match by themselves. A patron is told from another by Patreon's member id, which does not change when they change their email address.

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.

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 Patreon or Ko-fi is on. A bot added earlier has to be added again from the new link.

What Modbot keeps

For each patron: the name they pledged under, their tier, their Discord account once matched, when they were charged, which roles Modbot gave, and Patreon's member id with the date of each charge. Their email address is never read or stored; of what the patron connected to Patreon, only the Discord account is read. For the catch-up: your campaign's id, when your access token runs out, and when the last catch-up finished. The webhook secret and the four client keys are kept encrypted and never shown again. The only requests Modbot sends to Patreon carry your own keys and tokens, or a campaign's or a member's id. Nothing is sent to Modbot Cloud. A purge deletes the supporter matched to that Discord account, with their payments; no retention window touches it. A patron who is still pledging comes back at the next daily catch-up (see Purge).

Modbot is not endorsed by or affiliated with VRChat Inc. or Discord Inc. VRChat is a trademark of VRChat Inc. Discord is a trademark of Discord Inc. SteamVR is a trademark of Valve Corporation. Windows is a trademark of Microsoft Corporation. Docker is a trademark of Docker, Inc. PostgreSQL is a trademark of the PostgreSQL Community Association of Canada. Railway is a trademark of Railway Corp. Other names are trademarks of their respective owners; see Legal. Modbot and its logo are trademarks of the Modbot project. Open source under AGPL-3.0.

On this page