Complete Setup & Feature Guide
UnrealHQ lets you create AI character bots that live in Discord. Each character is its own Discord bot — with its own name, avatar, personality, memories, and codex entries. Your characters are live on Discord where your friends can talk to them too, or you can chat with them right here on the web.
Whether you want a roleplay companion, a group chat personality, a writing partner, or just a character you've designed to hang out in your server — this is the place to build it.
BYOA stands for Bring Your Own API. Instead of paying us a subscription, you get an API key from an AI provider (like ElectronHub, OpenAI, or Anthropic) and plug it in. The bot uses your key to generate responses.
Here's the fastest path from zero to a working character bot in your Discord server:
Go to the Dashboard and sign up with email or connect your Discord account. Either works — you can link Discord later if you start with email.
Sign up at ElectronHub (or any provider you prefer), create an API key, and save it in your Dashboard settings.
Go to the Character Creator. At minimum, fill in a name, description, and first message. You can always add more depth later.
Head to the Discord Developer Portal, create a new application, grab the bot token, and enable the Message Content intent. (Full walkthrough in the Create a Discord Bot section below.)
Paste your bot token in the Bot Manager. Link your character to the bot using the dropdown. Hit Start. Your bot is live.
Click the Invite link in the Bot Manager to add your bot to a Discord server. @mention it in any channel and start chatting!
UnrealHQ supports multiple AI providers. You can set your key from the Dashboard settings page, or with Discord commands:
| Provider | Command | Notes |
|---|---|---|
| ElectronHub | /setkey electronhub sk-... | Default provider. Many models, great pricing. |
| OpenAI | /setkey openai sk-... | GPT-4o, GPT-4, o1, etc. |
| Anthropic | /setkey anthropic sk-ant-... | Claude models. Great for creative writing. |
| OpenRouter | /setkey openrouter sk-or-... | Access 100+ models from one key. |
| Custom | /setkey custom your-key | Any OpenAI-compatible endpoint. |
/setmodel model-name to choose your model. Examples: /setmodel claude-3-5-sonnet-20241022 or /setmodel gpt-4o. Different models have different strengths — Claude is usually preferred for RP/creative writing, GPT-4o for speed and general conversation.
If you're just starting out, ElectronHub is the easiest choice — it gives you access to models from multiple providers through a single key, and pricing is very competitive. If you already have an OpenAI or Anthropic key, those work too.
Each character lives as its own Discord bot application. Here's the step-by-step:
Once you have a Discord bot token, head to the Bot Manager and paste it in the registration field. UnrealHQ will:
In the Bot Manager, use the character dropdown to assign one of your characters to the bot. Then hit Start. Your bot comes online in Discord immediately, speaking as that character with its full personality, codex entries, and commands.
You can swap characters anytime — just stop the bot, change the linked character, and start it again.
/setkey — you as the creator only handle the bot token.
Limit: Each creator can register up to 3 bots.
Starfall Haven lets you build AI characters with serious depth. Every field maps to the TavernCardV2 spec, so you can import and export characters freely.
Name — Your character's display name. Max 20 characters. This is how they'll appear in Discord.
Description — Who the character is. Background, appearance, history, relationships. This is the core identity block and the most important field. Be detailed here.
Personality — How they behave. Speech patterns, quirks, emotional tendencies, mannerisms. Bullet traits work well: "sarcastic, fiercely loyal, uses 90s slang."
Scenario — The current situation. Where are we? What's happening? This sets the stage. Example: "{{char}} and {{user}} are roommates in a cramped Tokyo apartment. It's raining outside."
First Message — The opening message when someone first talks to the bot. This sets the tone and should establish the scene. Write it in the character's voice.
Example Dialogue — Sample exchanges showing how the character should talk. The AI uses these as style references. Format them like this:
{{user}}: Hey, what's up?{{char}}: *leans against the doorframe* Oh, you know. Just contemplating the void. The usual Tuesday stuff.
System Prompt — Advanced override. If set, this replaces the auto-assembled system prompt entirely. For power users who want total control over what the AI sees. Most people should leave this blank and let UnrealHQ build the prompt from the other fields.
{{char}} becomes the character's name, {{user}} becomes the person talking. Use them in your description, scenario, and example dialogue so the character works regardless of actual names.
The codex is where character depth really comes alive. It's a collection of entries that get injected into the AI's context based on different rules. Think of it as your character's encyclopedia — but the AI only reads the relevant pages.
These entries are always injected into every message's context, no matter what. Use them for core world facts, fundamental character traits, and rules that should never be forgotten.
These entries are flagged for future semantic matching — the AI will eventually pull them in based on conversation meaning, not just exact keywords. For now they work like keyword entries but are marked for the upcoming smart matching upgrade.
These entries only inject when specific keywords from their trigger list appear in the conversation. This is classic codex behavior — precise and token-efficient.
Primary Keys — Comma-separated trigger words. At least one must match for the entry to fire.
Secondary Keys — If set, at least one secondary key must ALSO match (in addition to a primary). Great for precise two-condition triggers. Example: primary "sword" + secondary "broken" only fires when both concepts appear.
Priority — Higher priority entries are injected first when there's a token budget concern. Put your most important lore at higher priority.
Position — "Before Character" means the AI sees this info before the character definition. "After Character" places it later in context. Generally, world-building goes before and character-specific details go after.
Case Sensitive — Whether triggers match exact case or ignore it. Usually leave this off unless you need to distinguish between "Rose" (a character) and "rose" (a flower).
You can import codex entries in two ways:
Characters can have multiple first messages (greetings). Each greeting sets up a different scenario or starting point. When a user first talks to the bot, it uses the default greeting — but creators can define alternatives for variety.
Add alternate greetings in the Character Creator under the "Alternate Greetings" section. Each one is a complete opening message, just like your main first message.
Creators can define custom commands unique to their character. These are special triggers that make the bot respond in a specific way.
Add them in the Character Creator under "Custom Commands." Each command has a trigger word and a system instruction that tells the AI how to respond when that command is used.
!recipe command that tells the AI: "Generate a creative recipe in {{char}}'s dramatic Italian style, with commentary about the user's cooking skills."
Custom commands override built-in commands if they share the same trigger name. This lets you personalize the experience per character.
UnrealHQ has a multi-layered memory system that goes far beyond "remember last 30 messages." Your characters actually remember what happened.
1. Recent Messages — The last N messages (default 30, configurable with /setcontext). These are sent to the AI as-is, with full detail.
2. Summaries — When older messages pile up, the AI compresses them into narrative summaries. These get injected as "memory blocks" so the character remembers the gist without needing every message. Think of it as the character's long-term memory.
3. Personal Notes — You can pin your own notes to a channel via the Memory Manager. Pinned notes are injected as established facts — perfect for things like "we agreed the character's birthday is March 5th" or "my OC's name is Luna."
After a configurable number of unsummarized messages (default 50), the bot automatically generates a summary and archives older messages. This happens silently in the background — the conversation just keeps flowing.
!summarize 40 10 — Summarize the last 40 messages, keep the 10 most recent visible.!memory — Check your memory stats (total messages, summaries, context window size).
The Memory Manager page gives you full control:
UnrealHQ bots are built for group dynamics. They don't just talk to one person — they're aware of everyone in the room.
The bot saves every message in a channel to its history, even messages not directed at it. This means:
Even in a shared channel, each user's pinned memory notes are private. Your notes about the RP are injected only into YOUR interactions with the bot.
By default, bots only respond when @mentioned or replied to. Auto-respond mode lets the bot participate naturally, responding to any message in the channel as if they're part of the conversation.
| Command | What It Does |
|---|---|
!auto on | Enable auto-respond in this channel |
!auto off | Disable auto-respond |
!auto cooldown 30 | Wait at least 30 seconds between auto-responses |
!auto chance 50 | Only respond to ~50% of messages (more natural) |
!auto | Show current auto-respond settings |
/setkey.
Personas let you define how YOU present yourself to the bot. It's your RP identity — a name and description injected into the bot's context so it knows who it's talking to.
Go to the Dashboard and open Settings. Under User Personas, create a persona with a name (max 30 characters) and a description of your character. You can create multiple personas for different scenarios.
In the Memory Manager, select which persona to use in each channel. The bot will see your persona description alongside the conversation, so it knows to treat you as that character.
Once your bot is working, you can publish it so other people can discover and invite it to their servers.
In the Bot Manager, each bot card has a publish section. Write a short public description, then click Publish. Your bot will appear on the Browse page for anyone to find.
Published bots get their own profile page with:
Configure profile settings in the Bot Manager — choose a theme, write a longer description, and add tags.
Creators can block specific Discord users from interacting with their bots. If someone is being disrespectful or abusing your character, you can blacklist their Discord User ID.
In the Bot Manager, expand the "Blocked Users" section on any bot card. Enter a Discord User ID (the 17-20 digit number, not their username) and click Block. The bot will silently ignore all messages from that user.
In Discord, enable Developer Mode (User Settings → Advanced → Developer Mode). Then right-click any user and select "Copy User ID."
The Control Room settings panel lets you configure everything in one place.
| Setting | Default | What It Does |
|---|---|---|
| Provider | — | ElectronHub, OpenAI, Anthropic, OpenRouter, or Custom |
| API Key | — | Your provider API key (stored securely, masked in UI) |
| Model | — | The AI model name (e.g., gpt-4o, claude-3-5-sonnet) |
| Temperature | 0.8 | Creativity. Lower = focused/predictable. Higher = creative/varied. Set to whatever you want. |
| Max Tokens | 500 | Maximum response length in tokens (~4 chars per token). No hard cap — set as high as your provider allows. |
| Context Window | 25 | How many recent messages the bot sees. Increase for longer memory, decrease to save tokens. |
| Custom Base URL | — | For self-hosted or custom OpenAI-compatible endpoints |
All settings can also be changed via Discord commands (/setkey, /setmodel, /settemp, /setcontext).
| Command | Description |
|---|---|
/setkey [provider] <key> | Set your API key |
/setmodel <model> | Change AI model |
/settemp <0.1-2.0> | Set creativity/temperature |
/setcontext <5-100> | Set context window size |
/settings | View all your current settings |
/reload | Refresh character data from database |
| Command | Description |
|---|---|
!memory | View memory stats for this channel |
!summarize [count] [keep] | Manually summarize messages |
| Command | Description |
|---|---|
!auto on/off | Toggle auto-respond mode |
!auto cooldown <seconds> | Minimum wait between auto-responses |
!auto chance <1-100> | Response probability percentage |
| Command | Description |
|---|---|
!commands | List all available commands |
!relationship | Character analyzes your relationship |
!thoughts | Character's internal monologue about you |
!analyze | Personality analysis from the character's POV |
!augen | Generate an alternate universe scenario |
!comfort | Words of encouragement from the character |
!future | Character imagines your shared future |
!lovemap | Things the character loves about you |
!petnames | Generate pet names for you |
!youin3words | Character describes you in 3 words |
!describe | Detailed description of an item or outfit |
!msg | Simulate receiving a text message |
!twt | Character writes a tweet |
!ig | Character writes an Instagram caption |
| Command | Description |
|---|---|
/delete <count> | Delete the bot's last N messages from history (requires Manage Messages permission) |
/hide <count> | Hide (exclude) messages from context without deleting (requires Manage Messages permission) |
Back up your chat history from the Memory Manager. Each channel can be exported individually in two formats:
Bring your existing conversations to UnrealHQ! The Vault accepts JSONL and JSON (array or wrapped format). The importer auto-detects the format.
Starfall Haven supports full TavernCardV2 import and export. Import a character card and all fields come across — description, personality, scenario, example dialogue, codex entries, and alternate greetings.
Got an existing codex file? Click "Import Codex (.json)" in Starfall Haven. It handles all common World Info formats, including older ones with different field names. Choose to merge with existing entries or replace them entirely.
/setkey/setmodel)/settemp doesn't control length — max tokens does, set it in Dashboard settings)/setcontext) so the bot sees more historyYes! Characters and bots are separate. One character can be linked to multiple bots, and you can swap characters on a bot anytime.
Use the Invite button in the Bot Manager. If you created your own invite link in the Discord Developer Portal, that works too.
Not from us. Your only limit is your API provider's rate limits and your credit balance. UnrealHQ doesn't throttle or cap messages.
No. The bot uses each message sender's own API key. If someone doesn't have a key set, the bot silently skips their message. Everyone who wants the bot to respond to them needs to set their own key with /setkey.