# Ogma Documentation > Full markdown export of the Ogma documentation site for LLMs and automated tools. - Site: https://docs.ogma.gg - Product: Ogma — AI-powered Discord support (tickets, knowledge base, dashboard) - Generated: 2026-07-05T13:24:07.888Z - Pages: 24 ## Table of contents 1. [Ogma](https://docs.ogma.gg) 2. [Introduction](https://docs.ogma.gg/getting-started/) 3. [Setup](https://docs.ogma.gg/getting-started/setup) 4. [Checklist](https://docs.ogma.gg/getting-started/checklist) 5. [How tickets work](https://docs.ogma.gg/discord/how-tickets-work) 6. [Commands](https://docs.ogma.gg/discord/commands) 7. [Escalation](https://docs.ogma.gg/discord/escalation) 8. [Auto-learn](https://docs.ogma.gg/discord/auto-learn) 9. [Overview](https://docs.ogma.gg/dashboard/overview) 10. [Tickets](https://docs.ogma.gg/dashboard/tickets) 11. [Knowledge](https://docs.ogma.gg/dashboard/knowledge) 12. [Agentic tools](https://docs.ogma.gg/dashboard/agentic-tools) 13. [Tips](https://docs.ogma.gg/dashboard/tips) 14. [Background jobs](https://docs.ogma.gg/dashboard/jobs) 15. [Insights](https://docs.ogma.gg/dashboard/insights) 16. [Settings](https://docs.ogma.gg/dashboard/settings) 17. [Support ops](https://docs.ogma.gg/dashboard/support-ops) 18. [Automation rules](https://docs.ogma.gg/dashboard/automation-rules) 19. [Billing](https://docs.ogma.gg/dashboard/billing) 20. [Data & retention](https://docs.ogma.gg/dashboard/data) 21. [Zero-access encryption](https://docs.ogma.gg/dashboard/zero-access) 22. [FAQ](https://docs.ogma.gg/help/faq) 23. [Troubleshooting](https://docs.ogma.gg/help/troubleshooting) 24. [Team members](https://docs.ogma.gg/dashboard/team) --- ## Ogma Source: https://docs.ogma.gg # Ogma Answer once, reuse forever AI support for Discord. Private tickets, answers from your docs, and a dashboard for your team. --- ## Introduction Source: https://docs.ogma.gg/getting-started/ # Introduction Ogma is AI support for Discord. Users open private ticket channels from a panel in your server. Ogma searches your documentation and replies. If it cannot answer, it escalates to your staff. Most of your setup happens **in Discord** with slash commands. The [dashboard](https://ogma.gg) is for managing docs, reviewing tickets, and advanced settings. ## How it works 1. **Users start in Discord.** They click a button in a ticket panel and get a private channel. 2. **Ogma answers from your content.** It searches uploaded docs, pasted text, synced URLs, and learned tips. 3. **Staff step in when needed.** A "Request human" button and automatic escalation put the ticket in front of your team. 4. **Tickets close with learning.** Staff run `/close`. Users rate the experience. Helpful resolutions can become reusable tips. ## The loop - **Resolve once** in a ticket. - **Learn automatically** (optional). Ogma suggests short tips from staff-resolved conversations. - **Reuse forever.** Confirmed tips and your docs are searched for every future question. ## What you manage, and where | In Discord | In the dashboard | |------------|------------------| | Opening and closing tickets | Knowledge base, tips, insights | | `/ogma-config setup` — set up a new server | Custom ticket types, business hours, voice prompt | | `/ogma-config link` — use existing channels | Team members, billing | | `/close`, `/add`, `/remove`, `/rename` | Transcripts, Playground testing | ## Get started **New to Discord bots?** Start here: ### [Setup guide →](https://docs.ogma.gg/getting-started/setup) The setup guide is written for complete beginners. It walks you through: - Adding Ogma to your server - Running one command to create everything (**new server**) - Or linking channels you already have (**existing server**) - Adding docs and testing before you go live Then use the [launch checklist](https://docs.ogma.gg/getting-started/checklist) before you announce support to your community. Questions? See the [FAQ](https://docs.ogma.gg/help/faq) and [troubleshooting](https://docs.ogma.gg/help/troubleshooting) pages. --- ## Setup Source: https://docs.ogma.gg/getting-started/setup # Setup guide This guide walks you through setting up Ogma from scratch. No prior experience with Discord bots is required. When you are done, your server will have: - A **ticket panel** — buttons users click to open private support channels - **Staff channels** — where transcripts, escalations, and learned tips go - An **AI assistant** — Ogma replies in tickets using your documentation (once you add it) **Time needed:** about 10–15 minutes for the Discord setup, plus time to add your docs. --- ## Before you start You need: | Requirement | Why | |-------------|-----| | **Manage Server** on your Discord server | Only server admins (or people they trust) can run setup commands | | Permission to **add a bot** to the server | You will click “Add to Discord” on the Ogma website | | (Recommended) A **second Discord account** or a friend | To test opening a ticket as a regular user | You do **not** need to use the website dashboard to get started. Everything in the steps below happens in Discord. --- ## Pick your path Answer one question: > **Does your server already have support channels** (for example `#support`, `#tickets`, or categories for different ticket types)? | Your answer | Follow this path | |-------------|------------------| | **No** — we are starting fresh | [Path 1: New server](#path-1-new-server-recommended) | | **Yes** — we already run support in Discord | [Path 2: Existing channels](#path-2-existing-channels) | | **I prefer the website** for all settings | [Path 3: Dashboard setup](#path-3-dashboard-setup-advanced) | Most beginners should use **Path 1**. --- ## Path 1: New server (recommended) ### Step 1 — Add Ogma to your server 1. Go to [ogma.gg](https://ogma.gg). 2. Click **Add to Discord** (or use the invite link in the dashboard if you are already signed in). 3. Choose the server you want to set up. 4. On the permissions screen, leave the suggested permissions **enabled**. Ogma needs them to create channels, send messages, and post the ticket panel. 5. Click **Authorize**. **Success check:** - Ogma appears in your server’s member list (status should be online). - If your server has a **system messages** channel, Ogma may post a short welcome there with setup hints. **If something went wrong:** make sure you have “Manage Server” on that Discord server. Only admins (or roles with that permission) can add bots. --- ### Step 2 — Open the setup command 1. In Discord, go to any text channel where you can type (for example `#general`). 2. Type `/` to open the slash command menu. 3. Start typing `ogma-config` and select **`/ogma-config setup`**. 4. Press **Enter**. **Success check:** a popup form titled **“Ogma Support Setup”** appears. **If the command does not show up:** - Wait a minute and try again (new commands can take up to an hour to appear globally, but usually show up within a few minutes). - Make sure you typed `/` in a channel, not in a DM. - Confirm Ogma is online in the member list. --- ### Step 3 — Fill in the setup form Each field is explained below. You can copy the **example values** if you are unsure. #### Ticket types **What it means:** which kinds of support buttons users will see on the panel. **What to type:** comma-separated names from this list: | Type name | Good for | |-----------|----------| | `customer` | General help | | `technical` | Bugs and technical issues | | `billing` | Payments and invoices | | `sales` | Pricing and purchases | **Example:** `customer, technical` You can start with just `customer` if you want to keep it simple. --- #### Start channel name **What it means:** the name of the channel where the ticket panel (buttons) will live. **What to type:** a short name using letters and hyphens. **Example:** `start-support` (the default is fine) Ogma will create this channel for you. Tell your community: *“Open a ticket in #start-support.”* --- #### Staff role names **What it means:** which Discord roles can see all tickets and manage support. **What to type:** the **exact names** of your staff roles, separated by commas. These must match what you see in **Server Settings → Roles**. **Example:** `Support, Moderator` **How to find role names:** 1. In Discord, click your server name → **Server Settings**. 2. Open **Roles**. 3. Copy the names of roles that should handle tickets. **Tip:** leave this blank only if you will add staff roles later in the [dashboard Settings](https://docs.ogma.gg/dashboard/settings). Tickets will still work, but staff may not see them until roles are configured. --- #### Auto-learn from tickets **What it means:** when staff close a ticket, Ogma extracts a short tip and adds it to the knowledge base. Unwanted tips can be removed in `#learned-tips` or the dashboard. **What to type:** `yes` or `no` **Recommendation:** `yes` for most teams. --- #### Transcript retention (days) **What it means:** how long closed ticket transcripts are kept. **What to type:** one of these numbers (depends on your plan): | Value | Meaning | Plans | |-------|---------|-------| | `30` | Keep for 30 days | All (Free maximum) | | `60` or `90` | Longer retention | Plus, Enterprise | | `0` | Keep forever (unlimited) | Enterprise only | If you are on Free, use `30`. The setup form may default to `90` — lower it on Free or upgrade later under [Billing](https://docs.ogma.gg/dashboard/billing). --- ### Step 4 — Submit the form 1. Click **Submit** at the bottom of the form. 2. Wait a few seconds. Ogma will create channels and post the ticket panel. **Success check:** you see a private reply (only you can see it) that says support channels were created, with links to the start channel and staff area. **What Ogma creates:** | Channel / category | Purpose | |--------------------|---------| | `#start-support` (or your chosen name) | Ticket panel with buttons | | Categories for each ticket type | Private channels appear here when users open tickets | | `#ticket-transcripts` | Closed ticket logs | | `#staff-review` | Escalated tickets for staff | | `#learned-tips` | Suggested tips from resolved tickets | --- ### Step 5 — Confirm everything worked Run this command in Discord: ``` /ogma-config view ``` You should see: - A linked **start channel** - At least one **enabled ticket type** - A message that setup is ready (or clear next steps if something is missing) Then open your **start channel** in the channel list. You should see a message from Ogma with buttons like **Customer Support** and **Technical Support**. **If you see a permissions error:** Ogma needs **Manage Channels** on its bot role. 1. Go to **Server Settings → Roles**. 2. Find the **Ogma** role (or whichever role the bot uses). 3. Turn on **Manage Channels**, **View Channels**, **Send Messages**, and **Read Message History**. 4. Run `/ogma-config setup` again. More fixes: [Troubleshooting](https://docs.ogma.gg/help/troubleshooting). --- ### Step 6 — Add documentation (so Ogma can answer questions) Ogma searches **your content** before replying. Without docs, it can still open tickets and escalate to staff, but AI answers will be limited. **Easiest options:** | Method | Where | Best for | |--------|-------|----------| | Paste or upload | Dashboard → **Knowledge** | FAQs, policies, guides | | Quick note | Discord: `/ingest content:Your text here` | One-off answers you want immediately | After adding content: 1. Open the dashboard **Knowledge** page. 2. Use **Playground** to ask a real question your users would ask. 3. Check that the answer looks correct and cites your content. --- ### Step 7 — Test the full flow Use a **non-staff account** (a second Discord account or a friend): 1. Go to the **start channel** and click a ticket type button. 2. A **private channel** opens — only that user and staff should see it. 3. Ask a question that is answered in your docs. 4. Confirm Ogma replies. 5. Click **Request human** if you want to test escalation. Then as **staff**: 1. Reply in the ticket channel. 2. Run `/close` in that channel. 3. Confirm a transcript appears in `#ticket-transcripts`. 4. Confirm the user gets a rating DM (👍 / 👎 / Skip). --- ### You are done with Path 1 Before announcing support to your community, work through the [launch checklist](https://docs.ogma.gg/getting-started/checklist). --- ## Path 2: Existing channels Use this if you **already** have channels like `#support`, `#ticket-transcripts`, or ticket categories, and you do **not** want Ogma to create new ones. ### Step 1 — Add Ogma to your server Same as [Path 1, Step 1](#step-1--add-ogma-to-your-server). --- ### Step 2 — Link your existing channels 1. In any text channel, run: ``` /ogma-config link ``` 2. Ogma scans your server for common channel and category names. **Names Ogma looks for (examples):** | Purpose | Example channel / category names | |---------|-------------------------------| | Ticket panel | `#support`, `#tickets`, `#start-support` | | Transcripts | `#ticket-transcripts`, `#transcripts` | | Staff review | `#staff-review`, `#escalations` | | Tips | `#learned-tips`, `#tips` | | Ticket categories | `Customer Support Tickets`, or categories containing “support” / “billing” / “technical” | **Success check:** Ogma replies with a list of what it linked. If it found a start channel, the **ticket panel** is posted there automatically. --- ### Step 3 — Handle partial matches If Ogma links **some** channels but not all, the reply lists what is **still missing**. | Situation | What to do | |-----------|------------| | Missing a few channels | Run `/ogma-config setup` to create only what is missing, **or** rename your channels to match the examples above and run `/ogma-config link` again | | Names are very custom | Use the dashboard **Settings → Channels → Use channels this server already has** (channel migrator) to map them manually | | Nothing was found | Use [Path 1](#path-1-new-server-recommended) instead | Run `/ogma-config view` to see current status and next steps. --- ### Step 4 — Add docs and test Same as [Path 1, Step 6](#step-6--add-documentation-so-ogma-can-answer-questions) and [Step 7](#step-7--test-the-full-flow). --- ## Path 3: Dashboard setup (advanced) Use the website if you want finer control (custom ticket types, business hours, voice prompt, etc.) before touching Discord. ### Overview 1. [Sign in](https://ogma.gg) with Discord and select your server. 2. Configure your server using either: - **Setup wizard** — open **Overview** and follow the guided flow (or go directly to **Setup** from the continue banner). Choose to create new Discord channels or map existing ones, pick staff roles, and customize ticket types from a preset. - **Settings** — open **Settings** directly for full control. See [Settings](https://docs.ogma.gg/dashboard/settings) for every section. 3. Click **Save** (Settings) or finish the wizard steps. 4. In Discord, run: ``` /ogma autoconfig ``` This applies your saved settings by creating or updating channels and the ticket panel. **Important:** saving in the dashboard alone does **not** change Discord. You must run `/ogma autoconfig` after each structural change (ticket types, staff roles, categories). If you already have channels and do not want new ones created, use the dashboard **channel migrator** (Settings → Channels) instead of `/ogma autoconfig`. --- ## Quick reference | I want to… | Run this in Discord | |------------|---------------------| | Set up a new server from scratch | `/ogma-config setup` | | Connect channels we already have | `/ogma-config link` | | Check if setup is complete | `/ogma-config view` | | Apply dashboard changes to Discord | `/ogma autoconfig` | | Add a quick FAQ snippet | `/ingest content:…` | All setup commands require **Manage Server**. Full command list: [Discord commands](https://docs.ogma.gg/discord/commands). --- ## Common problems | Problem | Fix | |---------|-----| | “You need Manage Server permission” | Ask a server admin to run the command, or grant yourself Manage Server in **Server Settings → Roles** | | Ogma lists missing permissions | **Server Settings → Roles → Ogma** → enable **Manage Channels** and the other listed permissions | | `/ogma-config link` found nothing | Your channel names may not match common patterns — use Path 1 (`setup`) or the dashboard channel migrator | | No ticket panel in the start channel | Run `/ogma-config view`. If status is not ready, run `setup` or `link` again | | Ogma does not answer in tickets | Add content in **Knowledge**, then test in **Playground**. See [Troubleshooting](https://docs.ogma.gg/help/troubleshooting) | --- ## What to do next 1. [Launch checklist](https://docs.ogma.gg/getting-started/checklist) — verify everything before you go live 2. [How tickets work](https://docs.ogma.gg/discord/how-tickets-work) — what users and staff see day to day 3. [Knowledge](https://docs.ogma.gg/dashboard/knowledge) — build out your documentation --- ## Checklist Source: https://docs.ogma.gg/getting-started/checklist # Launch checklist Use this before you tell your community that Ogma support is live. Tick each box in order. If you used **Path 1** or **Path 2** from the [setup guide](https://docs.ogma.gg/getting-started/setup), most of the Discord items are already done. --- ## 1. Bot is in your server - [ ] Ogma shows as **online** in the member list - [ ] You (or an admin) have **Manage Server** permission --- ## 2. Discord setup is complete Run `/ogma-config view` in Discord. It should show that support is linked and ready. - [ ] A **start channel** exists (for example `#start-support`) with a **ticket panel** (buttons from Ogma) - [ ] At least **one ticket type** is enabled - [ ] Staff channels exist or are linked: `#ticket-transcripts`, `#staff-review`, `#learned-tips` - [ ] Each enabled ticket type has a **category** for new ticket channels **How you got here (check one):** - [ ] `/ogma-config setup` — new server setup - [ ] `/ogma-config link` — connected existing channels - [ ] Dashboard save + `/ogma autoconfig` — website configuration **If anything is missing:** see [Setup guide](https://docs.ogma.gg/getting-started/setup) or [Troubleshooting](https://docs.ogma.gg/help/troubleshooting). The dashboard **Overview** checklist shows the same gaps with quick-fix links. --- ## 3. Staff are configured - [ ] At least one **staff role** is set (in the setup form or dashboard **Settings → Team & access**) - [ ] Real support staff have that role on Discord - [ ] Staff know tickets are **private channels** and replies happen there - [ ] **Management roles** assigned if you plan to use `/lockdown` on sensitive tickets --- ## 4. Knowledge is in place - [ ] You added FAQs, policies, or guides in dashboard **Knowledge** (or used `/ingest` for quick notes) - [ ] You tested **several real questions** in **Playground** and the answers look good - [ ] You know how to add or update content later (upload, paste, or URL) - [ ] No **sync errors** on URL sources (check Overview health or Knowledge source health) --- ## 5. Test as a regular user Use an account **without** a staff role (a second account or a friend): - [ ] Open a ticket from the **panel** in the start channel - [ ] A **private ticket channel** opens - [ ] Ask something covered by your docs — Ogma replies with a relevant answer - [ ] Click **Request human** and confirm escalation works as you expect --- ## 6. Test as staff - [ ] Join an escalated or open ticket - [ ] Reply in the channel — Ogma should **pause** while staff are active (cooldown) - [ ] **Claim** the ticket from the dashboard queue or `/claim` in Discord - [ ] Run `/close` in the ticket channel (requires **Manage Channels** on your Discord account) - [ ] A **transcript** appears in `#ticket-transcripts` - [ ] The user receives a **rating DM** (👍 / 👎 / Skip) --- ## 7. Team and community readiness - [ ] Staff know to run `/close` when a ticket is resolved - [ ] Staff know where **escalations** appear (`#staff-review`) and where auto-learn summaries appear (`#learned-tips`, with remove if needed) - [ ] Staff know about the **Discord commands** page in the dashboard (searchable command reference) - [ ] You told users **where to open tickets** (for example: “Go to #start-support and click a button”) --- ## Optional (recommended) - [ ] **Auto-learn** is on (or you plan to maintain knowledge manually) - [ ] **Business hours** are set if you want different behavior outside support hours ([Settings](https://docs.ogma.gg/dashboard/settings)) - [ ] **AI model version** reviewed if a dashboard upgrade banner is showing ([Settings → AI model version](https://docs.ogma.gg/dashboard/settings#ai-model-version)) - [ ] **Transcript retention** matches your policy ([Data & retention](https://docs.ogma.gg/dashboard/data)) - [ ] **Usage alerts** configured under Settings → Notifications - [ ] On Plus/Enterprise: **Support ops** configured (assignment, SLAs, or macros) — see [Support ops](https://docs.ogma.gg/dashboard/support-ops) - [ ] You reviewed **Insights** after a few real tickets --- When every box in sections 1–7 is checked, you are ready to announce support. **Need help?** [Troubleshooting](https://docs.ogma.gg/help/troubleshooting) · [FAQ](https://docs.ogma.gg/help/faq) --- ## How tickets work Source: https://docs.ogma.gg/discord/how-tickets-work # How tickets work This page walks through a ticket's full lifecycle, from both the user's and the staff's point of view. ## Opening a ticket 1. Users go to the ticket start channel you configured. 2. They click a button for a ticket type (or choose from a dropdown when you have more than four types). 3. If **pre-open intake** is enabled, they fill in subject and/or description first. 4. Ogma creates a **private text channel** visible only to the user and your staff roles. By default a user can have only one open ticket per type. Raise or remove this limit per type in **Settings → Tickets**. Restrict types to specific Discord roles when needed. Each ticket channel is created inside a category for that type (for example "General Tickets"). Enable **Sequential ticket names** to use `ticket-1`, `ticket-2`, … instead of usernames. ## Business hours If you enable business hours in **Settings**, Ogma can: - Send an away message when users write outside your hours - Pause AI replies outside hours (while still allowing ticket creation, if configured) - Include expected response time and next open time in away messages when configured in Settings Tickets created outside hours still go into the normal flow when creation is allowed. ## AI replies and the knowledge base When a user sends a message in a ticket: - Ogma searches your knowledge base (uploaded files, pasted text, synced URLs, and tips). - If it finds a sufficiently relevant answer, it replies. - If it cannot answer confidently, it escalates. Once any staff member sends a message, Ogma pauses before replying again (30 minutes by default). Change this with **Staff reply cooldown** in Settings, or set it to 0 to disable the time-based pause. ## Escalation to staff A ticket escalates when: - The user clicks **Request human** - Ogma cannot find a good answer in your content - [Automation rules](https://docs.ogma.gg/dashboard/automation-rules) escalate on keyword, CSAT, or SLA triggers Escalated tickets stay in the same private channel. Staff reply directly there. Ogma will not interject while staff are responding (subject to the cooldown). Watch `#staff-review` for escalation feed items. On Plus/Enterprise, **Quality flags** in Settings list open tickets that need review. ## Assignment and the staff queue On Plus/Enterprise with auto-assignment enabled, new tickets may be assigned automatically (round robin or load balanced). Otherwise staff **claim** tickets from the dashboard **Staff queue** or with `/claim` in Discord. The queue filters by unclaimed, yours, escalated, awaiting staff, and awaiting customer. See [Tickets → Staff queue](https://docs.ogma.gg/dashboard/tickets#staff-queue). ## Lockdown Management can run `/lockdown` on sensitive tickets. Regular staff lose Discord access to the channel until `/unlock`. Closed lockdown tickets remain visible only to management in the dashboard. Configure **Management roles** in Settings first. ## Inactivity auto-close When **Ticket inactivity** is enabled, Ogma closes tickets after a set number of days without messages: - Optional warning posted N days before close - Optional longer timeout for escalated tickets - **Customer messages only** mode — staff replies reset the timer but do not count as activity Auto-close archives the transcript and deletes the channel. ## Closing a ticket Only members with Discord **Manage Channels** can run `/close` (a configured staff role alone is not sufficient). `/close` requires a reason: - Resolved, duplicate, user unresponsive, out of scope, spam, or other - Optional note (500 characters) On close: 1. The channel is deleted after archiving. 2. The user receives a CSAT DM: **Helpful** (👍), **Not helpful** (👎), or **Skip**. 3. A transcript posts to `#ticket-transcripts` (unless the ticket was under lockdown — see below). 4. If auto-learn is enabled, staff participated, and the ticket was not under lockdown, Ogma extracts a tip and posts a summary to `#learned-tips`. Optional **post-close follow-up** DMs check whether the issue was truly resolved (skipped for inactivity and lockdown closes). Transcripts are also in dashboard **Tickets**. Retention is controlled under [Data & retention](https://docs.ogma.gg/dashboard/data). ## Tips and learning If **Auto-learn** is on, tips are added to the knowledge base on close and summarized in `#learned-tips`. Staff can remove unwanted tips from Discord or the dashboard **Tips** page. Lockdown closes skip tip extraction and skip posting to `#ticket-transcripts`. See [Auto-learn](https://docs.ogma.gg/discord/auto-learn) and [Tips](https://docs.ogma.gg/dashboard/tips). ## Proactive follow-ups (Plus/Enterprise) **Proactive follow-ups** (Settings → Alerts & follow-ups) post a nudge in the ticket channel when an **open** ticket goes stale. **Reopen on negative CSAT** creates a quality flag and can run automation when a user rates 👎 after close. Because the ticket channel is deleted on close, this does not reopen the original Discord channel — review flagged tickets in **Settings → Quality flags** or **Insights**. Related: [Commands](https://docs.ogma.gg/discord/commands), [Escalation](https://docs.ogma.gg/discord/escalation), [Support ops](https://docs.ogma.gg/dashboard/support-ops), [Settings](https://docs.ogma.gg/dashboard/settings). --- ## Commands Source: https://docs.ogma.gg/discord/commands # Commands All commands are slash commands unless noted. Type `/` in a text channel to see what is available in your server. Your dashboard includes a searchable **Discord commands** page (sidebar → Discord commands) for each server. It lists every command, who can run it, whether it is available to your account, and per-command options. This docs page is the static reference; the dashboard page filters to what you can run today. **New to Ogma?** Follow the [setup guide](https://docs.ogma.gg/getting-started/setup) first — it tells you exactly which commands to run and when. --- ## Who can use what | Access | Typical users | |--------|----------------| | **Server admin** | Manage Server permission, or a role assigned as **management** in Settings | | **Support staff** | A **staff role** from Settings, or Manage Channels | | **Ticket participant** | The ticket owner or support staff | | **Anyone** | Any member (when enabled) | Staff roles and management roles are configured in dashboard **Settings → Team & access**. Many staff commands accept either a configured **staff role** or Discord **Manage Channels**. Exceptions: | Command | Who can run | |---------|-------------| | `/close` | **Manage Channels only** (staff role alone is not enough) | | `/remove` | Configured **staff role** only | | `/add`, `/rename` | Ticket owner or configured **staff role** | | `/claim`, `/unclaim`, `/note`, `/macro` | Staff role **or** Manage Channels | | `/lockdown`, `/unlock` | **Management role** or Manage Server | --- ## Setup commands (run these first) These require **Manage Server** (server admin). | Command | When to use it | |---------|----------------| | `/ogma-config setup` | **New server** — opens a guided form to create channels, save settings, and post the ticket panel | | `/ogma-config link` | **Existing channels** — auto-connects `#support`, transcript channels, and ticket categories you already have | | `/ogma-config view` | **Any time** — shows linked channels, setup status, enabled ticket types, and a link to dashboard Settings | | `/ogma autoconfig` | **After dashboard changes** — creates or updates Discord channels from settings you saved on the website | ### Permission note Ogma needs **Manage Channels** on its bot role to create channels and tickets. If something is missing, the bot replies with a list of permissions to fix — go to **Server Settings → Roles → Ogma** and enable them. --- ## Ticket commands Use these **inside an open ticket channel** unless noted. | Command | Who can use | What it does | |---------|-------------|--------------| | `/close reason note?` | Manage Channels | Closes the ticket, archives a transcript, deletes the channel, and sends the user a rating DM | | `/claim` | Staff role or Manage Channels | Assigns the ticket to you so others know you are handling it | | `/unclaim` | Staff role or Manage Channels | Releases your claim so another staff member can pick it up | | `/note content` | Staff role or Manage Channels | Adds an internal note (visible in the dashboard, excluded from user-facing transcripts) | | `/add user:@someone` | Ticket owner or staff role | Adds someone to the private ticket channel | | `/remove user:@someone` | Staff role | Removes someone from the ticket channel | | `/rename name:text` | Ticket owner or staff role | Renames the ticket channel | | `/lockdown` | Management | Restricts the ticket so only the customer and management roles can access the channel | | `/unlock` | Management | Lifts lockdown and restores normal staff access | ### Closing a ticket `/close` requires a **reason**: - Resolved - Duplicate - User unresponsive - Out of scope - Spam / abuse - Other You can add an optional **note** (up to 500 characters). The ticket owner receives a CSAT rating DM after closure when one has not already been submitted. ### Lockdown Lockdown is for sensitive tickets (billing disputes, HR, moderation). Regular support staff lose channel access until lockdown is lifted. Configure **management roles** in **Settings → Team & access** before using `/lockdown` or `/unlock`. Closed tickets that were under lockdown remain restricted to management in the dashboard. --- ## Staff shortcuts | Shortcut | Who can use | What it does | |----------|-------------|--------------| | `/macro shortcut` | Staff role or Manage Channels (Plus or Enterprise) | Inserts a canned response from **Settings → Macros** (e.g. `/macro refund-policy`) | | `-# your note` | Staff | Send a message starting with `-#` to save a quick internal note; the message is deleted after saving | Macros require **Ogma Plus** or **Enterprise**. Create and edit macros in dashboard **Settings → Macros**. --- ## Knowledge commands | Command | Permission | What it does | |---------|------------|--------------| | `/ingest content title?` | Manage Server | Adds pasted text to your knowledge base immediately | The optional `title` helps you find the source later. For files, URLs, and synced sources, use dashboard **Knowledge**. --- ## AI chat (raw GPT) These commands chat directly with the AI model **without** searching your knowledge base. They count against your plan's **direct AI question** allowance (Playground uses the same meter). | Command | Notes | |---------|-------| | `/ask prompt` | Preferred command name | | `/ogma askgpt prompt` | Legacy alias — same behavior as `/ask` | Both require **Settings → AI & voice → Enable raw GPT commands**. When disabled, the bot points you to **Playground** instead. **Hourly rate limits** apply per guild, channel, and user. Monthly AI usage is tracked for billing and alerts; it does not hard-block `/ask` at the included monthly count — see [Billing](https://docs.ogma.gg/dashboard/billing). ### Testing vs general chat | Tool | Use for | |------|---------| | **Playground** (dashboard → Knowledge) | Testing real support answers — shows exactly which docs were used | | `/ask` or `/ogma askgpt` | General AI chat — **ignores your docs** | For validating support quality, always use **Playground**, not raw GPT commands. --- ## Quick setup reminder | Your situation | Command | |----------------|---------| | Brand new server | `/ogma-config setup` | | Already have support channels | `/ogma-config link` | | Changed settings on the website | `/ogma autoconfig` | | Not sure if you are done | `/ogma-config view` | Full walkthrough: [Setup guide](https://docs.ogma.gg/getting-started/setup). --- ## Related - [How tickets work](https://docs.ogma.gg/discord/how-tickets-work) - [Escalation](https://docs.ogma.gg/discord/escalation) - [Support ops macros](https://docs.ogma.gg/dashboard/support-ops#macros) (Settings → Macros) - [Billing & usage limits](https://docs.ogma.gg/dashboard/billing) --- ## Escalation Source: https://docs.ogma.gg/discord/escalation # Escalation Escalation moves a ticket from "bot is handling it" to "a human needs to step in." ## How users escalate Every ticket message area includes a **Request human** button. When clicked: - The ticket is flagged for staff attention. - Depending on your setup, staff may be notified in the `staff-review` channel or by direct mentions. - Ogma will stop trying to answer until staff engage. ## Automatic escalation Ogma escalates on its own when: - It cannot find a sufficiently confident answer in your knowledge base. - The conversation indicates a human-only action (refunds, account changes, sensitive issues, etc.). - You have configured behavior that requires a human for certain signals. - **Frustration detection** is enabled and the customer shows repeated questions, escalation phrases, caps anger, or rapid messages — or the AI sets `requiresEscalation` on a reply. Configure frustration handling in **Settings → AI & voice → Frustration detection**: | Mode | Behavior | |------|----------| | **Escalate automatically** | Heuristic score at/above the threshold or AI escalation → full staff handoff | | **Suggest only** | Creates a quality flag and optional staff-review notification; bot keeps replying | Heuristic scores and reasons are recorded on ticket events for tuning. Escalated tickets remain in the same private channel. Staff reply there directly. ## Staff reply behavior Once any staff member sends a message in a ticket, Ogma pauses before replying again (30 minutes by default). Change this in **Settings → Team & access → Staff reply cooldown**: - A positive number (for example 15 or 30) — wait that many minutes after a staff message. - `0` — disable the time-based pause. Ogma will still avoid talking over active staff conversation using other signals. This prevents the bot from talking over your team while they are helping. ## Where staff see escalations - The ticket channel itself (always). - Dashboard **Staff queue** — filter by **Escalated** or **Awaiting staff** ([Tickets](https://docs.ogma.gg/dashboard/tickets#staff-queue)). - The `staff-review` management channel created by `/ogma autoconfig`. - **Quality flags** in Settings (Plus/Enterprise) — open tickets flagged for escalation, negative CSAT, or low-confidence replies. - [Automation rules](https://docs.ogma.gg/dashboard/automation-rules) and [webhooks](https://docs.ogma.gg/dashboard/support-ops#webhooks) on Plus/Enterprise. ## After escalation Staff handle the ticket to resolution and run `/close` when done. The normal close flow (rating DM, transcript, possible tip) still applies. See [How tickets work](https://docs.ogma.gg/discord/how-tickets-work) for the full lifecycle, [Support ops](https://docs.ogma.gg/dashboard/support-ops) for SLAs and alerts, and [Auto-learn](https://docs.ogma.gg/discord/auto-learn) for what happens to useful resolutions. --- ## Auto-learn Source: https://docs.ogma.gg/discord/auto-learn # Auto-learn Auto-learn turns resolved staff conversations into reusable knowledge with almost no extra work. ## How it works 1. A user opens a ticket and Ogma cannot fully resolve it, or the user requests a human. 2. Staff join the private channel and help. 3. Staff run `/close`. 4. If **Auto-learn** is enabled and the conversation meets minimum criteria (staff participated, enough messages), Ogma extracts a short **tip** and **adds it to the searchable knowledge base immediately**. 5. A summary is posted to your `learned-tips` channel with a **Remove from knowledge base** button if staff want to discard it. Tips are searchable right away unless removed. There is no separate confirm step before they go live. ## What makes a good tip Tips are short, specific, and scoped. Good examples: - "Refunds over $50 require a manager approval code from the #refunds channel." - "Password resets for school accounts are handled at help.school.edu/reset." - "Our Enterprise plan includes priority queueing and a dedicated channel." Tips are not a replacement for long documentation. Use **Knowledge** for reference material and procedures. Use tips for the answers your staff repeat in tickets. ## Requirements Auto-learn only runs when: - **Auto-learn** is enabled in **Settings → AI & voice**. - A staff member sent at least one message in the ticket. - The conversation meets the **minimum message count** configured in Settings (default skips very short threads). - The ticket was **not closed under lockdown** — lockdown closes skip tip extraction. You can turn auto-learn off at any time. When it is off, you are responsible for all knowledge. ## Managing tips - In Discord, use **Remove from knowledge base** in `#learned-tips` to discard a tip (with a short confirmation step). - In the dashboard, go to **Tips** to edit wording, merge near-duplicates, remove outdated tips, or browse tips by source ticket. Changes in the dashboard take effect immediately for future searches. ## Relationship to Knowledge | Source | Best for | Example | |--------|----------|---------| | Knowledge (upload, paste, URL) | Reference docs, procedures, product details | "How to connect a new integration" | | Tips (auto-learn or manual) | Repeated answers from real tickets | "The staging key expires every 6 hours" | Both are searched together when Ogma answers a question. ## Disabling or resetting Turn **Auto-learn** off in **Settings → AI & voice** if you prefer a fully manual knowledge base. Existing tips remain searchable until you remove them. See [Tips](https://docs.ogma.gg/dashboard/tips) and [Knowledge](https://docs.ogma.gg/dashboard/knowledge) for how to curate what Ogma knows. --- ## Overview Source: https://docs.ogma.gg/dashboard/overview # Dashboard overview The dashboard is where you configure and inspect Ogma. Day-to-day support still happens in Discord. Sign in at [ogma.gg](https://ogma.gg) with the Discord account that has Manage Server on the target server. ## Server navigation Use the server switcher to move between servers you manage. Each server has its own tickets, knowledge, tips, settings, agentic tools, billing, and team. ## Pages at a glance | Page | Primary purpose | Common tasks | |------|-----------------|--------------| | **Overview** | Setup checklist and health | See deployment status, bot permissions, knowledge sync issues | | **Tickets** | Review history | Open transcripts, search past issues, check CSAT | | **Staff queue** | Triage open tickets | Claim, filter escalated/unclaimed, jump to ticket detail | | **Discord commands** | Command reference | Search slash commands available to your account | | **Knowledge** | Curate what Ogma searches | Upload docs, paste text, add/sync URLs, test in Playground | | **Agentic tools** | Give Ogma live data access | Create webhook-backed lookups (orders, accounts, status). See [Agentic tools](https://docs.ogma.gg/dashboard/agentic-tools) — SDK and demo in [ogma-open](https://github.com/KieranHolroyd/ogma-open). | | **Tips** | Curate learned answers | Edit, merge, import, or batch-learn from transcripts | | **Background jobs** | Track long-running work | Monitor tip backfill and URL sync progress | | **Insights** | Understand performance | Deflection, CSAT trends, knowledge gaps, ticket-type breakdown | | **Settings** | Control behavior | Staff roles, ticket types, AI model version, business hours, support ops | | **Billing** | Plan and usage | View usage, overage estimates, upgrade, manage subscription | | **Data & retention** | Compliance and lifecycle | Transcript retention, exports, audit log | | **Team** | Dashboard access | Invite teammates, roles, category permissions | ## Setup checklist and health The **Overview** page shows a setup checklist and live health summary: | Checklist item | What it means | |----------------|---------------| | Bot permissions | Ogma has Manage Channels and related permissions | | Staff roles configured | At least one staff role selected in Settings | | Knowledge base started | At least one indexed source | | Discord channels linked | `/ogma autoconfig` or setup/link has run successfully | | First ticket received | At least one ticket has been opened | **Server health** reports deployment status (Ready / Partial / Pending), missing Discord channels, bot permission gaps, and knowledge sync problems. A **Ticket activity** chart shows tickets opened and closed over the last 14 days. Use the checklist action links to jump directly to the page that fixes each gap. If setup is incomplete, the **Overview** page redirects to the **setup wizard** — a guided flow for connecting Discord channels, choosing staff roles, and configuring ticket types (including custom types). You can reopen it anytime from the continue banner or from **Settings → Channels**. ## How it fits together - **Discord is the support surface.** Users open tickets, talk, and get help there. - **The dashboard is the control surface.** You upload docs, tune settings, review what happened, and connect tools. - **Autoconfig bridges the two.** After you change ticket types or staff roles, run `/ogma autoconfig` once in Discord to create or update channels and the ticket panel. ## Quick start from the dashboard 1. Go to **Settings** and define staff roles and at least one ticket type. 2. Run `/ogma autoconfig` in Discord. 3. Go to **Knowledge**, add a few key docs, and test questions in **Playground**. 4. Use **Insights** after some real tickets to see what to add next. 5. On Plus or Enterprise, explore **Support ops** for assignment, SLAs, and macros. See [Setup](https://docs.ogma.gg/getting-started/setup) for the full flow. ## Related - [Support ops](https://docs.ogma.gg/dashboard/support-ops) — Plus/Enterprise routing, SLAs, webhooks - [Discord commands](https://docs.ogma.gg/discord/commands) — slash command reference (also searchable in the dashboard) --- ## Tickets Source: https://docs.ogma.gg/dashboard/tickets # Tickets The **Tickets** page is your archive and audit trail for support on this server. ## What you see - Open and recently closed tickets - Ticket type, user, status, assignee, and timestamps - CSAT rating (👍 / 👎) when available - Escalation and lockdown indicators - Quick links to the full transcript ## What you can do - Search and filter by status and date range; use search for user, type, or subject text - Open a ticket to view the full message history - Download or view the transcript for any closed ticket - Export closed transcripts by date range (all plans) - Jump to the original Discord channel when it still exists ## Staff queue The **Staff queue** is a separate sidebar item under **Support** (not a sub-tab of Tickets): | Filter | Shows | |--------|-------| | **All open** | Every open ticket | | **Mine** | Tickets assigned to you | | **Unclaimed** | No assignee yet | | **Escalated** | Reached staff or bot could not answer | | **Awaiting staff** | Waiting on your team | | **Awaiting customer** | Waiting on the ticket owner | Claim or release tickets from the queue. Assignment syncs with Discord — staff can also use `/claim` and `/unclaim` in the ticket channel. Queue stats at the top show counts for open, mine, unclaimed, and escalated tickets. ## Ticket detail Opening a ticket shows the full message timeline, metadata (type, status, assignee, tags), CSAT feedback, and internal notes. Management-restricted tickets (closed under lockdown) are visible only to management roles in the dashboard. ## Transcripts and retention When staff run `/close` (or inactivity auto-close runs): - A full transcript (messages, timestamps, participants) is saved. - The transcript is posted to your `ticket-transcripts` Discord channel. - The transcript is available in the dashboard regardless of whether the Discord channel still exists. Control how long transcripts are kept in **Settings → Data & retention** or on the [Data & retention](https://docs.ogma.gg/dashboard/data) page. After that window, they are permanently deleted. Free plan supports up to 30 days; Plus and Enterprise support longer periods and unlimited on Enterprise. ## Lockdown Sensitive tickets can be **locked down** by management with `/lockdown` in Discord. Regular staff lose channel access; only the customer and management roles remain. Closed lockdown tickets stay restricted to management in the dashboard. Configure **Management roles** in Settings before using lockdown. See [Commands → Lockdown](https://docs.ogma.gg/discord/commands#lockdown). ## Inactivity auto-close When enabled in **Settings → Tickets**, Ogma closes tickets after a configured number of days without activity: - Optional warning message N days before close - Optional longer period for escalated tickets - **Customer messages only** — staff replies reset the timer but do not count as activity Auto-close archives the transcript and deletes the channel like a normal close. ## Relationship to Discord - **Live work happens in Discord.** Reply to users and run `/close` there. - **Triage happens in the queue.** Claim and filter open work without scrolling every channel. - **Review and export happens here.** Look up history, share transcripts, analyze patterns. See [How tickets work](https://docs.ogma.gg/discord/how-tickets-work) for the full lifecycle. See [Support ops](https://docs.ogma.gg/dashboard/support-ops) for assignment and SLAs. See [Insights](https://docs.ogma.gg/dashboard/insights) for aggregate performance. --- ## Knowledge Source: https://docs.ogma.gg/dashboard/knowledge # Knowledge The knowledge base is the primary source Ogma searches when answering tickets and Playground questions. ## What counts as knowledge - Uploaded files (Markdown, plain text, HTML, JSON, CSV — not PDF) - Pasted text blocks with an optional title - Synced URLs that Ogma re-fetches on a schedule All content is chunked, embedded, and stored per server. Nothing is shared across servers. ## Adding content ### Upload Drop one or more documents (max 5 MB each). Ogma extracts text and indexes it. Re-upload a file to refresh it. Supported formats include `.txt`, `.md`, `.markdown`, `.html`, `.htm`, `.json`, and `.csv` (not PDF). ### Paste Paste documentation, answers, or notes directly. Give it a title so you can find it later. Good for internal runbooks or short procedures. ### URL Add a publicly accessible page. Ogma will fetch it and re-sync on a schedule based on your plan. | Plan | Minimum interval | Default for new URL sources | Max sources | |------|------------------|----------------------------|-------------| | Free | 24 hours | 24 hours | 1 | | Plus | 1 hour | 3 hours | 5 | | Enterprise | 15 minutes | 1 hour | 50 | You can set a custom refresh interval per source (minimum depends on plan). If a URL fails to sync, the status column shows an error. Common causes: - The page requires login or is behind a firewall. - The site blocks scrapers or returns non-HTML content. - The URL redirects through pages that require auth. Fix the URL or visibility, then trigger **Sync now** from the source detail view. ## Source health The Knowledge page surfaces **source health** — problems that cause bad answers before users hit them: | Status | Meaning | |--------|---------| | **Healthy** | Synced recently, no errors | | **Stale sync** | Content may be outdated | | **Sync overdue** | Scheduled refresh has not run | | **Sync failed** | Last fetch or index failed | | **Never synced** | URL added but not yet indexed | | **Never retrieved** | Indexed but not used in recent ticket or Playground searches | The **Overview** page also shows a knowledge sync summary. Fix sync errors and stale sources proactively. ## Freshness alerts Sources flagged as **stale** or **never retrieved in search** appear under freshness alerts. These are candidates for update, removal, or Playground testing — content that exists but may not help users. ## Duplicate and overlap detection Ogma scans tips against knowledge docs to find: - Tips that overlap long-form KB content - Near-duplicate tips - Conflicting answers between tips Review overlaps periodically and merge or delete redundant tips. Last scan time and next available scan are shown on the Knowledge page. ## The ingest command Add short notes from Discord: ``` /ingest content:Your text here title:Optional title ``` Handy for capturing something from a live ticket. For larger content, use the dashboard. ## Editing and version history For **pasted** and **uploaded** documents, open **Edit content** on the Knowledge page to change title and body in a VS Code-style editor (Monaco) with syntax highlighting for Markdown, JSON, HTML, and plain text. Use the pencil icon in the folder sidebar to **create a new document** in the current folder. Each content change: 1. Snapshots the previous version (deduplicated by content hash — identical re-syncs skip new versions and re-embedding). 2. Re-chunks and re-embeds the updated text. Use **Version history** in the editor to compare a past version against the current content and **Revert** when needed. Ogma keeps the last 50 versions per document. URL- and Git-managed docs sync through their normal pipelines; manual edits are for paste/upload sources. ## Playground **Playground** tests real support behavior: - Type a question the way a user would. - See the answer Ogma would give. - See which chunks were retrieved and their scores. - See agentic tool calls and results. Use Playground to validate new docs, debug weak answers, and verify agentic tools. Do not use `/ask` or `/ogma askgpt` for this — those ignore your knowledge base. On a **free trial**, the dashboard warns before Playground runs that consume AI quota beyond included limits. ## Tips vs long-form knowledge Knowledge is for reference material. Tips are for short, repeated answers. Both are searched together. See [Tips](https://docs.ogma.gg/dashboard/tips) and [Auto-learn](https://docs.ogma.gg/discord/auto-learn). ## Background jobs URL syncs and tip backfill batch jobs appear on **Background jobs** while running. See [Background jobs](https://docs.ogma.gg/dashboard/jobs). ## Keeping knowledge healthy - Remove or update stale content when freshness alerts fire. - Split very long documents when answers are weak. - Watch **Insights → Knowledge gaps** for escalations with nothing to retrieve. - Use Playground after every significant add or edit. Related: [Tips](https://docs.ogma.gg/dashboard/tips), [Auto-learn](https://docs.ogma.gg/discord/auto-learn), [Insights](https://docs.ogma.gg/dashboard/insights), [Commands](https://docs.ogma.gg/discord/commands) (`/ingest`), [Billing](https://docs.ogma.gg/dashboard/billing) (indexing limits and overage). --- ## Agentic tools Source: https://docs.ogma.gg/dashboard/agentic-tools # Agentic tools Agentic tools let Ogma fetch live data from *your* systems during tickets and Playground tests by calling webhooks you control. You keep your API keys. Ogma only stores an encrypted signing secret and optional outbound headers. Agentic tools are available on all plans: **Free** (2 per server), **Plus** (10 per server), and **Enterprise** (25 per server). ## The idea When a user asks something like "Where is order ORD-42?", Ogma can call a tool you defined instead of guessing or saying it does not know. You define: - A stable name (for example `check_order_status`) - A description the model uses to decide when to call it - A JSON parameter schema (what arguments are required or allowed) - A webhook URL that you implement - Optional context to include (Discord user ID, ticket ID, subject, tags) - Optional extra outbound headers (API keys you want sent on every call, stored encrypted) Ogma compiles that into a tool the model can call at runtime. ## Sandbox mode For development and demos, enable **Use sandbox (no webhook)** when creating or editing a tool: - No HTTPS calls are made — responses come from in-process fixtures or the tool's example response. - Sandbox tools count toward your plan's agentic tool limit like webhook tools. - Configure **sandbox fixtures** as a JSON array of `{ "match": { ...arguments }, "response": { ... } }` objects. The first fixture whose `match` keys are a subset of the tool arguments wins. - Use sandbox mode to prototype tool shapes in Playground before wiring a production webhook. Sandbox differs from the [demo webhook server](#demo-application): sandbox runs entirely inside Ogma; the demo server is a separate Node process you deploy. ## Request and response When the model decides to use the tool, Ogma POSTs a signed JSON payload to your HTTPS endpoint. ### Request body ```json { "tool": "check_order_status", "guildId": "123456789012345678", "ticketId": 42, "discordUserId": "987654321098765432", "channelId": "111222333444555666", "ticketSubject": "Where is my order?", "ticketTags": ["billing"], "arguments": { "orderId": "ORD-42" }, "timestamp": 1710000000 } ``` Required fields: `tool`, `guildId`, `arguments`, `timestamp`. Context fields (`ticketId`, `discordUserId`, `channelId`, `ticketSubject`, `ticketTags`) are included only when enabled for that tool in the dashboard. ### Request headers | Header | Value | | --- | --- | | `Content-Type` | `application/json` | | `Authorization` | `Bearer ` | | `X-Ogma-Signature` | `t=,v1=` | | `X-Ogma-Tool-Id` | Tool UUID from the dashboard | Any outbound headers you configure in the dashboard are sent on every call (values are stored encrypted and never shown again). ### Response rules - Return a small JSON object or array on success (HTTP 2xx). - Return 4xx with a short error JSON on expected failures; Ogma will surface a safe message. - Keep responses under 64 KB and aim for low latency (10 second timeout). For a walkthrough of the architecture, see the [companion blog post](https://blog.ogma.gg/remote-tool-calling-with-custom-tools). ## Verify signatures Ogma signs each webhook with HMAC-SHA256 over `timestamp + "." + raw JSON body`. Always verify the signature (and/or the Bearer token) before acting, and reject timestamps older than five minutes. Use the **raw request body string** when verifying. Do not re-serialize parsed JSON. ### Node.js: `@ogmasupport/webhook` Ogma publishes a small npm package for Node.js webhook handlers. Source and examples live in [ogma-open](https://github.com/KieranHolroyd/ogma-open) (`packages/webhook`). ```bash npm install @ogmasupport/webhook ``` ```typescript import { verifyOgmaWebhook, type OgmaWebhookPayload } from '@ogmasupport/webhook'; const secret = process.env.OGMA_SIGNING_SECRET!; export async function handleWebhook(request: Request): Promise { const rawBody = await request.text(); const signature = request.headers.get('X-Ogma-Signature') ?? undefined; const authorization = request.headers.get('Authorization') ?? undefined; if ( !verifyOgmaWebhook({ rawBody, signatureHeader: signature, authorizationHeader: authorization, secret }) ) { return Response.json({ error: 'Invalid signature' }, { status: 401 }); } const payload = JSON.parse(rawBody) as OgmaWebhookPayload; // Look up data and return JSON return Response.json({ status: 'ok', tool: payload.tool }); } ``` Package reference: [npm](https://www.npmjs.com/package/@ogmasupport/webhook) · [source on GitHub](https://github.com/KieranHolroyd/ogma-open/tree/main/packages/webhook) `verifyOgmaWebhook` accepts: | Option | Required | Description | | --- | --- | --- | | `rawBody` | yes | Raw request body string | | `signatureHeader` | yes | Value of `X-Ogma-Signature` | | `authorizationHeader` | no | Value of `Authorization`; bearer token must match `secret` when present | | `secret` | yes | Signing secret from the dashboard | | `maxAgeSeconds` | no | Max age for timestamp (default: 300) | ### Other languages To verify manually: 1. Parse `X-Ogma-Signature` as `t=,v1=`. 2. Reject if `abs(now - t) > 300`. 3. Compute `HMAC-SHA256(secret, t + "." + rawBody)` as lowercase hex. 4. Compare with `v1` using a constant-time comparison. 5. Optionally require `Authorization: Bearer ` to match as well. ## Security model **You are responsible for:** - Verifying signatures on every request - Protecting your signing secret and any outbound header values - Enforcing your own authorization and rate limits inside the webhook - Returning only the fields the support experience needs - Never putting instructions or prompt-like content in tool responses **Ogma provides:** - HTTPS-only URLs and SSRF protections (no localhost or private IP ranges) - Encrypted storage of secrets and headers at rest - Per-guild and per-tool rate limits - A hard cap on tool calls per model turn - Explicit treatment of tool output as *untrusted context* in the AI prompt ## Demo application Ogma ships a mock webhook server you can use to try agentic tools without building your own backend. It backs a fictional pizzeria plus generic SaaS lookups (orders, subscriptions, licenses, accounts). | | | | --- | --- | | **Hosted demo** | [https://demo.ogma.gg/](https://demo.ogma.gg/) | | **Import bundle** | [demo-agentic-tools.json](https://demo.ogma.gg/demo-agentic-tools.json) | | **Source** | [ogma-open](https://github.com/KieranHolroyd/ogma-open) (`apps/demo-agentic-tools-server`) | ### Quick start 1. In the dashboard, open **Agentic tools** → **Import** and upload the bundle (or paste the JSON from the link above). 2. After import, open each tool and set the **Webhook URL** to your demo server (`https://demo.ogma.gg/` when using the hosted demo, or `http://localhost:8787/` when running locally). 3. Copy the one-time **signing secret** shown after import (or rotate one from the tools page). 4. If you run the demo server yourself, set `OGMA_SIGNING_SECRET` in its environment to that same secret. 5. Enable one or two tools, use **Test tool** on the detail page, then try a Playground or live ticket question. The bundle defines eight tools — six **read** lookups and two **action** tools that require staff approval on live tickets. ### Read tools (run immediately) | Tool | Example user question | Test arguments | Sample response | | --- | --- | --- | --- | | `search_menu` | "How much is a Margherita?" | `{ "query": "margherita" }` | Menu items with prices and categories | | `check_order_status` | "Where is order ORD-42?" | `{ "orderId": "ORD-42" }` | Status, carrier, tracking, ETA | | `check_subscription` | "Is demo@example.com still on Pro?" | `{ "email": "demo@example.com" }` | Plan, status, renewal date | | `validate_license` | "Is OGMA-DEMO-2026 still valid?" | `{ "licenseKey": "OGMA-DEMO-2026" }` | Validity, product, expiry, seats | | `account_status` | "Is player123 banned?" | `{ "username": "player123" }` | Account standing and restrictions | | `get_store_info` | "What time do you close?" | `{}` | Hours, address, phone, promotions | **Demo order IDs** (for `check_order_status`): | Order | Status | Notes | | --- | --- | --- | | `ORD-42` | shipped | UPS tracking, ETA 2026-06-24 | | `ORD-100` | preparing | Good candidate for cancellation | | `ORD-88` | out_for_delivery | Demo Delivery driver en route | | `ORD-15` | delivered | Cannot be cancelled | | `ORD-404` | cancelled | Already cancelled | Example webhook response for `check_order_status`: ```json { "found": true, "orderId": "ORD-42", "status": "shipped", "carrier": "UPS", "trackingNumber": "1Z999AA10123456784", "eta": "2026-06-24" } ``` Other demo fixtures worth trying: - Subscriptions: `trial@example.com` (trialing) - Licenses: `OGMA-EXPIRED` (invalid) - Accounts: `banned_user` (banned) - Menu: `{ "category": "1" }` for all pizzas ### Action tools (`create_order`, `cancel_order`) #### `create_order` | | | | --- | --- | | **Type** | Action — staff must approve before the webhook runs on live tickets | | **Example question** | "Can I order a large Margherita and garlic bread for collection? Name is Jamie Lee." | | **Test arguments** | `{ "customerName": "Jamie Lee", "items": "Margherita (large), Garlic Bread (medium)", "fulfillment": "collection" }` | Creates a new in-memory order with status `received`. After staff approve on a live ticket, use `check_order_status` with the returned `orderId` (e.g. `ORD-101`) to verify it. Example response after approval: ```json { "ok": true, "found": true, "orderId": "ORD-101", "status": "received", "customerName": "Jamie Lee", "items": ["Margherita (large)", "Garlic Bread (medium)"], "total": 15, "fulfillment": "collection", "estimatedReady": "2026-06-21T19:35:00Z", "message": "Order ORD-101 created for collection." } ``` #### `cancel_order` | | | | --- | --- | | **Type** | Action — staff must approve before the webhook runs on live tickets | | **Example question** | "Please cancel my order ORD-100" | | **Test arguments** | `{ "orderId": "ORD-100", "reason": "Customer changed plans" }` | On a **live ticket**, the AI submits a pending approval instead of calling the webhook. Staff see the proposed `orderId` and `reason` on the ticket detail page and click **Approve & run** or **Reject**. After approval, the demo server marks the order `cancelled` in memory. Example response after approval: ```json { "ok": true, "found": true, "orderId": "ORD-100", "status": "cancelled", "cancelReason": "Customer changed plans", "message": "Order ORD-100 has been cancelled." } ``` The demo rejects cancellation when the order is already `delivered` or `cancelled` — try `{ "orderId": "ORD-15" }` in **Test tool** to see the error shape. Dashboard **Test tool** and **Playground** still call the webhook directly (no approval gate), so you can verify the endpoint before testing the full ticket flow. ## Testing tools 1. Create the tool in the dashboard — or **import** the [demo bundle](https://demo.ogma.gg/demo-agentic-tools.json) to get pre-built examples (see [Demo application](#demo-application) above). 2. Copy the one-time signing secret into your environment (and into `OGMA_SIGNING_SECRET` if you self-host the demo server). 3. Use the **Test tool** button on the tool detail page with the fixtures from the demo (e.g. `{ "orderId": "ORD-42" }` for `check_order_status`). 4. In **Playground**, ask a question that should trigger the tool — e.g. "Where is order ORD-42?" or "Cancel order ORD-100" — and confirm the end-to-end behavior. Only after both the direct test and a Playground flow look correct should you rely on the tool in production tickets. ## Call logging and sampling The tool detail page shows recent calls with source (ticket / playground / test), latency, status, and any error. You can set a **call log sampling rate** (0–100%): - Failures and dashboard tests are always logged. - Successful production calls (tickets and Playground) are sampled according to the rate. - Billing usage counts every successful production call regardless of sampling. Lower the rate for high-volume tools to reduce storage growth while still seeing failures and test traffic. ## Using tools in answers Ogma is instructed to: - Use tool results as one input among others. - Prefer documentation-backed claims when possible. - Never follow directives found inside tool responses. Design your tools to return factual data, not instructions. ## Action tools (approval required) Agentic tools can be **read** (default) or **action**: - **Read tools** run immediately when the AI calls them during a ticket. Use for lookups (order status, subscription tier, license validity). The demo tools `search_menu`, `check_order_status`, `check_subscription`, `validate_license`, `account_status`, and `get_store_info` are all read tools. - **Action tools** create a **pending approval** on the ticket instead of calling your webhook. Staff review the proposed arguments in the dashboard and click **Approve & run** or **Reject**. The webhook only fires after approval. The demo tools `create_order` and `cancel_order` are action tools. Use action tools for mutations: refunds, password resets, subscription changes, order cancellations, and anything else that changes state in your systems. During a ticket the AI is told the action is pending — it must not tell the user the action is complete until staff approve it. Dashboard **Test tool** and Playground still call the webhook directly so you can verify your endpoint without going through approval. Every request, approval, rejection, and executed call is logged on the ticket timeline. **Example flow with the demo:** a user asks to place an order for collection. Ogma calls `create_order` with `{ "customerName": "Jamie Lee", "items": "Margherita (large), ...", "fulfillment": "collection" }`, creates a pending approval, and tells the user staff will confirm it. After approval the webhook returns `{ "ok": true, "orderId": "ORD-101", "status": "received", ... }`. A follow-up `check_order_status` call shows the new order. To cancel an existing order: a user asks to cancel `ORD-100`. Ogma calls `cancel_order` with `{ "orderId": "ORD-100", "reason": "..." }`, creates a pending approval, and tells the user a team member will review it. Staff approve in the dashboard; the demo webhook runs and returns `{ "ok": true, "status": "cancelled", ... }`. A follow-up `check_order_status` call for the same ID then shows `cancelled`. ## Operator prerequisites Before anyone on your team can create agentic tools, the Ogma API environment must have `SECRETS_ENCRYPTION_KEY` set (a base64-encoded 32-byte secret). Losing this key means existing secrets can no longer be decrypted; you would need to rotate them after restoring a new key. See the in-app agentic tools documentation and your deployment notes for how to generate and configure this key. --- ## Tips Source: https://docs.ogma.gg/dashboard/tips # Tips Tips are short, high-signal answers that Ogma can use alongside your longer documentation. ## Where tips come from - **Auto-learn** — after a staff-resolved ticket closes, Ogma extracts a concise tip and adds it to the knowledge base. Remove unwanted tips in the `learned-tips` Discord channel or the dashboard. - **Manual** — you can create tips directly in the dashboard when you notice a repeated question that does not belong in a long doc. - **Import** — bulk-add tips from a JSON or JSONL file on the **Tips** page. Only tips that remain in the knowledge base (not removed after auto-learn) are searched during tickets and Playground tests. ## Tips vs Knowledge | | Tips | Knowledge | |--|------|-----------| | Length | 1–3 sentences | Paragraphs to pages | | Source | Resolved tickets or manual entry | Uploads, pastes, synced URLs | | Update cadence | Frequent, small edits | Occasional, larger updates | | Example | "Staging tokens expire every 6 hours" | Full guide on generating and rotating tokens | Use the right tool for the job. A 10-page integration guide belongs in Knowledge. The three-line gotcha your team repeats belongs in a tip. ## Managing tips in the dashboard On the **Tips** page you can: - Browse all tips in the knowledge base - Edit the title and body - Merge near-duplicate tips - Delete tips that are outdated or incorrect - Import and export tips in bulk - See which ticket a tip originally came from (when applicable) Edits are live immediately. ## Managing tips in Discord When auto-learn adds a tip, it appears in your `learned-tips` channel with a **Remove from knowledge base** button: - **Remove** — discards the tip from the searchable knowledge base (with a short confirmation step) You can still edit or remove tips later from the dashboard. ## Quality guidelines Good tips are: - Specific and verifiable - Free of time-sensitive details that will rot quickly - Written as the answer, not a prompt or instruction to the model If a "tip" is growing long or has many conditional branches, consider moving it into a proper document in Knowledge and linking to it. ## Import and export Use **Export tips** to download all tips as a JSON bundle. Use **Import tips** to bulk-add tips from: - A Ogma tips export file (`schemaVersion: 1`) - A JSON array of `{ "content": "...", "question": "..." }` objects - A JSONL file with one tip per line (`content` or legacy `tip` field) When importing into a guild that already has matching tips, choose **Skip duplicates** (default) or **Stop import** to fail the whole batch. ## Turning auto-learn off If you prefer a fully manual knowledge base, disable **Auto-learn** in **Settings**. Existing tips remain searchable until you remove them. You can continue to create tips manually. ## Batch learning from transcripts The **Learn from transcript channel** section on the Tips page scans a Discord channel for closed-ticket HTML transcript links and runs tip extraction over them in bulk using OpenAI Batch. ### What it costs Each HTML transcript page the AI successfully processes is billed at **£0.01 per page** on Plus and Enterprise. Important details: - **Separate from direct AI questions** — batch learning does not use your included Playground or /ask quota. - **Per HTML page processed** — you are charged when the AI runs on a transcript page, not when a tip is saved. Pages with no extractable tips still count if the AI ran successfully. - **Skipped pages are free** — already-learned tickets, transcripts without a staff reply, and tickets that are too short are not sent to the AI and are not billed. - **Failed API calls are free** — if OpenAI fails to process a page, you are not charged for it. - **Free plan** — usage billing requires a Plus or Enterprise subscription. After you scan a channel, the dashboard shows an **estimated cost** for the run (page count × unit price). Use **Scan channel** before **Run batch learning** to review the estimate. Usage appears on your Stripe invoice under batch tip learning. See [Billing](https://docs.ogma.gg/dashboard/billing) for current rates and usage. --- ## Background jobs Source: https://docs.ogma.gg/dashboard/jobs # Background jobs The **Background jobs** page shows long-running processing for your server. Open it from the dashboard sidebar under **Knowledge** or after starting a batch operation. Jobs poll automatically while work is in progress — you can leave the page and return later. ## Job types | Type | What it does | |------|--------------| | **Tip backfill** | Batch learning from HTML transcript links in a Discord channel — see [Tips → Batch learning](https://docs.ogma.gg/dashboard/tips#batch-learning-from-transcripts) | | **Knowledge URL sync** | Scheduled or manual re-fetch of synced URL sources | Each job shows state (**Queued**, **Running**, **Completed**, **Failed**), progress (processed / total), and timestamps. ## Tip backfill When you run **Learn from transcript channel** on the Tips page, Ogma submits an OpenAI Batch job and tracks it here. The job row shows: - How many HTML transcript pages were processed - How many tips were added - Estimated charge for the run Failed pages are not billed. See [Tips](https://docs.ogma.gg/dashboard/tips) for eligibility rules and pricing. ## URL sync jobs When a URL source is due for refresh, a sync job may appear while Ogma re-fetches and re-indexes the page. Check **Knowledge → Source health** if sync jobs fail repeatedly. ## Related - [Tips](https://docs.ogma.gg/dashboard/tips) - [Knowledge](https://docs.ogma.gg/dashboard/knowledge) - [Billing](https://docs.ogma.gg/dashboard/billing) --- ## Insights Source: https://docs.ogma.gg/dashboard/insights # Insights **Insights** shows how Ogma is performing for this server. Use it to find the highest-leverage improvements to your content and process. ## Time period | Plan | Available periods | |------|-------------------| | Free | Last 7 days | | Plus & Enterprise | Last 7, 30, or 90 days | Use the period selector at the top to change the window. All metrics and charts update for the selected range. ## Key metrics | Metric | What it means | What to do about it | |--------|---------------|---------------------| | AI deflection rate | Share of closed tickets resolved by the bot without escalation | High and stable is good. Sudden drops often mean a content gap or a change in what users ask. | | Top questions | The questions asked most often across tickets | If the same question keeps appearing and deflection is low, add or improve the matching doc or tip. | | Tips learned | New tips added in the period | Review auto-learn output and remove bad tips in **Tips** or `#learned-tips`. | | Knowledge gaps | Escalations where Ogma had no relevant content | Highest priority list for new docs — sort by frequency. | | CSAT satisfaction | Helpful vs not helpful ratings | Low CSAT with high deflection can mean correct but unhelpful tone or completeness. | ## Charts Insights includes visual breakdowns for the selected period: - **Ticket resolution** — how closed tickets were resolved (bot resolved, escalated, other) — all plans - **CSAT breakdown** — helpful vs not helpful share — all plans - **CSAT trend** — daily rating counts over time — **Plus & Enterprise only** - **Performance by ticket type** — closed, bot-resolved, and escalated counts grouped by type — **Plus & Enterprise only** Charts need enough ticket volume to render; empty states explain when data is not yet available. ## Knowledge gaps — take action Each knowledge gap row links to the source ticket. From the gap list you can: | Action | Effect | |--------|--------| | **Add to knowledge base** | Opens a pre-filled Knowledge add sheet from ticket context | | **Create tip** | Drafts a short tip from the conversation | | **Mark out of scope** | Removes the gap from the list without adding content | Gaps are the fastest path from "Ogma escalated" to "doc exists for next time." ## CSAT details - **CSAT tags** — most common tags from rating submissions (**Plus & Enterprise**) - **Recent CSAT comments** — written feedback after close (all plans) - **Deflected tickets** — recently closed tickets the bot resolved without staff (**Plus & Enterprise**) - **Staff performance** — per-staff closed tickets, claims, response/resolution times, message volume, and CSAT (**Plus & Enterprise**) ## Staff performance The **Staff performance** table attributes metrics to individual staff Discord accounts for the selected period: | Column | Meaning | |--------|---------| | Closed | Tickets where this staff member is recorded as the closer | | Claimed | Tickets they claimed | | Avg first response | Time from ticket open to their first public staff reply | | Avg resolution | Time from open to close for tickets they closed | | Messages | Staff replies sent (excluding internal notes) | | CSAT rate | Share of positive CSAT on tickets they closed | CSAT is attributed to the closer in v1 — use ticket detail and transcripts when you need finer attribution. ## Using Insights with other pages - Repeated question → **Knowledge** or **Tips** - Gap cluster → write the missing doc, test in **Playground** - CSAT drop on a type → review transcripts and Playground the same questions - Many tips learned → review and remove bad ones in **Tips** or `#learned-tips` ## Related - [Knowledge](https://docs.ogma.gg/dashboard/knowledge) — source health and freshness - [Tickets](https://docs.ogma.gg/dashboard/tickets) — individual histories - [Settings](https://docs.ogma.gg/dashboard/settings) — controls that influence deflection and tone - [Support ops](https://docs.ogma.gg/dashboard/support-ops) — SLAs and quality flags (Plus/Enterprise) --- ## Settings Source: https://docs.ogma.gg/dashboard/settings # Settings **Settings** controls how Ogma behaves for this server. The page is organized into section groups — use the sidebar rail to jump between them. **Setting up for the first time?** Use the [setup guide](https://docs.ogma.gg/getting-started/setup) — most teams configure basics in Discord with `/ogma-config setup` or `/ogma-config link`. Come back here for advanced options. Most **channel and ticket type** changes require you to run `/ogma autoconfig` in Discord after saving (unless you used `/ogma-config setup` or `/ogma-config link`, which apply changes immediately). ## Section groups | Group | Sections | |-------|----------| | **Setup** | Team & access, Channels, Tickets | | **Behavior** | AI & voice, AI model version, Business hours | | **Operations** | Routing & SLA, Automation, Alerts & follow-ups, Quality flags | | **Integrations** | Macros, Webhooks | | **Account** | Notifications, Data & retention | --- ## Team & access ### Staff roles Select Discord roles treated as **support staff**. Staff can see every ticket channel, run staff commands, and cause the bot to pause replies after they respond. Add the smallest set of roles that actually handle support. ### Management roles A second tier for **sensitive tickets**. Members with management roles (or Manage Server) can run `/lockdown` and `/unlock`. When a ticket is locked down, regular staff lose Discord channel access until lockdown is lifted. Configure management roles before using lockdown. See [Commands → Lockdown](https://docs.ogma.gg/discord/commands#lockdown). --- ## Channels Link or name the Discord channels Ogma uses: - **Ticket panel channel** — where users click to open tickets - **Transcripts**, **Staff review**, **Learned tips** — management channels - **Ticket types** — label, description, category, enabled state, role restrictions, max open per user **Deployment status** shows what is linked in Discord (Ready / Partial / Pending). Use **Map channels** to adopt existing channels instead of creating new ones. You need at least one enabled ticket type before `/ogma autoconfig` will succeed. --- ## Tickets | Setting | Description | |---------|-------------| | **Pre-open intake** | Optional form (subject/description) before the ticket channel opens | | **Sequential ticket names** | Name channels `ticket-1`, `ticket-2`, … instead of usernames | | **Open ticket limits** | Max open tickets per user per type (0 = unlimited) | | **Ticket inactivity** | Auto-close after N days without messages; optional warning message and longer period for escalated tickets | | **Post-close follow-up** | DM the user after close to check resolution (skipped for inactivity closes) | | **Transcript retention** | Quick link to [Data & retention](https://docs.ogma.gg/dashboard/data) — how long closed transcripts are kept | Inactivity closes archive a transcript, post the close message, and delete the channel — same as manual `/close` without a staff-selected reason. --- ## AI & voice | Setting | Description | |---------|-------------| | **Auto-learn** | Propose tips from staff-resolved tickets — see [Auto-learn](https://docs.ogma.gg/discord/auto-learn) | | **Staff reply cooldown** | Minutes Ogma waits after a staff message before replying again (0–1440; 0 disables time-based pause) — configured under **Team & access** | | **Voice & tone** | Soft style instruction for bot replies — test in Playground | | **Raw GPT commands** | Enable `/ask` and `/ogma askgpt` (bypass knowledge base; consume AI quota) | | **Tip extraction minimum messages** | Skip auto-learn for very short tickets (2–100 messages) | A link at the bottom of this section opens **AI model version** for upgrades. --- ## AI model version Choose which **production AI flow** powers ticket replies. Each version bundles a model lineup, reasoning settings, and prompt behavior. Ogma ships new versions as they are validated; you decide when to upgrade your server. | Concept | Meaning | |---------|---------| | **Platform default** | The production version Ogma assigns to new servers and to servers that have not pinned a version | | **Active version** | The flow currently used for this server | | **Pinned version** | A version you explicitly selected — your server will not auto-follow platform default changes | ### How upgrades work - Upgrades apply to **new ticket conversations only**. Existing open tickets keep the flow they started with. - Only **production** versions appear in the dashboard. Draft and staging versions are platform-internal. - When a newer production version is available, billing managers see a banner across the dashboard with a link to review and upgrade. - Test representative questions in **Playground** after upgrading to confirm the new flow behaves as expected. ### When to upgrade Upgrade when Ogma announces a new production version and the changelog describes improvements you want (for example, better reasoning or updated models). If your answers are already good, staying on your current version is fine — pinned servers are not forced to move. --- ## Business hours Configure timezone, weekly schedule, away message, and options: - **Allow tickets outside hours** — block or allow panel clicks when closed - **Pause AI outside hours** — send away message instead of searching docs - **Expected response time** — optional minutes value included in away messages when set - **Include next open time** — append when support reopens to the away message --- ## Routing & SLA Plus and Enterprise only. See [Support ops](https://docs.ogma.gg/dashboard/support-ops). - **Auto-assignment** — manual, round robin, or load balanced - **SLA targets** — first response and resolution minutes, breach alerts --- ## Automation JSON automation rules (Plus/Enterprise). Documented in [Automation rules](https://docs.ogma.gg/dashboard/automation-rules). --- ## Alerts & follow-ups Plus and Enterprise only. See [Support ops → Manager alerts and Proactive follow-ups](https://docs.ogma.gg/dashboard/support-ops#manager-alerts). --- ## Quality flags Plus and Enterprise only. Lists open tickets flagged for escalation, negative CSAT, or low-confidence bot replies. --- ## Macros and Webhooks Plus and Enterprise only. See [Support ops → Macros and Webhooks](https://docs.ogma.gg/dashboard/support-ops#macros). --- ## Notifications Configure who receives billing and usage notifications: | Notification | Channels | Plans | |--------------|----------|-------| | **Usage alerts** | Email, Discord DM | All plans — fires at 80% and 100% of included limits | | **Weekly digest** | Email, Discord DM | Plus and Enterprise — summary of ticket activity | Only billing managers (owner, admin, or Discord server owner) can change notification preferences. Trial servers also see in-dashboard banners and inline warnings before billable overage actions (batch tip learning, knowledge ingest, etc.). See [Billing → Free trial and overage](https://docs.ogma.gg/dashboard/billing#free-trial-and-overage). --- ## Data & retention Link to the full [Data & retention](https://docs.ogma.gg/dashboard/data) page for transcript retention, ticket export, and audit logs. --- ## Applying channel changes After you save channel or ticket type changes, run: ``` /ogma autoconfig ``` in Discord. Safe to re-run on an existing setup. ## Related - [Support ops](https://docs.ogma.gg/dashboard/support-ops) - [Automation rules](https://docs.ogma.gg/dashboard/automation-rules) - [Commands](https://docs.ogma.gg/discord/commands) - [Setup guide](https://docs.ogma.gg/getting-started/setup) --- ## Support ops Source: https://docs.ogma.gg/dashboard/support-ops # Support ops **Support ops** is a set of routing, SLA, alerting, and integration features for teams on **Ogma Plus** or **Enterprise**. Configure them in dashboard **Settings** under the **Operations** and **Integrations** section groups. Free plan servers can still use business hours and expected response time in away messages; other support ops features require an upgrade. ## Where to configure | Settings section | What it controls | |------------------|------------------| | **Routing & SLA** | Auto-assignment and first-response / resolution targets | | **Automation** | JSON rules for ticket triggers — see [Automation rules](https://docs.ogma.gg/dashboard/automation-rules) | | **Alerts & follow-ups** | Manager alerts and proactive stale-ticket nudges | | **Quality flags** | Open tickets flagged for escalation, negative CSAT, or low-confidence replies | | **Macros** | Canned responses for `/macro` in Discord | | **Webhooks** | HTTPS endpoints for ticket and SLA events | Save settings after changes. Assignment and SLA tracking apply to new activity immediately; macros and webhooks are live as soon as saved. --- ## Routing and assignment Enable **auto-assignment** to assign new tickets to staff automatically. | Mode | Behavior | |------|----------| | **Manual only** | Staff claim tickets from the [staff queue](https://docs.ogma.gg/dashboard/tickets#staff-queue) or run `/claim` in Discord | | **Round robin** | Rotates through eligible staff in order | | **Load balanced** | Assigns to the staff member with the fewest open assigned tickets | Automation rules can also run `{ "type": "assign_round_robin" }` on triggers like `ticket_opened`. See [Automation rules](https://docs.ogma.gg/dashboard/automation-rules). --- ## SLAs When SLAs are enabled, Ogma tracks: - **First response** — time until a staff member sends the first reply - **Resolution** — time until the ticket is closed Set targets in minutes (minimum 5). Enable **Alert on SLA breach** to notify managers when a target is missed (works with **Manager alerts** below). SLA breaches can also trigger [automation rules](https://docs.ogma.gg/dashboard/automation-rules) with the `sla_breach` trigger and [webhooks](#webhooks) with the `sla.breach` event. --- ## Staff queue The **Staff queue** page lists open tickets for triage — unclaimed, yours, escalated, awaiting staff, or awaiting customer. Claim or release tickets from the queue; the same assignment is reflected in Discord (`/claim`, `/unclaim`). See [Tickets → Staff queue](https://docs.ogma.gg/dashboard/tickets#staff-queue). --- ## Manager alerts Notify managers when support metrics need attention: | Setting | Fires when | |---------|------------| | **Queue depth threshold** | Open unclaimed or escalated tickets exceed the count | | **CSAT drop threshold** | Satisfaction percentage drops by the configured amount | | **Escalation spike threshold** | Escalations in a short window exceed the count | | **SLA breach alerts** | An SLA target is missed | Alerts are delivered through your configured manager notification paths (see dashboard settings for the server). --- ## Proactive follow-ups Separate from the post-close follow-up DM in **Settings → Tickets**, proactive follow-ups nudge customers on **stale open tickets**: - **Stale after (hours)** — no activity for this long triggers a message in the ticket channel - **Reopen on negative CSAT** — optionally reopen or follow up when a user rates 👎 after close - Custom messages for stale tickets and negative CSAT --- ## Quality flags The **Quality flags** section lists open tickets that need review: - **Escalated** — reached staff without a confident bot answer - **Negative CSAT** — user rated not helpful after close - **Low confidence** — bot replied but retrieval scores were weak Resolve flags from Settings after you have reviewed the ticket. Jump to the ticket from the list. --- ## Macros Create canned responses with a **shortcut** (for example `refund-policy`) and **content**. Staff insert them in Discord with: ``` /macro refund-policy ``` Macros require Plus or Enterprise. See [Commands → Staff shortcuts](https://docs.ogma.gg/discord/commands#staff-shortcuts). ### Suggested macros On **Plus** and **Enterprise**, Ogma scans recent closed tickets for repeated staff replies (same normalized text in at least three messages across two or more tickets). Pending suggestions appear above your macro list: - **Accept** — pick a shortcut and create the macro - **Dismiss** — hide the suggestion Suggestions run on a daily schedule; they never create macros without staff approval. --- ## Webhooks Send signed HTTPS POST requests to your endpoints when events occur: | Event | When | |-------|------| | `ticket.opened` | New ticket channel created | | `ticket.escalated` | Ticket escalated to staff | | `ticket.closed` | Ticket closed | | `csat.negative` | User submits a low rating | | `sla.breach` | SLA target missed | Each webhook has a name, URL, enabled flag, event selection, and optional signing secret. Verify payloads using the secret on your server. Webhooks complement [agentic tools](https://docs.ogma.gg/dashboard/agentic-tools) — use agentic tools when the AI needs live lookup data during a ticket; use webhooks when your systems need to react to ticket lifecycle events. --- ## Related - [Automation rules](https://docs.ogma.gg/dashboard/automation-rules) - [Tickets](https://docs.ogma.gg/dashboard/tickets) - [Commands](https://docs.ogma.gg/discord/commands) - [Billing](https://docs.ogma.gg/dashboard/billing) — Plus and Enterprise plans --- ## Automation rules Source: https://docs.ogma.gg/dashboard/automation-rules # Automation rules Automation rules run actions when tickets match triggers you define. Configure them in **Settings → Automation** as a JSON array (up to 25 rules per server). Available on **Plus** and **Enterprise** plans. ## Rule shape Each rule is an object with: | Field | Required | Description | | --- | --- | --- | | `id` | No | Stable identifier. If omitted, the server assigns one when saved. | | `enabled` | No | Defaults to `true`. Disabled rules are ignored. | | `name` | No | Label for logs and escalation messages. Max 80 characters. | | `trigger` | Yes | When to evaluate this rule (see below). | | `match` | For `message_contains` | Case-insensitive substring to find in new ticket messages. Max 200 characters. | | `ticketTypeId` | No | If set, the rule only runs for that ticket type id. | | `actions` | Yes | One or more actions to run when the rule matches. | ## Triggers | Trigger | When it fires | | --- | --- | | `ticket_opened` | A new ticket channel is created. | | `ticket_escalated` | A ticket is escalated to staff. | | `message_contains` | A customer or staff message is posted and contains `match`. | | `csat_negative` | The ticket creator submits a low CSAT rating after close. | | `sla_breach` | A configured SLA target is missed. | ## Actions | Action | Effect | | --- | --- | | `{ "type": "add_tag", "tag": "billing" }` | Adds a tag to ticket metadata (max 40 characters). | | `{ "type": "escalate" }` | Escalates the ticket and pauses bot replies. | | `{ "type": "assign_round_robin" }` | Assigns the ticket using your **Routing & SLA** assignment settings. | Each rule must include at least one valid action. Invalid rules are dropped when you save. ## Example ```json [ { "id": "billing-escalate", "enabled": true, "name": "Escalate billing keywords", "trigger": "message_contains", "match": "refund", "ticketTypeId": "billing", "actions": [ { "type": "add_tag", "tag": "refund" }, { "type": "escalate" } ] }, { "id": "assign-on-open", "enabled": true, "name": "Assign new tickets", "trigger": "ticket_opened", "actions": [{ "type": "assign_round_robin" }] } ] ``` Paste a JSON **array** of rules into the editor. The server validates and normalizes the payload when you click **Save settings**. ## Tips - Test assignment rules separately under **Settings → Routing & SLA** before chaining `assign_round_robin` in automation. - Use `ticketTypeId` to scope noisy keyword rules to a single queue. - Escalation from automation records the rule name in the escalation reason for staff context. **Related:** [Support ops](https://docs.ogma.gg/dashboard/support-ops) · [Settings](https://docs.ogma.gg/dashboard/settings) · [Tickets](https://docs.ogma.gg/dashboard/tickets) · [Insights](https://docs.ogma.gg/dashboard/insights) --- ## Billing Source: https://docs.ogma.gg/dashboard/billing # Billing Billing is per **Discord server** (guild). Each server has its own plan, subscription, usage quotas, and team seats. ## Plans | Resource | Free | Ogma Plus (£15/mo) | Enterprise (£60/mo) | |----------|------|---------------------|-------------------------| | Support tickets | Unlimited | Unlimited | Unlimited | | LLM tokens / month | 100,000 | Currently Unlimited | Currently Unlimited | | Direct AI questions / month | 10 | 300 | 2,000 | | Embeddings indexed per month | 1,000 | 25,000 | 100,000 | | URL sources (live sync) | 1 | 5 | 50 | | Team members | 2 | 10 | 50 | | Agentic tools | 2 | 10 | 25 | **Ogma Plus** is the self-serve paid plan with a **14-day free trial** on the monthly subscription fee. **Enterprise** is **£60/mo** — the top tier with the highest limits and optional **zero-access encryption**. Contact sales to upgrade or to enable zero-access setup. Self-serve Enterprise checkout may be enabled for your server when offered by the Ogma team. See [Zero-access encryption](https://docs.ogma.gg/dashboard/zero-access) for what is protected, how setup works, and what your security team should prepare. ### Usage periods Included allowances reset each **billing period**: - **Free** (no active subscription) — calendar month (1st through last day). - **Plus & Enterprise** — your Stripe subscription period (`currentPeriodStart` → `currentPeriodEnd`). The **Billing** page always shows usage for the current period for that server. ### Free vs paid when you hit a limit | Meter | Free plan | Plus & Enterprise | |-------|-----------|-------------------| | Direct AI questions | Not metered from ticket bot replies; Playground and /ask count here | Usage beyond included is **billed** at **£0.10 per question**, not blocked | | LLM tokens (all AI usage) | **Blocked** at 100,000 tokens per period | Unlimited | | Knowledge indexing (embeddings) | New indexing **blocked** when allowance exhausted | Same — **hard cap** on all plans; uploads fail when remaining embeddings are insufficient | | Batch tip learning | Not available | **£0.01 per HTML page** processed (see [Tips](https://docs.ogma.gg/dashboard/tips)) | On Free, **LLM token** and **indexing** limits are hard-blocked when exhausted. **Direct AI questions** (Playground, /ask) are tracked separately and enforced mainly through **hourly rate limits**, not only the monthly included count. On paid plans, **direct AI question** overage is billed when Playground or `/ask` usage exceeds included amounts. **Indexing** still stops when you run out of included embeddings. Support tickets are **not** limited or billed per month on any plan. ## Pay-as-you-go overage rates These rates apply on **Ogma Plus** and **Enterprise** when billable usage exceeds included allowances: | Usage | Overage rate | Blocked or billed? | |-------|--------------|-------------------| | Direct AI questions | £0.10 per question | **Billed** — Playground, `/ask`, `/ogma askgpt` | | Knowledge indexing | £0.001 per embedding chunk | **Blocked** at ingest when over limit (rate shown for estimates) | | Batch tip learning | £0.01 per HTML transcript page | **Billed** per page processed | Rates appear on the **Billing** page with current-period usage and estimated charges. The marketing homepage lists the same rates under pricing. Batch tip learning is billed separately from direct AI questions and indexing — see [Tips → Batch learning from transcripts](https://docs.ogma.gg/dashboard/tips#batch-learning-from-transcripts). ## How overage is billed 1. Ogma tracks usage per meter throughout the billing period. 2. Usage within your plan's included allowance is free. 3. Billable overage (direct AI questions, batch tip learning) is converted to a single Stripe usage total and added to your subscription invoice. All overage types share one Stripe meter. Internally, each meter has its own unit price (see table above); Ogma converts the combined pence total into Stripe usage units at **£0.01 per unit** before reporting. You do not need to configure meters yourself — overage is attached automatically when you subscribe to Plus or Enterprise. ### Invoices and estimates Open **Billing** for the server to see: - Current period consumption for direct AI questions and embeddings - Overage units beyond included limits (where billing applies) - Estimated overage charges for the period - Your plan subscription fee (when not in trial) Use **Manage subscription** in Stripe to download invoices, update your payment method, or cancel. ## Free trial and overage Ogma Plus includes a **14-day free trial** on the **monthly plan fee only**. Important: - **Overage is not deferred.** Usage beyond your included limits during the trial is charged to your payment method on file as it accrues — not after the trial ends. - **Trial overage is invoiced separately** from the subscription meter path (Stripe does not bill meter usage while a subscription is in `trialing`). Small amounts may accumulate until they reach a minimum threshold (typically **£1.00**) before a one-off invoice is issued; larger overage is invoiced sooner. - The dashboard shows warnings when you are on a trial and approaching or exceeding included limits, including before billable actions such as batch tip learning or knowledge ingest. When the trial ends, your plan subscription fee starts and overage continues on the normal subscription invoice cycle. ## What counts as a direct AI question Each time you run **Playground**, **`/ask`**, or **`/ogma askgpt`**, it counts against this meter. These are user-initiated AI completions outside normal knowledge-backed ticket support. **Knowledge-backed replies in tickets are not counted** toward direct AI questions. They still use your LLM and are subject to hourly rate limits, but they do not consume this monthly quota or incur direct-AI overage. Hourly rate limits also apply per guild, channel, and user. ## What counts as knowledge indexing Usage is measured in **embedding chunks** — the searchable sections Ogma creates when content is indexed. A single upload, paste, URL import, or URL refresh can consume many chunks depending on document length. Re-indexing the same document on refresh counts again. Ingest is blocked when `remaining` embeddings for the period are less than the chunk count required. ## Viewing usage Open **Billing** for the server. The page shows current period consumption for: - Direct AI questions (Playground, /ask) - Embeddings indexed - Batch tip learning pages (if used) - Overage beyond included limits and estimated charges (where billing applies) If you are close to a limit, you will see warnings in the dashboard. Indexing limits block the corresponding action on all plans. Direct AI usage continues subject to hourly rate limits; paid plans bill overage rather than cutting off at the monthly included count. Usage alerts (email or Discord at 80% and 100% of included limits) can be configured under **Settings → Notifications**. ## Upgrading and managing 1. Select the server in the dashboard. 2. Open **Billing**. 3. Choose a plan and complete checkout (Plus includes a 14-day trial on the subscription fee). Use **Manage subscription** to: - Update payment method - Change plan - Download invoices - Cancel (you keep access until the end of the paid period) Plan changes are effective immediately for limits and features on that server. ## Team access Invite teammates under **Team** for the same server. Team members can access the dashboard for that server according to their role. Dashboard access is separate from Discord staff roles — assign staff roles in **Settings** for in-ticket permissions. See [Team members](https://docs.ogma.gg/dashboard/team). --- ## Data & retention Source: https://docs.ogma.gg/dashboard/data # Data & retention The **Data & retention** page controls how long ticket transcripts are kept and how you export support history for compliance or backup. Open it from **Settings → Data & retention** (`?section=data`), the **Open data & retention** link on the Tickets page, or directly at `/guilds/:guildId/data`. ## Transcript retention Closed ticket transcripts are stored for the period you choose, then **permanently deleted** from storage and removed from dashboard access. | Retention | Plans | |-----------|-------| | 30 days | Free (maximum), Plus, Enterprise | | 60 or 90 days | Plus, Enterprise | | Unlimited | Enterprise | Configure retention on the Data page or in **Settings → Data & retention**. The setting applies to all closed tickets for that server going forward; already-expired transcripts are not restored if you increase retention later. See also [Tickets → Transcripts and retention](https://docs.ogma.gg/dashboard/tickets#transcripts-and-retention). ## Data lifecycle | Data type | Retention behavior | |-----------|-------------------| | **Ticket transcripts** | Kept for your configured period, then deleted | | **Knowledge sources** | Remain until you delete them or URL sync replaces content | | **Learned tips** | Remain until you remove them from **Tips** | | **Open tickets** | Live in Discord until closed; transcript saved on `/close` | ## Ticket export Export closed ticket transcripts from the **Tickets** page: - Choose a **date range** (from / to) for the export - Optionally enable **PII redaction** when sharing data externally - Export is **not** limited to your current search or status filters — only the date range applies Available on all plans. ## Audit log export On Plus and Enterprise, download dashboard audit events (settings changes, team updates, billing actions) as JSON for a selected date range. View recent events in the dashboard or download the full export from **Data & retention → Audit log export**. ## Related - [Tickets](https://docs.ogma.gg/dashboard/tickets) - [Settings](https://docs.ogma.gg/dashboard/settings) - [Zero-access encryption](https://docs.ogma.gg/dashboard/zero-access) — Enterprise encryption at rest - [Billing](https://docs.ogma.gg/dashboard/billing) — retention limits by plan --- ## Zero-access encryption Source: https://docs.ogma.gg/dashboard/zero-access # Zero-access encryption (Enterprise) **Zero-access encryption** is an Enterprise feature. Your Discord support data is encrypted at rest, wrapped in **your** key management system (KMS). Ogma operators cannot read ticket content, transcripts, knowledge, or user identifiers in our internal admin tools—even when supporting your account. Your team keeps working exactly as before in Discord and in your server’s dashboard. Encryption and decryption happen automatically for authorized guild operations. What changes is who can see plaintext outside your organization. ::: info Contact sales Zero-access encryption is enabled by the Ogma team for Enterprise servers (not self-serve checkout). If you need zero-access encryption, [contact us](mailto:support@ogma.gg) or reach out through your account channel. ::: ## What problem this solves Most SaaS products can read customer data at rest. That is fine for many teams, but regulated or security-sensitive organizations often need a stronger guarantee: **the vendor should not be able to browse support conversations in their own backend.** Zero-access encryption is built for that requirement. It does not replace your Discord permissions or dashboard access controls—it adds a layer so Ogma’s platform staff are locked out of content, while your guild team retains normal access. ## What you control | You hold | Purpose | |----------|---------| | **KMS key** | Wraps and unwraps a per-server data encryption key (DEK). Without your KMS, encrypted blobs cannot be read. | | **LLM API key** | Powers AI replies and embeddings for your server. Stored encrypted; used only for your guild’s requests. | Ogma never needs plaintext access to your KMS or LLM credentials after setup. Credentials you provide are stored encrypted in our database. ## What stays protected When zero-access is enabled for a server, the following categories are encrypted at rest: ### Support conversations - Ticket message content, author names, and attachment URLs - Ticket metadata (for example subject lines) - Ticket event messages and actor references - Transcript previews and archived transcript files in object storage ### Knowledge base - Document titles and body text (uploads, pasted content, synced docs, learned tips) ### Feedback and quality signals - CSAT comments and submitter references - Tip extraction content and reasoning text - User feedback messages and display names (for members of your server) ### Identity handling - Discord user IDs are stored as **pseudonyms** (one-way tokens for queries) with the real ID kept in an encrypted vault. This preserves ticket workflows without storing raw IDs in searchable columns. ### What is not encrypted by default - **Vector embeddings** used for knowledge search remain plaintext in the database by default. This keeps semantic search fast and accurate. A stricter mode to encrypt embeddings is available at setup time; it trades some search convenience for maximum at-rest protection (see [Embeddings](#embeddings-and-search) below). Non-sensitive operational fields (timestamps, ticket status, channel IDs, billing counters, etc.) remain unencrypted so the product can function. ## What Ogma operators cannot do For zero-access servers, Ogma’s internal **platform admin** views show redacted placeholders instead of real content—tickets, messages, knowledge, tips, and feedback appear as `[encrypted — zero-access tier]` or similar. Additionally, for these servers we disable: - Recording AI prompt/response content in error monitoring - Feedback webhook payloads that would leak message text - Other telemetry paths that would store customer content outside your encryption boundary Your guild’s own dashboard and Discord flows continue to decrypt data for authorized team members and the bot at runtime. ## How encryption works (plain language) Each Enterprise server with zero-access enabled gets its own **data encryption key** (DEK)—a random key used to encrypt fields and files. 1. When zero-access is enabled, Ogma generates a DEK. 2. The DEK is **wrapped** (encrypted) using your KMS key. Only the wrapped form is stored in our database. 3. When the bot or dashboard needs to read or write protected data, Ogma unwraps the DEK through your KMS (in memory), encrypts or decrypts the specific fields, and discards the key material from the process when done. ``` Your KMS key │ ▼ wraps / unwraps Per-server DEK ──► encrypts ticket text, knowledge, transcripts, etc. ``` If someone copied our database without access to your KMS, they would see ciphertext—not your users’ messages. Field-level encryption uses industry-standard **AES-256-GCM** envelopes. Each encrypted value is independently authenticated. ## Supported KMS providers During setup you choose where the DEK is wrapped: | Provider | Typical use | |----------|-------------| | **AWS KMS** | Production deployments on AWS; use an IAM role or supply credentials Ogma can use to `Encrypt`/`Decrypt`. | | **Google Cloud KMS** | GCP-hosted keys and workload identity. | | **Azure Key Vault** | Azure environments with Key Vault keys. | | **HashiCorp Vault** | Transit engine keys for teams standardizing on Vault. | | **Local (development only)** | Wraps DEKs with the platform `SECRETS_ENCRYPTION_KEY`. For staging and engineering—not for production customer data. | You provide: - **Key ID / ARN** (provider-specific identifier) - **Region** (where required, e.g. AWS) - **Optional credentials JSON** if Ogma cannot use ambient cloud IAM The setup wizard includes a **Test KMS connection** step that performs a wrap/unwrap cycle before anything is enabled. ## Bring your own LLM (BYOK) Enterprise servers with zero-access enabled use **your** LLM provider credentials for: - AI replies in tickets and related flows - Text embeddings for knowledge ingest and search (unless strict embedding encryption is enabled) Supported providers: **OpenAI**. You may supply a custom base URL if you use a proxy or compatible endpoint. Ogma’s shared platform API keys are not used for zero-access guilds. If your key is revoked or misconfigured, AI features for that server stop until you update credentials. ## Setup process Setup is performed by Ogma platform staff in the **Zero-access setup wizard** (Admin → Guild billing → **Set up encryption** for Enterprise servers). ### Before you start 1. **Enterprise plan** assigned to the server (£60/mo — contact sales). 2. **KMS key** created with permissions for Ogma to wrap and unwrap small payloads (the DEK). 3. **LLM API key** with sufficient quota for your expected ticket and knowledge volume. 4. **Maintenance window** for the one-time **backfill** that re-encrypts existing tickets, messages, knowledge, transcripts, and related rows. ### Wizard steps 1. **Overview** — Confirms prerequisites and explains the impact on operator access. 2. **Encryption keys** — KMS provider, key ID, region, optional credentials; test connection. 3. **LLM provider** — Provider, API key, optional base URL. 4. **Review** — Confirm settings; optional strict embedding encryption. 5. **Enable & backfill** — Turns on zero-access and encrypts historical data. You receive counts of tickets, messages, documents, and transcripts processed. If zero-access is already active, the same page allows **re-running the backfill** after key rotation or recovery operations. ### What we need from you Send your security or platform team’s preferred secure channel: - KMS provider and key identifier - Region (if applicable) - Whether Ogma should use IAM/workload identity or explicit credentials - LLM provider and API key (or a process to rotate keys through Ogma support) - Whether you require strict encrypted embeddings Ogma completes the wizard on your behalf and confirms backfill results. ## After enable: what changes for your team **In Discord** — No change. Users open tickets; staff reply; Ogma answers from knowledge as usual. **In your server dashboard** — No change for authorized team members. Tickets, knowledge, Playground, and transcripts display normally. **In Ogma platform admin** — Support staff cannot read your content when helping with billing or infrastructure issues. They can still see non-sensitive metadata (server name, plan, ticket counts, timestamps) to operate the platform. ## Embeddings and search Knowledge search relies on vector embeddings. By default on zero-access Enterprise servers, **document text is encrypted** but **embeddings are stored in plaintext** so pgvector similarity search continues to work without loading entire libraries into memory. ::: warning Residual semantic exposure Plaintext embeddings can leak approximate topic information to someone with database access, even if document text is encrypted. For most teams, encrypted content plus operator lockout is the right balance. ::: At setup you may enable **Encrypt knowledge embeddings** for maximum at-rest protection. In that mode, search behavior may differ (similarity runs after decrypting vectors in memory). Discuss trade-offs with Ogma before enabling in production. ## Key rotation and recovery - **LLM key rotation** — Provide a new API key through your Ogma contact; we update the encrypted credential without re-encrypting all content. - **KMS key rotation** — Coordinate with Ogma to re-wrap the server DEK with a new KMS key version and re-run backfill if needed. - **Loss of KMS access** — If your KMS key is deleted or permissions revoked, Ogma cannot unwrap the DEK. **Encrypted data becomes unrecoverable.** Treat your KMS key with the same care as a database backup encryption key. We recommend documenting which KMS key wraps each production server and including it in your disaster-recovery runbooks. ## Security review checklist Use this list when evaluating zero-access Enterprise internally: - [ ] Per-server DEK wrapped by customer-controlled KMS - [ ] Ticket, knowledge, transcript, and PII-class fields encrypted at rest - [ ] Discord IDs tokenized; raw IDs not stored in plaintext query columns - [ ] Ogma operator admin cannot decrypt guild content - [ ] AI and feedback telemetry disabled for content exfiltration paths - [ ] Customer-supplied LLM credentials; platform keys not used - [ ] One-time backfill encrypts historical data and R2 transcript objects - [ ] Embeddings strategy documented (default vs strict mode) ## Frequently asked questions ### Is zero-access the same as end-to-end encryption in Discord? No. Discord messages in ticket channels are visible to your staff and the bot under normal Discord permissions. Zero-access protects data **at rest in Ogma’s systems** and blocks **Ogma operator** access—not encryption of Discord’s own transport or your staff’s view. ### Can Ogma support debug a ticket content issue? Not by reading message bodies in admin. Support relies on your team’s description, reproducible steps, and non-content logs (errors, timestamps, configuration). For deep debugging you may temporarily reproduce in a non-zero-access staging server. ### Does encryption slow down tickets? Wrapping and field encryption add small overhead. In practice, ticket flows remain responsive; the backfill is the only operation that may take noticeable time on large histories. ### Can we enable zero-access encryption later? Yes. Assign Enterprise, complete the zero-access setup wizard, and run backfill. Plan the migration window with Ogma so existing data is encrypted before you rely on operator lockout. ### Can we disable zero-access encryption? Contact Ogma. Moving off zero-access requires a deliberate key and data migration plan; do not delete KMS keys while data is still encrypted. --- **Related:** [Billing](https://docs.ogma.gg/dashboard/billing) · [Settings](https://docs.ogma.gg/dashboard/settings) · [FAQ](https://docs.ogma.gg/help/faq) --- ## FAQ Source: https://docs.ogma.gg/help/faq # FAQ ## How do I set up Ogma from scratch? Follow the [setup guide](https://docs.ogma.gg/getting-started/setup). It is written for complete beginners. - **New server:** run `/ogma-config setup` in Discord (one form, done). - **Existing support channels:** run `/ogma-config link` in Discord. - **Prefer the website:** configure in dashboard **Settings**, then run `/ogma autoconfig` in Discord. You do not need the dashboard to get started. ## What is Ogma? AI support for Discord. Users open private ticket channels from a panel. Ogma replies from your documentation and learned tips. When it cannot help, it escalates to staff. Your team works in Discord; you configure and review in the dashboard. ## Do users need anything besides Discord? No. All support interactions happen in Discord. The dashboard is only for your team. ## How do I test what Ogma will answer? Use **Playground** on the **Knowledge** page. Type questions the way your users do. You will see the exact answer and which content was used. Do not rely on `/ogma askgpt` for this. It ignores your knowledge base. ## Why did Ogma not reply in a ticket? Common causes: - A staff member sent a message recently and the cooldown is still active. - The ticket has already escalated and staff are expected to handle it. - **Hourly AI rate limits** were hit (per guild, channel, or user). - The bot does not have permission to send messages in that channel. - Business hours are configured to skip AI outside your support window. Check **Insights**, the ticket transcript, and **Billing** usage. Test the same question in Playground. ## Can a user have more than one open ticket? By default, one open ticket per user per ticket type. You can increase or remove this limit per type in **Settings**. ## How often do URL sources refresh? Minimum and default refresh intervals depend on plan (you can set a custom interval per source within the minimum): | Plan | Minimum interval | Default for new URL sources | Max sources | |------|------------------|----------------------------|-------------| | Free | 24 hours | 24 hours | 1 | | Plus | 1 hour | 3 hours | 5 | | Enterprise | 15 minutes | 1 hour | 50 | See [Knowledge](https://docs.ogma.gg/dashboard/knowledge). ## What happens when I hit a limit? Behavior depends on your plan and meter: - **Free — indexing:** new uploads, pastes, and URL syncs blocked when embedding allowance is exhausted. - **Free — direct AI questions:** Playground and /ask count toward the monthly quota; enforced mainly through **hourly rate limits**, not a hard monthly stop. - **Plus & Enterprise — direct AI questions:** Playground and /ask usage beyond included is overage billed at £0.10 per question (hourly rate limits still apply). - **Plus & Enterprise — indexing:** still **hard-blocked** when embedding allowance is exhausted — no pay-as-you-go ingest path today. Limits reset each **billing period** (calendar month on Free; Stripe subscription period on paid plans). During a **free trial**, overage is still charged when you exceed included amounts — the trial waives the plan fee only. See [Billing](https://docs.ogma.gg/dashboard/billing). ## Is billing per server? Yes. Each Discord server has its own plan and monthly quotas for metered usage (direct AI questions, embeddings, and similar). Knowledge, tickets, tips, and settings are isolated per server. **Support tickets are unlimited on every plan, including Free.** See [Billing](https://docs.ogma.gg/dashboard/billing). ## What is zero-access encryption? Enterprise includes optional encryption at rest with **your** KMS key that blocks Ogma operators from reading your ticket and knowledge content in platform admin. Your team’s dashboard and Discord experience stay the same. It is enabled during Enterprise setup (contact sales). See [Zero-access encryption](https://docs.ogma.gg/dashboard/zero-access) for setup requirements and what is encrypted. ## Where do transcripts go? On `/close`, a transcript is posted to your `ticket-transcripts` channel (except lockdown closes) and is available in the dashboard under **Tickets**. Retention is controlled under **Settings → Data & retention** or [Data & retention](https://docs.ogma.gg/dashboard/data). ## Can staff add someone to a ticket? Yes. Use `/add user:@someone` in the ticket channel. The ticket owner or a member with a configured **staff role** can add people. Only configured **staff roles** can remove with `/remove` (Manage Channels alone is not enough for `/remove`). ## Do I need to run autoconfig after every setting change? - **First-time setup in Discord:** `/ogma-config setup` or `/ogma-config link` applies everything — no separate autoconfig step. - **Changes in the dashboard:** run `/ogma autoconfig` when you change ticket types, staff roles, categories, or management channels. - **Other settings** (cooldown, voice, auto-learn, support ops, inactivity, AI model version) take effect without autoconfig. ## What is the staff queue? The **Staff queue** in the dashboard lists open tickets for triage — filter by unclaimed, yours, escalated, or awaiting staff/customer. Claim tickets from the queue or with `/claim` in Discord. See [Tickets → Staff queue](https://docs.ogma.gg/dashboard/tickets#staff-queue). ## What is support ops? On **Plus** and **Enterprise**, support ops adds auto-assignment, SLAs, macros, webhooks, manager alerts, proactive follow-ups, quality flags, and automation rules. See [Support ops](https://docs.ogma.gg/dashboard/support-ops). ## What is AI model version? Ogma ships **production AI flows** — bundled model choices, reasoning settings, and reply behavior. In **Settings → AI model version** you can see which flow your server uses and upgrade when a newer production version is available. - Upgrades apply to **new ticket conversations** only. - If you pick a version explicitly, your server is **pinned** and will not auto-follow platform default changes until you upgrade again. - When a newer version exists, billing managers see a dashboard banner with a link to review the changelog. See [Settings → AI model version](https://docs.ogma.gg/dashboard/settings#ai-model-version). ## What is ticket lockdown? Management roles can run `/lockdown` to restrict a sensitive ticket so only the customer and management see the Discord channel. Regular staff lose access until `/unlock`. Closed lockdown tickets stay management-only in the dashboard. See [Commands](https://docs.ogma.gg/discord/commands#lockdown). ## Where is the Discord command list in the dashboard? Open **Discord commands** in the sidebar for a searchable list filtered to commands your account can run, with options and availability badges. The docs site has the same reference at [Commands](https://docs.ogma.gg/discord/commands). ## Does the free trial cover overage? No. The Plus **14-day trial** waives the monthly subscription fee only. Usage beyond included limits during the trial is still billed as overage. The dashboard shows warnings before billable actions. See [Billing → Free trial and overage](https://docs.ogma.gg/dashboard/billing#free-trial-and-overage). ## How do I export tickets or audit logs? Use **Settings → Data & retention** (or the link from Tickets) for transcript retention and **audit log export** (Plus/Enterprise). **Ticket transcript export** is available from the Tickets page by date range — all plans. See [Data & retention](https://docs.ogma.gg/dashboard/data). ## What are background jobs? Long-running work such as **tip backfill** (batch learning from transcripts) and **URL sync** appears on **Background jobs** with progress and status. See [Background jobs](https://docs.ogma.gg/dashboard/jobs). --- ## Troubleshooting Source: https://docs.ogma.gg/help/troubleshooting # Troubleshooting Fixes for the most common issues. Within each section, work through the steps in order. ## Bot is not replying in a ticket Check in this order: 1. **Cooldown** — has a staff member sent a message in the last N minutes? Look at recent messages or lower **Staff reply cooldown** in Settings. 2. **Already escalated** — is the ticket marked for staff? If a human is expected, reply in the channel instead of waiting for the bot. 3. **Billing** — open **Billing** for the server. Are you hitting **hourly AI rate limits** or out of embedding allowance? Monthly direct AI usage is tracked but not a hard monthly stop — see [Billing](https://docs.ogma.gg/dashboard/billing). 4. **Permissions** — does the bot have Send Messages and Read Message History in the ticket channel and the start channel? 5. **Business hours** — are you outside your configured hours with "skip AI" enabled? 6. **Content** — test the exact question in **Playground**. If there is no good answer, add or improve the relevant doc or tip. ## `/ogma autoconfig` or `/ogma-config setup` fails | Error or message | Likely cause | Fix | |------------------|--------------|-----| | Need Manage Server | You are not an admin on the Discord server | Run the command with a user who has Manage Server | | Missing **Manage Channels** (or other permissions) | The bot role is missing permissions | **Server Settings → Roles → Ogma** → enable the permissions listed in the error, then run the command again | | No enabled ticket types | No ticket types are enabled (dashboard path) | Enable at least one type in **Settings**, save, then run `/ogma autoconfig` — or use `/ogma-config setup` in Discord instead | | Category full | Discord category has too many channels (max 50) | Remove unused channels or pick a different category | After fixing, run `/ogma-config setup`, `/ogma-config link`, or `/ogma autoconfig` again (whichever you used for setup). See the [setup guide](https://docs.ogma.gg/getting-started/setup) for step-by-step instructions. ## `/ogma-config link` found no channels - Your channel names may not match common patterns (`#support`, `#ticket-transcripts`, etc.). - **Fix:** run `/ogma-config setup` to create channels, **or** use the dashboard **Settings → Channels → Use channels this server already has** to map them manually, **or** rename channels to match common names and run `/ogma-config link` again. ## Ticket panel is missing or buttons do not appear - Run `/ogma-config view` and follow the “Get started” or “Finish setup” steps shown. - If you used the dashboard, save **Settings** and run `/ogma autoconfig`. - Confirm the bot can send messages in the start channel (check channel permissions and category overwrites). - Look for the panel message from Ogma; if it is missing, setup may have failed — check for permission errors when you ran setup. ## A URL source will not sync - The page must be publicly crawlable without a login. - Check the row status on the **Knowledge** page for the specific error. - Some sites require special headers or block common crawlers; hosting a mirror or exporting the content and uploading it can be more reliable. Free plans refresh at least every 24 hours; Plus and Enterprise allow shorter minimum intervals (see [Knowledge](https://docs.ogma.gg/dashboard/knowledge)). ## "User already has an open ticket" By default only one open ticket is allowed per user per type. Options: - Close the existing ticket with `/close`. - Increase or remove the per-user limit for that type in **Settings**, then re-run `/ogma autoconfig` if you changed categories. - Ask the user to use a different type if appropriate. ## Auto-learn is not creating tips Requirements: - **Auto-learn** must be enabled in Settings. - A staff member must have sent at least one message in the ticket. - The conversation must be long enough (very short threads are skipped). If those are met and you still see nothing: - Check the `learned-tips` channel for recent summaries (with **Remove from knowledge base** if needed). - Look at the ticket in the dashboard to see if a tip was proposed and perhaps removed. - Confirm that the close was performed by staff (owner-only closes may not trigger learning). ## Team members cannot see the server in the dashboard - They must have accepted the team invite sent to their email, or been added by Discord ID. - They must sign in with the Discord account that received the invite. - They must be a team member for that specific server (or have Manage Server / a configured staff role). Dashboard access is separate from Discord permissions. They still need Manage Server on the Discord server to run `/ogma autoconfig`. ## Cannot sign in or switch servers - Use the Discord account that has Manage Server on the server you want to manage. - If you were invited to a server's team, open the invite link from the email first, then sign in. - Clear any workspace or account switcher state and try again. ## Need more help Use the **Feedback** link in the dashboard header, or email [support@ogma.gg](mailto:support@ogma.gg). Ogma support is available **10am–5pm, Monday–Friday**. For product questions, recent tickets and Playground sessions are usually the best clues for what to document next. --- ## Team members Source: https://docs.ogma.gg/dashboard/team # Team members Team members are people who can access the dashboard for a specific Discord server. ## Who can access the dashboard A user can open a server's dashboard if they are: - A **team member** for that server (owner, admin, or member role) - A Discord user with **Manage Server** on that server - Assigned a configured **staff role** in Settings Billing changes require team **owner** or **admin**, or the Discord server owner. ## Inviting teammates 1. Select the server in the dashboard. 2. Open **Team**. 3. Search for an existing Ogma user by name or Discord ID, or invite by email. Email invites expire after 14 days. The recipient must sign in with Discord after accepting. ## Roles | Role | Can manage billing | Can invite/remove members | |------|-------------------|---------------------------| | Owner | Yes | Yes (including admins) | | Admin | Yes | Yes (members only) | | Member | No | No | Members can use the dashboard but cannot change billing or team membership. ## Category permissions Owners and admins always have full dashboard access. For **members**, you can grant read and/or write access to each dashboard area: | Area | Includes | |------|----------| | **Support** | Overview, tickets, staff queue, Discord commands, tool action approvals | | **Knowledge** | Knowledge base, playground, agentic tools, tips, background jobs | | **Analytics** | Insights | | **Server admin** | Settings, data & retention, billing (view), team (view) | New members start with **no category access** until an owner or admin grants permissions on the Team page. Existing members were migrated with full access. On the Team page, owners can change a member between **Admin** and **Member** roles. Only members with the Member role can have category permissions edited. Click the permissions summary or **Permissions** button to open the editor. Write access is required for changes (for example editing settings or managing tickets). Team management (invite/remove) still requires owner or admin role. ## Discord staff vs dashboard team Being a dashboard team member does not grant Discord permissions in tickets. Assign **staff roles** in **Settings → Team & access** so the bot recognizes support staff in Discord. Removing someone from the team revokes dashboard access only. It does not change their Discord roles. ---