Discord Sink

The Discord sink allows your workflows to be triggered by Discord bot interactions including slash commands, button clicks, and message components.

How It Works

Local Mode (Gateway)

When running the desktop app, Flow-Like connects to Discord via the Gateway API (WebSocket):

┌──────────────┐    WebSocket (Gateway)    ┌──────────────┐
│   Flow-Like  │◄─────────────────────────►│   Discord    │
│   Desktop    │                           │   Servers    │
└──────────────┘                           └──────────────┘

Advantages:

Works behind firewalls/NAT
No public URL required
Receives all gateway events (messages, presence, etc.)

Limitations:

Requires persistent connection
Must keep the app running

Remote Mode (Interactions Webhook)

When deployed to a server, Discord sends interactions directly via HTTP:

┌──────────────┐                           ┌──────────────┐
│   Flow-Like  │◄──────────────────────────│   Discord    │
│    Server    │   (Interactions Webhook)   │   Servers    │
└──────────────┘                           └──────────────┘

Advantages:

Instant interaction handling
Works 24/7
More efficient for slash commands

Limitations:

Requires public HTTPS endpoint
Only receives interactions, not gateway events

Endpoint Format (Remote)

POST /sink/trigger/discord/{event_id}

Configuration Options

| Field | Type | Description | Required | |-------|------|-------------|----------| | token | string | Bot token from Developer Portal | Yes | | webhook_secret | string | Application public key (for signature verification) | Recommended | | bot_name | string | Display name for the bot | No | | intents | string[] | Gateway intents (for local mode) | No | | respond_to_mentions | boolean | Respond to @mentions | No | | respond_to_dms | boolean | Respond to DMs | No | | command_prefix | string | Command prefix for text commands | No | | channel_whitelist | string[] | Only process from these channels | No | | channel_blacklist | string[] | Ignore these channels | No |

Creating a Discord Bot

Go to the Discord Developer Portal
Click "New Application" and give it a name
Go to the "Bot" section and click "Add Bot"
Copy the bot token (click "Reset Token" if needed)
Enable the required intents under "Privileged Gateway Intents"

Webhook Setup (Remote Mode)

1. Get Your Application's Public Key

Go to the Discord Developer Portal
Select your application
Copy the Public Key from the General Information page

2. Configure Flow-Like

Save the public key in the webhook_secret field of your event configuration.

3. Get Your Interactions Endpoint URL

The URL format is:

https://your-domain.com/sink/trigger/discord/{event_id}

4. Register with Discord

Go to your application in the Developer Portal
Under General Information, find "Interactions Endpoint URL"
Paste your webhook URL
Discord will verify the endpoint automatically

Security

Ed25519 Signature Verification

Discord signs all webhook requests using Ed25519. Flow-Like verifies these signatures using:

Header: X-Signature-Ed25519 (the signature)
Header: X-Signature-Timestamp (the timestamp)
Your application's public key

The message verified is: timestamp + request_body

Development Mode

In development (when API_BASE_URL contains localhost), signature verification is disabled for easier testing.

Interaction Types

Discord sends different interaction types:

| Type | Value | Description | |------|-------|-------------| | PING | 1 | Verification request from Discord | | APPLICATION_COMMAND | 2 | Slash command invoked | | MESSAGE_COMPONENT | 3 | Button/select menu used | | APPLICATION_COMMAND_AUTOCOMPLETE | 4 | Autocomplete request | | MODAL_SUBMIT | 5 | Modal form submitted |

PING Handling

Flow-Like automatically responds to PING requests with PONG - this is required for Discord to verify your endpoint:

// Request
{"type": 1}

// Response
{"type": 1}

Command/Component Handling

For actual interactions, Flow-Like:

Acknowledges with a deferred response (type 5)
Dispatches the workflow execution asynchronously
Your workflow can then follow up with a response

Payload Format

Discord sends interactions like this:

{
  "type": 2,
  "id": "123456789",
  "application_id": "987654321",
  "token": "interaction_token",
  "guild_id": "111222333",
  "channel_id": "444555666",
  "member": {
    "user": {
      "id": "777888999",
      "username": "johndoe"
    }
  },
  "data": {
    "id": "command_id",
    "name": "mycommand",
    "options": [
      {"name": "option1", "value": "hello"}
    ]
  }
}

Response Format

The sink returns a deferred response immediately:

{
  "type": 5
}

This tells Discord "we received it and will respond later". Your workflow must then use the interaction token to send a follow-up response via Discord's API.

Gateway Intents

For local mode, you may need to enable gateway intents:

| Intent | Purpose | Privileged | |--------|---------|------------| | Guilds | Server information | No | | GuildMessages | Messages in servers | No | | MessageContent | Read message content | Yes | | GuildMembers | Member information | Yes | | GuildPresences | User presence | Yes |

Privileged intents must be enabled in the Developer Portal.

Registering Commands

To use slash commands, you must register them with Discord:

curl -X POST "https://discord.com/api/v10/applications/{app_id}/commands" \
  -H "Authorization: Bot {bot_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hello",
    "description": "Says hello",
    "type": 1
  }'

Error Handling

| Status Code | Description | |-------------|-------------| | 200 OK | Interaction handled | | 401 Unauthorized | Invalid signature | | 404 Not Found | No matching sink found |

Best Practices

Always verify signatures in production
Respond within 3 seconds - Discord requires fast acknowledgement
Use deferred responses for workflows that take time
Register commands before using slash commands
Keep the bot token secure - use environment variables
Enable only needed intents for gateway mode