dannystocker/navidocs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
navidocs/INTEGRATIONS-SIP-DISCORD.md

49 KiB
Raw Export PDF Permalink Blame History

Discord API Research & Integration Strategy

Comprehensive 8-Pass Methodology Analysis

Document Version: 2.0 Created: 2025-11-14 Status: Complete Technical Analysis Research Methodology: 8-Pass IF.Search Analysis Target Integration: NaviDocs Bot & Team Notifications

TABLE OF CONTENTS

  1. Pass 1: Signal Capture
  2. Pass 2: Primary Analysis
  3. Pass 3: Rigor & Refinement
  4. Pass 4: Cross-Domain Integration
  5. Pass 5: Framework Mapping
  6. Pass 6: Specification Details
  7. Pass 7: Meta-Validation
  8. Pass 8: Deployment Planning
  9. Implementation Reference

PASS 1: SIGNAL CAPTURE

Objective: Identify all Discord API endpoints, capabilities, and signal types

1.1 Gateway API (WebSocket Real-Time Communication)

Gateway Endpoints:

  • Wss Protocol: WebSocket Secure connection for real-time messaging
  • URL: wss://gateway.discord.gg/?v=10&encoding=json
  • Purpose: Establish persistent connection to Discord service
  • Data Frames: JSON-formatted events sent bidirectionally
  • Ping Interval: Server sends PING every 20-60 seconds (client must PONG)
  • Heartbeat: Client must send heartbeat every 41-45 seconds

Core Gateway Events:

  • READY - Logged in, receive user info + guild list
  • MESSAGE_CREATE - New message in channel
  • MESSAGE_UPDATE - Message edited
  • MESSAGE_DELETE - Message deleted
  • GUILD_CREATE - Server joined or synced
  • GUILD_UPDATE - Server settings changed
  • GUILD_MEMBER_ADD - User joined server
  • GUILD_MEMBER_UPDATE - User role/status changed
  • VOICE_STATE_UPDATE - User entered/left voice channel
  • PRESENCE_UPDATE - User online status changed
  • INTERACTION_CREATE - Slash command, button click, modal submit

Intents (Required Subscriptions):

  • GUILDS - Guild create, update, delete
  • GUILD_MEMBERS - Member add, update, remove
  • GUILD_MESSAGES - Message create, update, delete
  • DIRECT_MESSAGES - DM events
  • MESSAGE_CONTENT - Access to message text (requires privileged intent)
  • GUILD_VOICE_STATES - Voice channel changes

1.2 REST API (HTTPS Request-Response)

Base URL: https://discord.com/api/v10

Core Resource Endpoints:

Endpoint Method Purpose
/channels/{id} GET, PATCH, DELETE Get/modify/delete channel
/channels/{id}/messages GET, POST Fetch/send messages
/channels/{id}/messages/{msg_id} GET, PATCH, DELETE Get/edit/delete message
/channels/{id}/messages/{msg_id}/reactions POST, DELETE Add/remove emoji reactions
/guilds/{id} GET, PATCH Get/modify server
/guilds/{id}/members/{user_id} GET, PATCH, DELETE Get/modify/kick member
/guilds/{id}/roles GET, POST, PATCH Manage roles
/guilds/{id}/channels GET, POST, PATCH Manage channels
/users/{id} GET Get user profile
/users/@me GET Get current bot/user info
/users/@me/guilds GET List guilds bot is in

1.3 Webhooks API

Webhook Types:

  • Incoming Webhooks: External services → Discord (send-only)
  • Channel Webhooks: Bot posts messages as custom user
  • Token-based: No authentication needed (public URL)
  • No guild permission checks (webhook URL grants access)

Webhook Endpoint:

POST https://discord.com/api/webhooks/{webhook_id}/{webhook_token}

Payload:

{
  "content": "Message text",
  "embeds": [{
    "title": "Embed Title",
    "description": "Embed description",
    "color": 16711680,
    "fields": [{
      "name": "Field Name",
      "value": "Field Value",
      "inline": false
    }]
  }],
  "username": "Custom Bot Name",
  "avatar_url": "https://example.com/avatar.png"
}

Webhook Limits:

  • 10 webhooks per channel
  • Message size: 4,000 characters (content) + embeds
  • Rate limit: 10 requests per 10 seconds per webhook

1.4 Slash Commands (Interactions API)

Command Registration:

PUT https://discord.com/api/v10/applications/{app_id}/commands

Command Types:

  1. CHAT_INPUT - Slash commands (e.g., /query warranty)
  2. USER - Right-click context menu on user
  3. MESSAGE - Right-click context menu on message

Slash Command Example:

{
  "name": "find_document",
  "type": 1,
  "description": "Search NaviDocs documents",
  "options": [{
    "name": "query",
    "type": 3,
    "description": "Search term (warranty, service, manual)",
    "required": true
  }, {
    "name": "boat_id",
    "type": 4,
    "description": "Boat ID (optional, uses default if not specified)",
    "required": false
  }]
}

Command Handler Response:

{
  "type": 4,
  "data": {
    "content": "Found 3 documents matching 'warranty'",
    "embeds": [{
      "title": "Engine Warranty",
      "description": "Yanmar 4JH110, expires 2027-12-15"
    }]
  }
}

Response Types:

  • 4 - CHANNEL_MESSAGE_WITH_SOURCE (respond in channel)
  • 5 - DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE (acknowledge, respond later)
  • 9 - DEFERRED_UPDATE_MESSAGE (acknowledge button click)

1.5 Bot API (OAuth2 & Permissions)

OAuth2 Flow:

https://discord.com/api/oauth2/authorize?
  client_id={bot_client_id}
  &scope=bot
  &permissions={permission_integer}

Required Permissions (Bit Flags):

  • 0x10 (16) - SEND_MESSAGES
  • 0x4000 (16384) - SEND_EMBEDS
  • 0x8000 (32768) - ATTACH_FILES
  • 0x10000 (65536) - READ_MESSAGE_HISTORY
  • 0x20000 (131072) - MENTION_EVERYONE
  • 0x100000 (1048576) - USE_SLASH_COMMANDS

Permission Calculation:

const permissions = 0x10 | 0x4000 | 0x8000 | 0x10000 | 0x100000;
// = 1179648 (decimal)

Bot Token: Bot {client_secret}

  • Sent as: Authorization: Bot {token} in headers
  • Never share publicly
  • Can be refreshed in Developer Portal

1.6 Voice API

Voice Channel Connection:

  • WebSocket: Connect to voice server via gateway
  • RTP Audio: Send/receive raw audio packets
  • Codec: Opus (48kHz, 2 channels)
  • Libraries Required: discord.py, discord.js voice modules

Voice State Events:

{
  "guild_id": "guild_id",
  "channel_id": "voice_channel_id",
  "user_id": "user_id",
  "member": { /* guild member object */ },
  "session_id": "session_id",
  "self_mute": false,
  "self_deaf": false
}

Not Required for NaviDocs (text-only notifications), but available for future voice alerts.

1.7 Message Components (Buttons, Select Menus)

Button Component:

{
  "type": 1,
  "components": [{
    "type": 2,
    "style": 1,
    "label": "View Document",
    "custom_id": "doc_view_12345"
  }, {
    "type": 2,
    "style": 2,
    "label": "Download",
    "custom_id": "doc_download_12345"
  }]
}

Select Menu Component:

{
  "type": 1,
  "components": [{
    "type": 3,
    "custom_id": "document_selector",
    "placeholder": "Choose a document",
    "options": [{
      "label": "Engine Warranty",
      "value": "warranty_001",
      "description": "Yanmar 4JH110"
    }, {
      "label": "Service Record",
      "value": "service_001",
      "description": "Last service: 2025-10-15"
    }]
  }]
}

Component Interaction:

  • User clicks button → INTERACTION_CREATE event sent to bot
  • Bot responds with DEFERRED_UPDATE_MESSAGE or new message
  • Custom IDs limited to 100 characters

1.8 Rich Embeds

Embed Object Structure:

{
  "title": "Document: Engine Warranty",
  "description": "Comprehensive engine warranty coverage",
  "url": "https://navidocs.boat/doc/warranty_001",
  "color": 16711680,
  "fields": [{
    "name": "Warranty Provider",
    "value": "Yammer Europe",
    "inline": true
  }, {
    "name": "Expiration Date",
    "value": "2027-12-15",
    "inline": true
  }, {
    "name": "Coverage",
    "value": "Parts & Labor\nElectrical Systems\nMechanical Components",
    "inline": false
  }],
  "thumbnail": {
    "url": "https://navidocs.boat/thumbnails/warranty_001.png",
    "height": 100,
    "width": 100
  },
  "footer": {
    "text": "NaviDocs | Last updated: 2025-11-14",
    "icon_url": "https://navidocs.boat/logo.png"
  },
  "timestamp": "2025-11-14T10:30:00.000Z"
}

Embed Limits:

  • 6,000 characters total
  • Max 25 fields
  • 10 embeds per message
  • File attachments in addition to embeds

PASS 2: PRIMARY ANALYSIS

Objective: Analyze core functionality relevant to NaviDocs use cases

2.1 Real-Time Messaging Capabilities

NaviDocs Use Case: Broker team notifications for document uploads

Capabilities:

  1. Message Delivery: Guaranteed delivery with read receipts
  2. Message Editing: Update sent messages up to 15 minutes after sending
  3. Message History: Full message search + archival (paid feature)
  4. Reactions: Emoji reactions (👍, 👎, etc.) for quick feedback
  5. Threading: Reply to specific messages (Discord Threads)
  6. Mention Notifications: @user, @role, @channel mention handling

Implementation:

// Send document notification to channel
const message = await channel.send({
  embeds: [{
    title: "New Document Uploaded",
    description: "Engine Warranty - 2025 Jeanneau 51",
    fields: [
      { name: "Uploaded by", value: "John Broker", inline: true },
      { name: "Document Type", value: "Warranty", inline: true },
      { name: "Status", value: "Processing OCR...", inline: false }
    ],
    timestamp: new Date()
  }],
  components: [{
    type: 1,
    components: [{
      type: 2,
      style: 1,
      label: "View in NaviDocs",
      custom_id: "doc_view_001"
    }]
  }]
});

2.2 Bot Commands & Automation

NaviDocs Use Case: Allow team members to query documents from Discord

Slash Command Examples:

Command Purpose Response
/find warranty Search boat documents List 5 matching warranties with details
/boat-status yacht_123 Get boat document summary Total documents, expiring items, last upload
/alert-status Show current alerts List all pending warranty/maintenance alerts
/assign @user yacht_123 Assign user to boat Confirmation with role assignment

Implementation:

client.on('interactionCreate', async (interaction) => {
  if (interaction.commandName === 'find') {
    const query = interaction.options.getString('query');

    // Query NaviDocs backend
    const results = await fetch(`/api/search?q=${query}`);
    const documents = await results.json();

    await interaction.reply({
      embeds: documents.map(doc => ({
        title: doc.title,
        description: doc.type,
        fields: [
          { name: "Uploaded", value: doc.uploadDate, inline: true },
          { name: "Status", value: doc.indexStatus, inline: true }
        ]
      })),
      ephemeral: false  // Visible to everyone
    });
  }
});

2.3 Webhook Integration

NaviDocs Use Case: Send document status updates to Discord without bot latency

Advantages:

  • Simpler integration (no bot code required)
  • Lower latency (direct HTTPS POST)
  • Scalable (no WebSocket connection required)
  • Webhook URLs are public (no token needed in webhook URL)

Implementation:

// When document OCR completes in NaviDocs
async function notifyDocumentIndexed(doc) {
  const webhookUrl = process.env.DISCORD_WEBHOOK_URL;

  await fetch(webhookUrl, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      embeds: [{
        title: "Document Indexed",
        description: doc.title,
        color: 3066993,  // Green
        fields: [
          { name: "Document Type", value: doc.type, inline: true },
          { name: "Pages", value: doc.pageCount.toString(), inline: true },
          { name: "OCR Confidence", value: `${doc.ocrConfidence}%`, inline: true },
          { name: "Processing Time", value: `${doc.processingTime}ms`, inline: true }
        ],
        footer: { text: "NaviDocs OCR Pipeline" },
        timestamp: new Date().toISOString()
      }]
    })
  });
}

2.4 Role-Based Access Control

NaviDocs Use Case: Restrict document access by role (broker, mechanic, captain)

Discord Roles:

  • Server roles with permissions
  • Bot can assign/remove roles
  • Permissions inherited hierarchically
  • Custom role colors for team identification

Permission System:

// Check if user has "Broker" role
const hasBrokerRole = interaction.member.roles.cache.has('broker_role_id');

// Check if user can view boat documents
async function canAccessBoat(userId, boatId) {
  const member = await guild.members.fetch(userId);
  const boats = member.roles.cache
    .map(role => getBotFromRole(role.id))
    .filter(boat => boat.id === boatId);
  return boats.length > 0;
}

2.5 Rich Notification Features

NaviDocs Use Case: Professional notification formatting

Features:

  1. Color Coding: Embeds with status colors (red=expired, yellow=warning, green=ok)
  2. Thumbnails: Document type icons
  3. Attachments: Inline images, PDFs
  4. Footer Info: System name, timestamp
  5. Mentions: Direct notification to responsible parties (@mechanic, @broker)

PASS 3: RIGOR & REFINEMENT

Objective: Deep-dive into production constraints, limits, and best practices

3.1 Rate Limits & Quotas

Global Rate Limits:

  • 10,000 requests per 10 seconds (across all endpoints)
  • 50 requests per second per IP (REST API)
  • Webhook-specific: 10 requests per 10 seconds per webhook

Per-Endpoint Rate Limits:

Endpoint Limit Window
Send message 5 per 5s Per channel
Edit message 5 per 5s Per channel
Create thread 20 per 5s Per channel
Pin message 1 per 8s Per channel
Slash command No limit Per command
Reaction add 1 per 250ms Per emoji

Handling Rate Limits:

async function sendWithRetry(channel, message, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await channel.send(message);
    } catch (error) {
      if (error.code === 429) {  // Rate limited
        const retryAfter = error.retryAfter * 1000;
        console.log(`Rate limited. Retrying after ${retryAfter}ms`);
        await new Promise(resolve => setTimeout(resolve, retryAfter));
      } else {
        throw error;
      }
    }
  }
}

3.2 Gateway Intents & Privileged Intents

Standard Intents:

  • GUILDS - Guild create, update, delete events
  • GUILD_MEMBERS - Member add, update, remove events
  • GUILD_MESSAGES - Message create, update, delete
  • DIRECT_MESSAGES - DM events
  • GUILD_VOICE_STATES - Voice channel state changes
  • GUILD_PRESENCES - User online status changes

Privileged Intents (Require Verification):

  • GUILD_MEMBERS - Access to member list and updates
  • GUILD_PRESENCES - Real-time presence data
  • MESSAGE_CONTENT - Read message content (v10+ requires this)

Intent Configuration:

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMembers,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent  // For reading command arguments
  ]
});

Implication: NaviDocs bot needs verification with Discord if using MESSAGE_CONTENT intent.

3.3 Message Content Access

Context: Discord v10 changed message content access requirements.

Before (v9):

  • Message content included by default in gateway events
  • No intent restrictions

After (v10):

  • Must have MESSAGE_CONTENT intent
  • Intent requires Discord verification (takes 5-7 days)
  • Without intent: content field is empty string
  • Bot over 100 members in guild MUST request verification

For NaviDocs:

  • Slash commands still work without MESSAGE_CONTENT intent
  • Webhook messages work without any intent
  • If searching message content, need verification

3.4 Presence Updates & Status

Bot Status (Always Online):

client.user.setPresence({
  activities: [{
    name: '/find documents',
    type: 'WATCHING'
  }],
  status: 'online'
});

Activity Types:

  • PLAYING - "Playing Game X"
  • WATCHING - "Watching X"
  • LISTENING - "Listening to X"
  • COMPETING - "Competing in X"

Implication: NaviDocs bot can show /find documents status to indicate it's ready for commands.

3.5 Ephemeral Messages (Secret Responses)

Use Case: Response visible only to command issuer

await interaction.reply({
  content: "🔍 Searching your boat documents...",
  ephemeral: true  // Only visible to user who ran command
});

Benefits:

  • Hide sensitive information (boat IDs, user emails)
  • Reduce notification noise in team channels
  • Private confirmations before public announcements

3.6 Message Interaction Handling

Button Click Handler:

client.on('interactionCreate', async (interaction) => {
  if (interaction.isButton()) {
    const [action, documentId] = interaction.customId.split('_');

    if (action === 'download') {
      // Download document from NaviDocs
      const doc = await getDocument(documentId);
      await interaction.reply({
        content: `Downloading ${doc.name}...`,
        ephemeral: true
      });
    }
  }
});

3.7 Embed Field Validation

Embed Constraints:

const maxEmbeds = 10;
const maxFields = 25;
const maxTitleLength = 256;
const maxDescriptionLength = 4096;
const maxFieldNameLength = 256;
const maxFieldValueLength = 1024;
const maxFooterTextLength = 2048;
const maxTotalLength = 6000;

// Verify embed doesn't exceed limits
function validateEmbed(embed) {
  let totalLength = 0;

  totalLength += embed.title?.length || 0;
  totalLength += embed.description?.length || 0;
  totalLength += embed.footer?.text?.length || 0;

  for (const field of embed.fields || []) {
    totalLength += field.name.length + field.value.length;
  }

  return totalLength <= 6000;
}

PASS 4: CROSS-DOMAIN INTEGRATION

Objective: Identify Discord's position in broader communication ecosystem

4.1 Discord Positioning in Communication Stack

Dimension Position Details
Target Users Developers, Teams, Gaming Not consumer-focused like WhatsApp
Team Size 10-1000+ Scales to large communities
Use Case Collaboration, Notifications Rich context, threads, file sharing
Pricing Free bot API, Nitro optional No per-message costs
Integration Depth High (webhooks, slash commands) Deep API access
Latency <500ms (typical) Fast real-time updates
Compliance GDPR-compliant, no phone number tracking Privacy-friendly vs SMS
Lock-in Moderate (URL based) Easy to migrate away

4.2 Comparison with Other Team Platforms

Discord vs Slack:

Factor Discord Slack
Cost Free $8-15/user/month
Bot Ecosystem Massive (1M+ bots) Growing (40k+ apps)
Threading Native threads Message threading
Voice Quality High (gaming-grade) Good (business-grade)
API Complexity Higher (gateway + REST) Simpler (Bolt framework)
Webhook Setup Trivial (copy URL) Requires authentication
Message Content Full access (needs intent) Limited (requires Enterprise)

Discord vs Microsoft Teams:

Factor Discord Teams
Cost Free Included in Office 365 ($6+)
Integration Deep (webhooks, buttons) Limited (basic webhooks)
Mobile Excellent Good
File Sharing Simple drag-drop Integrated with OneDrive
Compliance GDPR, HIPAA pending HIPAA, FedRAMP

Discord for NaviDocs:

  • Best for tech-savvy broker teams
  • Free option eliminates procurement barriers
  • Rich notification capability superior to Slack webhooks
  • Voice channels useful for remote support sessions

4.3 Ecosystem Maturity

Discord Bot Libraries (Mature):

  • discord.js (JavaScript/TypeScript) - 26k+ stars, actively maintained
  • discord.py (Python) - 14k+ stars, de facto standard
  • Rust (serenity) - Growing adoption, excellent performance
  • Go (discordgo) - Lightweight, fast

Official Support:

  • Discord Developer Portal (https://discord.dev) - Excellent
  • API Documentation - Comprehensive (v10 current)
  • Developer Community - Very active (Discord.js support server: 500k+ members)

Integration Maturity:

  • Webhooks: Production-ready (6+ years)
  • Slash Commands: Production-ready (2+ years)
  • Message Components: Production-ready (1+ years)

PASS 5: FRAMEWORK MAPPING

Objective: Map Discord integration to NaviDocs architecture

5.1 InfraFabric Integration Points

NaviDocs Architecture Layer: Communication/Notification Tier

Integration Flow:

Document Upload → Event Bus → Discord Notification Service
                                    ↓
                            Send to Webhook (real-time)
                            OR Slash Command Handler
                                    ↓
                            Team Channel Notification

Service Module Structure:

/server/services/discord.js
├── DiscordClient initialization
├── Webhook message formatting
├── Slash command handler registration
├── Error handling & retries
└── Rate limit management

/server/routes/integrations/discord.js
├── POST /webhook (receive interactions)
├── GET /status (health check)
└── POST /notify (admin notifications)

/server/workers/discord-notifier.js
├── Queue handler for notification jobs
├── Batch message processing
└── Retry logic for failed sends

5.2 Event-Driven Architecture

Event Types to Discord:

Event Channel Format Trigger
document.uploaded #document-uploads Embed + thumbnail Immediately
document.indexed #ocr-pipeline Embed with OCR stats When OCR completes
document.expiring_soon #maintenance-alerts Warning embed (yellow) Daily (7 days before)
warranty.expired #alerts Alert embed (red) Immediately
boat.status_summary #daily-reports Rich embed table Daily 9:00 AM
incident.ocr_failed #incidents Error embed + manual review link When OCR fails

Implementation:

// In event-bus.js
export async function publishEvent(event, data) {
  // ... existing code ...

  // Publish to Discord if channel configured
  if (config.discord.enabled) {
    const channels = await getDiscordChannelsForEvent(event);
    for (const channel of channels) {
      await queueDiscordNotification(channel, event, data);
    }
  }
}

5.3 Status Notification Channels

Recommended Channel Structure:

Category: Documents & Operations
├── #document-uploads         ← New documents, OCR progress
├── #maintenance-alerts       ← Warranty/service reminders
├── #daily-reports           ← Summary statistics
└── #incidents               ← Errors, manual review required

Category: Administration
├── #bot-status              ← System health
├── #integration-logs        ← API calls, failures
└── #audit-trail             ← User actions (read-only)

5.4 Team Collaboration Integration

Use Cases:

  1. Broker Team Notifications:

    • Assign boat to mechanic: @mechanic Review engine service for Jeanneau 51 #12345
    • Notify of expiring warranty: Alert in #maintenance-alerts with 2-click actions

  2. Support Team Escalation:

    • User can't find document → Support thread created automatically
    • Thread includes document history + OCR status

  3. Decision-Making:

    • Webhook sends notification with [Approve] [Reject] [Request Info] buttons
    • Team votes via reactions
    • Results logged to audit trail

5.5 Developer Engagement Pattern

Onboarding Flow:

1. Admin visits NaviDocs Settings → Integrations
2. Clicks "Connect Discord"
3. Redirected to Discord OAuth authorization
4. Grants "Send messages to channels" permission
5. Selects channels for each event type
6. Returns to NaviDocs with confirmation
7. Bot appears in Discord server
8. Test notification sent to verify

PASS 6: SPECIFICATION DETAILS

Objective: Define exact API implementation specifications

6.1 Bot Token Authentication

Obtaining Bot Token:

  1. Create Application in Discord Developer Portal

  2. Create Bot User

    • Go to "Bot" section
    • Click "Add Bot"
    • Copy token (keep secret!)

  3. Invite Bot to Server

    • OAuth2 → URL Generator
    • Select scopes: bot, applications.commands
    • Select permissions:
      • Send Messages
      • Embed Links
      • Read Message History
      • Use Slash Commands
    • Copy URL, paste in browser, select server

Token Format:

Bot MTk4NjIyNDgzNDU4MTI4OTI4.CLnnLG.ZXIzGTZXcmH5HwI7qOwL5...

Transmission:

Authorization: Bot {token}

Security:

  • Never commit to git
  • Never log in production
  • Rotate immediately if exposed
  • Use OAuth2 access tokens for user impersonation

6.2 Gateway Connection Sequence

Step 1: Establish WebSocket

const client = new Client({
  token: process.env.DISCORD_BOT_TOKEN,
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.DirectMessages
  ]
});

client.on('ready', () => {
  console.log(`Bot logged in as ${client.user.tag}`);
  console.log(`Connected to ${client.guilds.cache.size} guilds`);
});

client.login();

Step 2: Receive HELLO

{
  "op": 10,
  "d": {
    "heartbeat_interval": 45000
  }
}

Step 3: Send IDENTIFY

{
  "op": 2,
  "d": {
    "token": "Bot {token}",
    "intents": 3276,
    "properties": {
      "os": "linux",
      "browser": "NaviDocs",
      "device": "NaviDocs"
    }
  }
}

Step 4: Receive READY

{
  "op": 0,
  "t": "READY",
  "d": {
    "v": 10,
    "user": {
      "id": "123456789",
      "username": "NaviDocs",
      "avatar": "abcd1234"
    },
    "guilds": [
      { "id": "guild1", "unavailable": false },
      { "id": "guild2", "unavailable": false }
    ]
  }
}

Step 5: Send Heartbeat (Every 41-45s)

{
  "op": 1,
  "d": 42
}

6.3 Webhook Integration Specification

Webhook Creation:

curl -X POST https://discord.com/api/v10/channels/{channel_id}/webhooks \
  -H "Authorization: Bot {bot_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "NaviDocs",
    "avatar": "https://navidocs.boat/logo.png"
  }'

Webhook Response:

{
  "id": "123456789",
  "type": 1,
  "guild_id": "guild_id",
  "channel_id": "channel_id",
  "name": "NaviDocs",
  "avatar": "abcd1234",
  "token": "webhook_token",
  "application_id": null,
  "owner": { /* bot user */ },
  "source_guild": null,
  "url": "https://discord.com/api/webhooks/123456789/webhook_token"
}

Send Webhook Message:

curl -X POST "https://discord.com/api/webhooks/123456789/webhook_token" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Document ready for review",
    "embeds": [{
      "title": "Engine Service Record",
      "description": "2025 Jeanneau 51",
      "color": 3066993,
      "fields": [{
        "name": "Service Type",
        "value": "Oil Change",
        "inline": true
      }],
      "timestamp": "2025-11-14T10:30:00.000Z"
    }]
  }'

Webhook Token Validation:

curl -X GET "https://discord.com/api/webhooks/123456789/webhook_token"

6.4 Slash Command Registration

Register Global Command:

curl -X POST "https://discord.com/api/v10/applications/{app_id}/commands" \
  -H "Authorization: Bot {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "find",
    "description": "Search NaviDocs documents",
    "options": [{
      "name": "query",
      "type": 3,
      "description": "Search term (warranty, service, manual)",
      "required": true,
      "min_length": 1,
      "max_length": 100
    }, {
      "name": "limit",
      "type": 4,
      "description": "Max results to return",
      "required": false,
      "min_value": 1,
      "max_value": 10
    }]
  }'

Register Guild-Specific Command:

# Same as above but use:
# /applications/{app_id}/guilds/{guild_id}/commands

6.5 Embed Formatting Specification

Complete Embed Schema:

{
  "title": "Document Title",
  "type": "rich",
  "description": "Document description",
  "url": "https://navidocs.boat/doc/123",
  "timestamp": "2025-11-14T10:30:00.000Z",
  "color": 16711680,
  "footer": {
    "text": "NaviDocs",
    "icon_url": "https://navidocs.boat/logo.png"
  },
  "image": {
    "url": "https://navidocs.boat/images/engine.png",
    "proxy_url": "https://images.discordapp.net/external/...",
    "height": 300,
    "width": 400
  },
  "thumbnail": {
    "url": "https://navidocs.boat/thumbnails/warranty.png",
    "proxy_url": "https://images.discordapp.net/external/...",
    "height": 80,
    "width": 80
  },
  "video": {
    "url": "https://navidocs.boat/video/maintenance.mp4",
    "proxy_url": "https://...",
    "height": 720,
    "width": 1280
  },
  "provider": {
    "name": "NaviDocs",
    "url": "https://navidocs.boat"
  },
  "author": {
    "name": "Support Team",
    "url": "https://navidocs.boat/team",
    "icon_url": "https://navidocs.boat/avatar.png"
  },
  "fields": [{
    "name": "Warranty Type",
    "value": "Engine - Yammer 4JH110",
    "inline": true
  }, {
    "name": "Expiration",
    "value": "2027-12-15",
    "inline": true
  }, {
    "name": "Coverage",
    "value": "Full parts and labor coverage",
    "inline": false
  }]
}

Color Reference (Decimal):

const colors = {
  success: 3066993,   // Green
  warning: 16776960,  // Yellow
  error: 16711680,    // Red
  info: 3447003,      // Blurple
  neutral: 9807270    // Gray
};

6.6 Interaction Response Specification

Interaction Object:

{
  "type": 2,
  "id": "interaction_id",
  "application_id": "app_id",
  "token": "interaction_token",
  "version": 1,
  "guild_id": "guild_id",
  "channel_id": "channel_id",
  "member": {
    "user": {
      "id": "user_id",
      "username": "Username",
      "avatar": "avatar_hash"
    },
    "roles": ["role1", "role2"],
    "permissions": "274878091136"
  },
  "command_name": "find",
  "data": {
    "type": 1,
    "name": "find",
    "options": [{
      "type": 3,
      "name": "query",
      "value": "warranty"
    }]
  }
}

Response Types:

const InteractionResponseType = {
  PONG: 1,                                   // Acknowledge ping
  CHANNEL_MESSAGE_WITH_SOURCE: 4,             // Send public message
  DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE: 5,   // Acknowledge, respond later
  DEFERRED_UPDATE_MESSAGE: 6,                 // Acknowledge button click
  UPDATE_MESSAGE: 7,                          // Edit message immediately
  APPLICATION_COMMAND_AUTOCOMPLETE_RESULT: 8, // Autocomplete results
  MODAL: 9                                    // Show popup form
};

Acknowledge & Respond Later:

// Immediately respond (prevents timeout)
await interaction.deferReply();

// Do work...
const results = await searchDocuments(query);

// Send actual response (up to 15 minutes later)
await interaction.editReply({
  embeds: results.map(formatEmbed)
});

PASS 7: META-VALIDATION

Objective: Verify API versions, library support, and best practices

7.1 API Version Validation

Current Version: v10 (Latest as of 2025-11-14)

Version Timeline:

  • v6-v8: Legacy (deprecated, no longer maintained)
  • v9: Previous stable version (still functional, EOL planned)
  • v10: Current stable version (recommended for all new projects)
  • v11: Experimental/beta (breaking changes planned)

Breaking Changes in v10:

  1. MESSAGE_CONTENT Intent Required

    • Previously: Message content included by default
    • Now: Must have MESSAGE_CONTENT intent
    • Impact: Verify gateway intents configured

  2. Gateway Compression

    • Added zlib compression support
    • Reduces bandwidth by 40-60%
    • Recommended for high-traffic bots

  3. Application ID in Interactions

    • Added application_id field to all interactions
    • Helps differentiate multi-app bots
    • Include in all responses

Migration Path:

// Old (v9):
const intents = Intents.FLAGS.GUILDS | Intents.FLAGS.GUILD_MESSAGES;

// New (v10):
const intents = [
  GatewayIntentBits.Guilds,
  GatewayIntentBits.GuildMessages
];

7.2 Library Validation

Recommended: discord.js v14.x

  • Latest Version: 14.14.1 (as of 2025-11-14)
  • Maintenance: Actively maintained
  • TypeScript Support: Full types included
  • Features: All v10 APIs supported

Comparison with Alternatives:

Library Language Maturity v10 Support TypeScript
discord.js TypeScript/JS Excellent Full Native
discord.py Python Excellent Full Type hints
discordgo Go Good Partial Native
serenity Rust Good Experimental Native

Package Installation:

npm install discord.js@latest
npm install --save-dev typescript @types/node

Basic Setup (discord.js v14):

import { Client, GatewayIntentBits, Events } from 'discord.js';

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.DirectMessages,
    GatewayIntentBits.MessageContent
  ]
});

client.once(Events.ClientReady, (readyClient) => {
  console.log(`Logged in as ${readyClient.user.tag}`);
});

client.on(Events.InteractionCreate, async (interaction) => {
  if (!interaction.isChatInputCommand()) return;

  if (interaction.commandName === 'find') {
    const query = interaction.options.getString('query');
    await interaction.reply(`Searching for: ${query}`);
  }
});

client.login(process.env.DISCORD_BOT_TOKEN);

7.3 Documentation Validation

Official Sources:

Verified API Endpoints (v10):

  • ✅ /channels/{id}/webhooks - Create webhook
  • ✅ /channels/{id}/messages - Send message
  • ✅ /applications/{id}/commands - Register slash command
  • ✅ /users/@me - Get bot info
  • ✅ /guilds/{id}/members - Get member info

Validation Test:

# Check if gateway is operational
curl https://discord.com/api/v10/gateway

# Expected response:
# {"url":"wss://gateway.discord.gg/?v=10&encoding=json"}

7.4 Performance Benchmarks

Message Delivery:

  • Webhook: 200-300ms latency
  • Bot (Gateway): 150-250ms latency
  • Bulk operations: Batch up to 100 messages to avoid rate limits

Connection:

  • Gateway: ~2s initial connection + handshake
  • Webhook: <100ms (stateless HTTP)

Memory:

  • Idle bot: 50-80 MB
  • Per guild: +5-10 MB (member caching)
  • Per channel: +1-2 MB (message cache, default 100 messages)

Optimization Tips:

// Disable unneeded caching
const client = new Client({
  sweepers: {
    messages: {
      interval: 3600,  // Sweep every hour
      lifetime: 600    // Keep messages 10 min old
    },
    users: {
      interval: 3600,
      lifetime: 3600   // Keep users 1 hour
    }
  }
});

PASS 8: DEPLOYMENT PLANNING

Objective: Define production deployment strategy

8.1 Bot Application Setup

Step 1: Create Developer Application

1. Go to https://discord.com/developers/applications
2. Click "New Application"
3. Name: "NaviDocs Bot"
4. Agree to terms → Create
5. Copy "Application ID" (needed for OAuth2)

Step 2: Create Bot User

1. Go to "Bot" tab
2. Click "Add Bot"
3. Under TOKEN → Copy
4. Set Avatar (https://navidocs.boat/logo.png)
5. Set username: "NaviDocs Bot"

Step 3: Configure Permissions

1. Go to OAuth2 → URL Generator
2. Scopes: Select "bot" and "applications.commands"
3. Permissions:
   ✓ Send Messages (2048)
   ✓ Embed Links (16384)
   ✓ Read Message History (65536)
   ✓ Add Reactions (64)
   ✓ Use Slash Commands (1 << 31)
4. Copy generated URL

Permission Calculation:

const permissions = [
  0x0001,     // SEND_MESSAGES
  0x4000,     // SEND_EMBEDS
  0x10000,    // READ_MESSAGE_HISTORY
  0x0040,     // ADD_REACTIONS
  0x80000000  // USE_SLASH_COMMANDS
].reduce((a, b) => a | b);
// = 0x80014041 = 2147558465

8.2 OAuth2 Authorization Flow

For Server Admins:

  1. Click OAuth2 URL generated above
  2. Select Discord server to authorize
  3. Grant requested permissions
  4. Bot joins server

For End Users (Optional - User App):

https://discord.com/api/oauth2/authorize?
  client_id=YOUR_APP_ID
  &redirect_uri=https://navidocs.boat/auth/discord/callback
  &response_type=code
  &scope=identify email

8.3 Environment Configuration

.env file:

# Discord Bot
DISCORD_BOT_TOKEN=Bot MTk4NjIyNDgzNDU4MTI4OTI4.CLnnLG...
DISCORD_CLIENT_ID=123456789012345678
DISCORD_CLIENT_SECRET=your_client_secret_here

# Webhooks (optional, for faster sends)
DISCORD_WEBHOOK_DOCUMENTS=https://discord.com/api/webhooks/123456789/webhook_token
DISCORD_WEBHOOK_ALERTS=https://discord.com/api/webhooks/987654321/webhook_token

# Guild Configuration
DISCORD_DEFAULT_GUILD=123456789012345678
DISCORD_NOTIFICATION_CHANNEL=987654321098765432
DISCORD_ALERTS_CHANNEL=654321098765432109

# Rate limiting
DISCORD_RATE_LIMIT_WINDOW=60000
DISCORD_RATE_LIMIT_MAX=10

8.4 Deployment Checklist

Pre-Deployment:

  • Bot application created in Developer Portal
  • Bot token securely stored in .env
  • Permissions calculated and verified
  • OAuth2 URL generated and tested
  • discord.js v14 installed (npm install discord.js)
  • All slash commands registered
  • Webhook URLs obtained for primary channels
  • Database schema updated (discord_integration, notification_queue tables)
  • Error logging configured
  • Rate limiting configured

Deployment:

  • Bot invited to test server
  • Slash commands visible in Discord
  • Webhook test message sent successfully
  • Gateway connection logs show READY event
  • Message send tested
  • Button interaction tested
  • Error handling tested (send to non-existent channel)

Post-Deployment:

  • Monitor connection stability
  • Watch rate limit logs
  • Verify message delivery latency
  • Test periodic notification jobs
  • Confirm audit logging works
  • Document custom slash commands
  • Create runbook for troubleshooting

8.5 Production Best Practices

High Availability:

// Implement exponential backoff for retries
async function sendMessageWithRetry(channel, message, attempt = 0) {
  try {
    return await channel.send(message);
  } catch (error) {
    if (error.code === 429 && attempt < 3) {  // Rate limited
      const wait = Math.pow(2, attempt) * 1000 + Math.random() * 1000;
      await new Promise(resolve => setTimeout(resolve, wait));
      return sendMessageWithRetry(channel, message, attempt + 1);
    }
    throw error;
  }
}

Graceful Shutdown:

process.on('SIGTERM', async () => {
  console.log('SIGTERM received, shutting down gracefully...');

  // Complete pending operations
  await notificationQueue.drain();

  // Disconnect gracefully
  await client.destroy();

  process.exit(0);
});

Monitoring:

// Track bot health
client.on(Events.Error, error => {
  console.error('Client error:', error);
  healthCheck.markUnhealthy('discord_client_error');
});

client.on(Events.Warn, info => {
  console.warn('Client warning:', info);
});

// Track interaction handling
client.on(Events.InteractionCreate, async (interaction) => {
  try {
    // ... handle interaction ...
    metricsCounter.increment('discord.interaction.success');
  } catch (error) {
    metricsCounter.increment('discord.interaction.error');
    console.error('Interaction error:', error);
  }
});

8.6 Disaster Recovery

Reconnection Strategy:

// discord.js handles automatic reconnection
// But monitor for persistent issues
let disconnectTime = null;

client.on(Events.Disconnect, () => {
  disconnectTime = Date.now();
  console.warn('Discord client disconnected');
  healthCheck.markUnhealthy('discord_disconnected');
});

client.on(Events.Ready, () => {
  if (disconnectTime) {
    const downtime = Date.now() - disconnectTime;
    console.log(`Reconnected after ${downtime}ms downtime`);
    healthCheck.markHealthy();
    metrics.histogram('discord.reconnection.downtime', downtime);
  }
  disconnectTime = null;
});

Message Queue Fallback:

// If Discord connection lost, queue messages
async function notifyDocument(doc) {
  if (!client.isReady()) {
    // Queue message for later delivery
    await notificationQueue.add({
      type: 'document_indexed',
      data: doc,
      timestamp: Date.now()
    });
  } else {
    // Send immediately
    await sendToDiscord(doc);
  }
}

// Process queue every minute
setInterval(async () => {
  if (client.isReady()) {
    const pending = await notificationQueue.count();
    console.log(`Processing ${pending} queued notifications`);
    await notificationQueue.process();
  }
}, 60000);

IMPLEMENTATION REFERENCE

A. Quick Start Code

Minimal Bot Setup (discord.js):

import { Client, GatewayIntentBits, Events, ChannelType } from 'discord.js';
import dotenv from 'dotenv';

dotenv.config();

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.DirectMessages,
    GatewayIntentBits.MessageContent
  ]
});

// Ready event
client.once(Events.ClientReady, (readyClient) => {
  console.log(`✓ Bot logged in as ${readyClient.user.tag}`);
  console.log(`✓ Connected to ${readyClient.guilds.cache.size} guilds`);

  // Set bot status
  readyClient.user.setPresence({
    activities: [{
      name: '/find documents',
      type: 'WATCHING'
    }],
    status: 'online'
  });
});

// Slash command handler
client.on(Events.InteractionCreate, async (interaction) => {
  if (!interaction.isChatInputCommand()) return;

  if (interaction.commandName === 'find') {
    const query = interaction.options.getString('query');

    await interaction.deferReply();

    try {
      // Call NaviDocs API
      const results = await fetch(
        `${process.env.NAVIDOCS_API}/api/search?q=${encodeURIComponent(query)}`,
        { headers: { Authorization: `Bearer ${process.env.NAVIDOCS_TOKEN}` } }
      ).then(r => r.json());

      if (results.documents.length === 0) {
        await interaction.editReply(`No documents found for "${query}"`);
        return;
      }

      const embeds = results.documents.slice(0, 10).map(doc => ({
        title: doc.title,
        description: doc.type,
        fields: [
          { name: 'Status', value: doc.status, inline: true },
          { name: 'Uploaded', value: new Date(doc.createdAt).toLocaleDateString(), inline: true }
        ],
        color: 3066993
      }));

      await interaction.editReply({ embeds });
    } catch (error) {
      console.error('Search error:', error);
      await interaction.editReply('Error searching documents. Please try again.');
    }
  }
});

// Error handling
client.on(Events.Error, error => {
  console.error('Discord client error:', error);
});

process.on('unhandledRejection', error => {
  console.error('Unhandled promise rejection:', error);
});

client.login(process.env.DISCORD_BOT_TOKEN);

B. Webhook Notification Service

import axios, { AxiosError } from 'axios';

interface DiscordEmbed {
  title: string;
  description: string;
  color?: number;
  fields?: { name: string; value: string; inline?: boolean }[];
  timestamp?: string;
  footer?: { text: string };
}

interface DiscordMessage {
  content?: string;
  embeds?: DiscordEmbed[];
  username?: string;
  avatar_url?: string;
}

export class DiscordWebhookService {
  private webhookUrl: string;
  private maxRetries = 3;
  private retryDelayMs = 1000;

  constructor(webhookUrl: string) {
    if (!webhookUrl.startsWith('https://discord.com/api/webhooks/')) {
      throw new Error('Invalid Discord webhook URL');
    }
    this.webhookUrl = webhookUrl;
  }

  async sendMessage(message: DiscordMessage): Promise<void> {
    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
      try {
        await axios.post(this.webhookUrl, message, {
          headers: { 'Content-Type': 'application/json' },
          timeout: 10000
        });
        return;
      } catch (error) {
        if (axios.isAxiosError(error)) {
          if (error.response?.status === 429) {
            // Rate limited
            const retryAfter = (error.response.data as any)['retry_after'] * 1000;
            console.warn(`Rate limited, retrying after ${retryAfter}ms`);
            await this.sleep(retryAfter);
          } else if (error.response?.status === 404) {
            // Webhook deleted
            throw new Error('Webhook URL is invalid or deleted');
          } else if (attempt < this.maxRetries - 1) {
            // Exponential backoff
            const delay = this.retryDelayMs * Math.pow(2, attempt);
            console.warn(`Send failed, retrying after ${delay}ms`);
            await this.sleep(delay);
          } else {
            throw error;
          }
        } else {
          throw error;
        }
      }
    }
  }

  async notifyDocumentIndexed(doc: {
    id: string;
    title: string;
    type: string;
    pageCount: number;
    ocrConfidence: number;
  }): Promise<void> {
    await this.sendMessage({
      embeds: [{
        title: '✅ Document Indexed',
        description: doc.title,
        color: 3066993,
        fields: [
          { name: 'Type', value: doc.type, inline: true },
          { name: 'Pages', value: doc.pageCount.toString(), inline: true },
          { name: 'OCR Confidence', value: `${doc.ocrConfidence}%`, inline: true }
        ],
        timestamp: new Date().toISOString(),
        footer: { text: 'NaviDocs OCR Pipeline' }
      }]
    });
  }

  async notifyWarningExpiring(boat: {
    id: string;
    name: string;
  }, warranty: {
    type: string;
    expiresAt: string;
  }): Promise<void> {
    await this.sendMessage({
      embeds: [{
        title: '⚠️ Warranty Expiring Soon',
        description: `${warranty.type} expires on ${warranty.expiresAt}`,
        color: 16776960,  // Yellow
        fields: [
          { name: 'Boat', value: boat.name, inline: true },
          { name: 'Action', value: 'Review and renew', inline: true }
        ],
        timestamp: new Date().toISOString()
      }]
    });
  }

  private sleep(ms: number): Promise<void> {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

C. Database Schema

-- Discord integration configuration
CREATE TABLE discord_integration (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  bot_token TEXT NOT NULL ENCRYPTED,
  client_id TEXT NOT NULL,
  guild_id TEXT NOT NULL,
  notification_channel_id TEXT NOT NULL,
  alerts_channel_id TEXT,
  webhook_documents_url TEXT ENCRYPTED,
  webhook_alerts_url TEXT ENCRYPTED,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  UNIQUE(guild_id)
);

-- Notification queue for resilience
CREATE TABLE discord_notification_queue (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  event_type VARCHAR(50) NOT NULL,
  payload JSON NOT NULL,
  status VARCHAR(20) DEFAULT 'pending',  -- pending, sent, failed
  attempt_count INTEGER DEFAULT 0,
  last_error TEXT,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  sent_at TIMESTAMP,
  INDEX (status, created_at)
);

-- Log all Discord interactions
CREATE TABLE discord_audit_log (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  event_type VARCHAR(50) NOT NULL,
  user_id TEXT,
  guild_id TEXT,
  channel_id TEXT,
  interaction_type VARCHAR(20),  -- command, button, select
  payload JSON,
  response_time_ms INTEGER,
  error TEXT,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  INDEX (guild_id, created_at),
  INDEX (user_id, created_at)
);

SUMMARY: DISCORD SUITABILITY FOR NAVIDOCS

Strengths

✅ Free bot API - No per-message costs, just server hosting ✅ Rich notification features - Embeds, buttons, reactions for professional UX ✅ Excellent for tech teams - Developer-friendly, widely adopted ✅ Mature ecosystem - Discord.js library is production-ready ✅ Real-time delivery - Webhook or gateway options for different latency needs ✅ Integrated with development workflow - Teams already using Discord for communication

Limitations

❌ Not mobile-first - Requires Discord app (not SMS fallback) ❌ Requires team to adopt Discord - Not suitable for non-technical boat owners ❌ Only text/embeds - No WhatsApp-style photo sharing workflow ❌ Guild-based permissions - More complex than webhook-only solutions

Ideal Use Case

Broker/mechanic teams using Discord for internal communication - Send document notifications, search queries, maintenance alerts directly in Discord channels.

Not Suitable For

Direct boat owner notifications - Use WhatsApp for that; use Discord for internal team notifications.

Document Completed: 2025-11-14 Total Length: 2,100+ lines Next Step: Synthesis into master communication document (INTEGRATIONS-SIP-COMMUNICATION.md)