Developer Portal
App Fundamentals

ModVC Bots

Bots interact with the ModVC platform using the same interfaces as regular users. They can join servers, read text channels, and manage members.

Adding a Bot to a Server

Bots do not join servers on their own. A user with the Manage Server permission must authorize the bot via an OAuth2 link.

You can generate this link in the Developer Portal. It looks like this:
https://modvc.org/app/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=SEND_MESSAGES,KICK_MEMBERS

Authentication

All API requests made by a bot must include the Authorization: Bot <token> header. Do not share this token. If someone gets your token, they control your bot.

GET /api/bot?serverId=123&type=members
Authorization: Bot m_bot_xyz123...

Bot Permissions

When your bot joins a server, it receives a role containing the permissions requested in the OAuth2 URL. If your bot tries to do something it lacks permission for (like kicking a user without the KICK_MEMBERS permission), the API returns a 403 error.

Webhooks & Interactions

If you set an Interactions Endpoint URL in the Developer Portal, ModVC will send HTTP POST requests to your server whenever a user interacts with your bot.

  • type 2 (APPLICATION_COMMAND): Triggered when a user runs a Slash Command.
  • type 3 (MESSAGE_COMPONENT): Triggered when a user clicks a button attached to one of your bot's messages.

Your webhook must respond with a 200 OK status. You can respond synchronously with JSON to immediately trigger UI actions (like acknowledging a button click or sending a reply).