Getting Started with GuildPilot

GuildPilot is a professional Discord automation platform for businesses and communities. It gives your Discord server structured ticketing, workflow automations, AI-powered support, and a centralized dashboard to manage everything.

The typical setup path takes about five minutes:

1. Sign in with Discord at /login. GuildPilot creates your workspace automatically.
2. Link a Discord server from the Servers page. You need the guild ID (found in Discord settings under Advanced > Developer Mode) and the server name.
3. Invite the bot using the invite link on the Servers page. Grant bot and application command permissions.
4. Post a ticket panel by running /ticket-panel in a Discord channel. Members can now open tickets.
5. Add automations as needed from the Automations page. Optionally enable the AI assistant on the Business plan.

Discord Login

GuildPilot uses Discord OAuth for authentication. There are no separate email or password accounts. When you click "Continue with Discord", you are redirected to Discord's authorization page where you grant GuildPilot permission to read your basic profile (username, avatar, and user ID).

On first login, GuildPilot creates:

• A user record tied to your Discord identity.
• A workspace (tenant) on the Free plan, owned by your account.
• A session stored as a cookie that expires after 30 days.

No additional personal information is collected during sign-in. Billing contact details (name, email, address) are only collected when you upgrade to a paid plan via the Billing page.

GuildPilot supports two OAuth flows depending on the server configuration. The code grant flow is preferred and exchanges a short-lived authorization code for an access token server-side. The implicit flow is used as a fallback when a client secret is not configured; the access token is returned in the URL fragment and forwarded to the server via JavaScript.

To sign out, click "Sign Out" in the sidebar. This clears your session on both the client and server.

Bot Installation

The GuildPilot Discord bot handles ticket creation, transcript archival, and slash command interactions inside your Discord server. To install it:

1. Go to the Servers page in the GuildPilot dashboard.
2. Click "Invite GuildPilot Bot". This opens Discord's bot authorization flow with the required permissions pre-selected.
3. Select the target server in the Discord dialog and confirm. The bot needs permissions to manage channels, send messages, embed links, read message history, and use application commands.
4. Return to GuildPilot and enter the Guild ID and server name in the link form, then click "Save linked server".

Finding your Guild ID: In Discord, go to User Settings → Advanced → enable Developer Mode. Then right-click your server name in the sidebar and choose "Copy Server ID". This is a numeric string like 1234567890123456.

Once linked, the server will appear in the Servers table with an "Active" status. You can link multiple servers to one workspace (limits depend on your plan: 1 for Free, up to 5 for Pro, unlimited for Business).

Ticket System

GuildPilot provides a structured ticketing system that operates entirely within Discord, with web-side visibility for management and auditing.

Creating a Ticket Panel

Run /ticket-panel in any Discord channel where you want members to be able to open tickets. The bot posts an embed message with an "Open Ticket" button. You can have multiple panels in different channels if needed.

Opening a Ticket

When a member clicks the button, GuildPilot:

• Creates a private text channel under a "Support Tickets" category (created automatically if it does not exist).
• Sets permissions so only the ticket opener and the bot can see the channel. Your support team members will need a role that has visibility into the category.
• Posts an opening message with the ticket ID and a "Close Ticket" button.
• Records the ticket in the database with status open and priority normal.

Closing a Ticket

A team member can close a ticket by clicking the "Close Ticket" button in the channel or by running /ticket-close. On close, GuildPilot:

• Fetches the last 100 messages from the channel.
• Saves them as a transcript text file on the server.
• Records the transcript file path in the database.
• Updates the ticket status to closed with a timestamp.
• Deletes the Discord channel after archiving.

Web Dashboard

The Tickets page in the GuildPilot web app shows all tickets for your workspace, including status, priority, guild, opener, creation date, close date, and transcript count. Use this view for auditing conversations, reviewing support quality, and tracking volume trends.

Automations

Automations let you define trigger-action chains that execute automatically when specific events occur in your linked Discord servers. Each automation has three components:

• Trigger: The event that starts the automation (e.g., ticket_created, member_joined).
• Conditions: Optional filters that must match for the automation to proceed (e.g., priority = high). If all conditions pass, the actions execute.
• Actions: The steps to execute in order (e.g., mention a role, send a message, assign a role).

Supported Triggers

• ticket_created — fires when a new ticket is opened.
• ticket_closed — fires when a ticket is resolved and archived.
• button_clicked — fires when a custom button interaction is detected.
• member_joined — fires when a new member joins a linked server.
• member_left — fires when a member leaves a linked server.
• role_assigned — fires when a role is added to a member.
• message_received — fires on incoming messages (use conditions to filter).

Creating an Automation

Use the Automations page in the dashboard. Enter a descriptive name, select a trigger, optionally add conditions (one per line in the conditions textarea), and define actions (one per line). Automations can be enabled or disabled individually without deleting them.

Automation Storage

Automations are stored as JSON definitions in the database. The definition_json column contains the full definition including conditions and actions arrays. You can also manage automations programmatically via the API endpoint POST /api/automations?action=save.

Best Practices

• Start with a single automation for your most repetitive workflow (e.g., notifying support on new tickets).
• Use conditions to avoid false positives — an automation that fires on every message will create noise.
• Name automations descriptively so your team understands what each one does without reading the definition.
• Disable automations temporarily rather than deleting them if you want to pause a workflow.

AI Assistant

The AI ticket assistant is a Business-plan feature that automatically responds to questions in ticket channels using content from your knowledgebases.

Configuration

Go to the AI Assistant page in the dashboard to configure:

• Enable / Disable: Toggle the assistant on or off for your workspace.
• Confidence threshold: A decimal between 0 and 1 (default 0.72). The AI only posts an answer if its confidence exceeds this value. Lower values mean the AI responds more often but with less certainty.
• Support role ID: The Discord role ID to mention when the AI escalates to a human. Find this in Discord by enabling Developer Mode and right-clicking the role.
• Fallback message: The text sent in the ticket channel when the AI is not confident enough to answer automatically.

Knowledgebases

Create knowledgebases from the AI Assistant page. Each knowledgebase is a named collection of reference material that the AI searches when formulating responses. Knowledgebases have three statuses:

• active — available for AI queries.
• building — being indexed or updated.
• disabled — excluded from AI queries.

Response Flow

When a ticket is opened and AI is enabled: the assistant searches your active knowledgebases for relevant content, generates a response, and checks its confidence score against your threshold. If confidence is sufficient, it posts the answer directly in the ticket channel. If not, it posts the fallback message and mentions your support role so a human can follow up.

Tips

• Keep knowledgebase content accurate and up to date. The AI is only as good as its reference material.
• Start with a higher confidence threshold (0.80+) and lower it gradually as you verify the quality of responses.
• Write a clear fallback message that sets expectations — users should know a human will follow up.

Billing and Onboarding

GuildPilot keeps the sign-in experience frictionless by using Discord-only authentication. No email, password, or personal information is collected during basic login.

When a workspace is ready to upgrade to a paid plan (Pro or Business), the Billing page collects the business details needed for invoicing:

• Billing contact name
• Billing email address
• Business address (line 1, line 2, city, state, postal code, country)

This information is stored on the tenant record and timestamped when first collected. It supports future payment processing integration without burdening free-tier users with unnecessary forms.

Plans

• Free: 1 server, basic tickets, transcripts, event logging, community support.
• Pro ($12/mo): Up to 5 servers, automation engine, custom templates, role management, priority support.
• Business ($39/mo): Unlimited servers, AI ticket assistant, knowledgebase, REST API access, custom integrations, dedicated support.

API Reference

GuildPilot exposes a REST API for programmatic access to all core features. All endpoints accept and return JSON. CORS headers are included for cross-origin access.

Authentication

• GET /api/auth?action=discord_start — Redirects to Discord OAuth authorization page.
• GET /api/auth?action=discord_callback&code=...&state=... — Handles code grant OAuth callback, creates session.
• POST /api/auth?action=discord_implicit_complete — Completes implicit flow. Body: {"access_token": "...", "state": "..."}
• GET /api/auth?action=logout — Clears session and redirects to login page.

Tickets

• POST /api/tickets?action=create — Create a ticket. Body: {"tenant_id", "guild_id", "channel_id", "opener_user_id"}. Returns {"ok": true, "ticket_id": 123}
• POST /api/tickets?action=close — Close a ticket. Body: {"ticket_id"}
• POST /api/tickets?action=transcript — Record a transcript path. Body: {"ticket_id", "storage_path"}
• GET /api/tickets?action=list&tenant_id=X — List tickets for a tenant. Returns up to 200 records, newest first.

Servers

• GET /api/servers?action=list&tenant_id=X — List linked Discord servers for a tenant.
• POST /api/servers?action=link — Link a server. Body: {"tenant_id", "guild_id", "guild_name"}. Uses upsert — re-linking reactivates an existing record.

Automations

• GET /api/automations?action=list&tenant_id=X — List all automations for a tenant.
• POST /api/automations?action=save — Create or update an automation. Body: {"tenant_id", "name", "trigger_type", "definition_json": {"conditions": [...], "actions": [...]}, "enabled", "id" (optional for update)}

AI Settings

• GET /api/ai?action=settings&tenant_id=X — Get AI settings and knowledgebases for a tenant.
• POST /api/ai?action=settings — Update AI settings. Body: {"tenant_id", "enabled", "confidence_threshold", "support_role_id", "fallback_message"}

Health Check

• GET /api/health — Returns {"ok": true, "service": "guildpilot-web", "time": "2024-01-15T12:00:00Z"}