Overview
This guide walks you through building a Discord bot that connects to TierZero, enabling your team to receive alerts, interact with AI responses, and manage incidents directly within Discord channels.The Discord bot acts as a bridge between Discord and TierZero.
Architecture
Your Discord bot will:- Listen to Discord events (mentions, reactions, guild joins, guild leaves)
- Forward relevant events to TierZero via webhooks
- Receive commands from TierZero to send messages, reactions, and updates
- Handle authentication and rate limiting
Outbound Events
Discord → TierZero
Bot mentions, reactions, server joins
Inbound Commands
TierZero → Discord
Send messages, add reactions, fetch data
Prerequisites
- Discord Developer Application and Bot Token
- HTTPS endpoint for webhook reception
- TierZero API key (32-character hex string)
Data Model
Core Objects
All timestamps are RFC-3339/ISO-8601 format in UTC. Field order is illustrative; implementations may reorder fields.
Server (Discord Guild)
Server (Discord Guild)
Represents a Discord server where your bot is installed.
Channel
Channel
Text or voice channels within a server. Channel types include
GUILD_TEXT, GUILD_VOICE, GUILD_PUBLIC_THREAD, GUILD_PRIVATE_THREAD, and others.Fields marked with
? in the spec (like parent_id?, archived?) are optional and may be null or omitted.Thread
Thread
Specialized channels that are treated as threads (includes all Channel fields plus thread-specific metadata).
User
User
Discord members with profile information.
Message
Message
Chat messages with full context and metadata.
Reaction
Reaction
Emoji reactions on messages with count and metadata.For standard Unicode emojis:
Security & Authentication
Transport Security
- HTTPS 1.2+ required for all communications
- TLS certificate validation enforced
Authentication Header
Include this header in all requests (both directions):Replay Protection
Each outbound event includes anidempotency_key (UUID-v4). TierZero rejects duplicates within 24 hours.
Webhook Envelope Format
All webhook calls use this consistent envelope structure:Outbound Events (Discord → TierZero)
Your bot should send these events to TierZero when they occur in Discord:1. Server Joined
Trigger:GUILD_CREATE - Bot added to a new Discord serverEndpoint:
POST https://api.tierzero.ai/discord/webhooks/server_joined
2. Bot Mentioned
Trigger:MESSAGE_CREATE - User mentions your bot in a messageEndpoint:
POST https://api.tierzero.ai/discord/webhooks/bot_mentioned
3. Reaction Added
Trigger:MESSAGE_REACTION_ADD - User adds a reaction to a messageEndpoint:
POST https://api.tierzero.ai/discord/webhooks/reaction_added
4. Server Left
Trigger:GUILD_DELETE - Bot removed from serverEndpoint:
POST https://api.tierzero.ai/discord/webhooks/server_left
Inbound Webhooks (TierZero → Discord)
Your bot must expose these webhook endpoints for TierZero to call:Read Operations
Get Users
Get Users
Path:
POST /webhooks/get_usersLists all users in servers where the bot is present.Get Server Channels
Get Server Channels
Path:
POST /webhooks/get_server_channelsLists all channels in a specific server.Get Channel Messages
Get Channel Messages
Path:
POST /webhooks/get_channel_messagesRetrieves messages from a specific channel.Get Channel Threads
Get Channel Threads
Path:
POST /webhooks/get_channel_threadsLists all threads in a channel.Get Thread Messages
Get Thread Messages
Path:
POST /webhooks/get_thread_messagesRetrieves messages from a specific thread.Write Operations
Send Message
Send Message
Path:
POST /webhooks/send_messageSends a message to a channel or thread.This single endpoint handles both channel and thread messages. For thread messages,
thread_id will be included in the request data instead of channel_id.Add Reaction
Add Reaction
Path:
POST /webhooks/add_reactionAdds a reaction to a message.Edit Message
Edit Message
Path:
POST /webhooks/edit_messageEdits a message sent by the bot.Delete Message
Delete Message
Path:
POST /webhooks/delete_messageDeletes a message sent by the bot.Error Handling
Your bot should handle these HTTP status codes appropriately:| Code | Meaning | Response |
|---|---|---|
400 | Invalid request | {"error": "VALIDATION_ERROR", "details": "Missing channel_id"} |
401 | Authentication failed | {"error": "UNAUTHORIZED", "details": "Invalid API key"} |
404 | Resource not found | {"error": "NOT_FOUND", "details": "Channel not found"} |
429 | Rate limit exceeded | {"error": "RATE_LIMITED", "retry_at": "2025-07-02T19:10:00Z"} |
5xx | Server error | {"error": "INTERNAL_ERROR", "details": "Temporary failure"} |
Best Practices
- Queue requests internally to avoid hitting limits
- Use the same
idempotency_keyfor retries - Implement backoff strategies for rate limit responses
- Cache frequently accessed data to reduce API calls
Implementation Example
Here’s a basic TypeScript implementation structure using discord.js:Troubleshooting
TierZero API Errors
Symptoms: 401, 403, or 5xx responses from TierZero Solutions:- Verify
x-tierzero-discord-keyheader is correct - Check request payload matches documented schema
- Ensure HTTPS is used for all requests
Support
For technical support with your Discord bot integration:- Discord API: Consult the Discord Developer Documentation