Skip to main content

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.
Represents a Discord server where your bot is installed.
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.
Specialized channels that are treated as threads (includes all Channel fields plus thread-specific metadata).
Discord members with profile information.
Chat messages with full context and metadata.
Emoji reactions on messages with count and metadata.
For standard Unicode emojis:

Security & Authentication

Store your API key securely and never expose it in client-side code or logs.

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 an idempotency_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 server
Endpoint: POST https://api.tierzero.ai/discord/webhooks/server_joined

2. Bot Mentioned

Trigger: MESSAGE_CREATE - User mentions your bot in a message
Endpoint: POST https://api.tierzero.ai/discord/webhooks/bot_mentioned

3. Reaction Added

Trigger: MESSAGE_REACTION_ADD - User adds a reaction to a message
Endpoint: POST https://api.tierzero.ai/discord/webhooks/reaction_added

4. Server Left

Trigger: GUILD_DELETE - Bot removed from server
Endpoint: 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

Path: POST /webhooks/get_usersLists all users in servers where the bot is present.
Path: POST /webhooks/get_server_channelsLists all channels in a specific server.
Path: POST /webhooks/get_channel_messagesRetrieves messages from a specific channel.
Path: POST /webhooks/get_channel_threadsLists all threads in a channel.
Path: POST /webhooks/get_thread_messagesRetrieves messages from a specific thread.

Write Operations

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.
Path: POST /webhooks/add_reactionAdds a reaction to a message.
Path: POST /webhooks/edit_messageEdits a message sent by the bot.
Path: POST /webhooks/delete_messageDeletes a message sent by the bot.

Error Handling

Your bot should handle these HTTP status codes appropriately:
Implement exponential backoff for 5xx errors and respect the retry_at timestamp for 429 responses.

Best Practices

  1. Queue requests internally to avoid hitting limits
  2. Use the same idempotency_key for retries
  3. Implement backoff strategies for rate limit responses
  4. 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-key header is correct
  • Check request payload matches documented schema
  • Ensure HTTPS is used for all requests

Support

For technical support with your Discord bot integration: