Discord Platform Integration

The Gova Discord integration allows for automated content moderation, user identity linking, and remote bot management. This integration is handled through a combination of OAuth2 flows and specialized action handlers.

Authentication and OAuth

Gova uses a two-pronged OAuth approach to manage both user identities and bot permissions within Discord guilds.

User Identity Linking

To associate a Discord account with a Gova user profile, the system utilizes the standard Discord OAuth2 flow. This grants access to the user's identity and the list of guilds they manage.

• Endpoint: GET /auth/discord/oauth
• Functionality: Handles the callback from Discord, encrypts the resulting OAuth payload, and stores it against the user record.
• Data Persistence: The payload includes access_token, refresh_token, and expiry timestamps, all stored securely using AES-GCM encryption.

Bot Installation

To moderate a server, the Gova bot must be invited to the guild with specific permissions.

• Endpoint: GET /auth/discord/oauth/bot
• Functionality: A dedicated callback for the bot-add flow. This ensures the bot is correctly associated with the user's account and redirects the user back to their connections dashboard.

Guild and Channel Management

Once a user has linked their Discord account, Gova provides tools to discover and select the specific environments to moderate.

Fetching Guilds

Retrieve a list of Discord servers where the authenticated user has administrative permissions.

• Endpoint: GET /connections/discord/guilds
• Returns: A list of Guild objects containing id, name, and icon.

Fetching Channels

Retrieve the text channels available within a specific guild for fine-grained moderation targeting.

• Endpoint: GET /connections/discord/{guild_id}/channels
• Returns: A list of GuildChannel objects.

Discord Moderator Configuration

When creating a moderator via POST /moderators/, the conf (configuration) object for Discord must specify how the AI agent behaves and which thresholds trigger specific actions.

Configuration Schema

{
  "guild_id": "123456789012345678",
  "enabled_channels": ["112233445566778899"],
  "actions": {
    "reply": { "enabled": true, "threshold": 0.5 },
    "timeout": { "enabled": true, "threshold": 0.8, "duration_seconds": 3600 },
    "kick": { "enabled": false, "threshold": 0.95 }
  },
  "guidelines": "No toxicity, no spamming crypto links."
}

Action Execution

Gova supports three primary automated actions on the Discord platform. These actions are triggered based on the AI's severity score and require manual approval if configured for an "Awaiting Approval" state.

Supported Action Types

| Action Type | Description | Required Parameters | | :--- | :--- | :--- | | REPLY | Sends a public warning or response to the offender. | content (string) | | TIMEOUT | Restricts the user from speaking for a set duration. | duration (seconds) | | KICK | Removes the user from the guild. | reason (string) |

Approving an Action

To execute a pending moderation action, use the approval endpoint:

• Endpoint: POST /actions/{action_id}/approve
• Logic: The system retrieves the DiscordMessageContext, initializes the DiscordHandler, and executes the specific API call to Discord (e.g., handle_timeout).

Message Context and Review

The ReviewAgent utilizes the DiscordMessageContext to understand the environment of a violation. This context is critical for the AI to determine the "Severity Score."

Discord Message Context Structure

When a message is ingested, Gova captures the following metadata for the AI:

• content: The raw text of the message.
• author_id: The Discord Snowflake ID of the sender.
• channel_id: The Snowflake ID of the channel.
• guild_id: The Snowflake ID of the server.
• timestamp: When the message was sent.

The ReviewAgent processes this context against the server's guidelines and channel_summary to produce a ReviewAgentOutput, which includes the suggested action and a reason.

# Example Review Agent Output for Discord
{
    "severity_score": 0.85,
    "reason": "User is repeatedly using banned slurs despite previous warnings.",
    "action": {
        "type": "TIMEOUT",
        "params": { "duration": 3600 }
    }
}