Discord Integration Guide

Post messages and rich embeds from your pipelines to Discord channels, through an incoming webhook or a bot.

Authentication

Incoming webhook URL, or bot token

Operations

Send Message

Rate limit

5 messages per 2 s per webhook; 5 per 5 s per channel

Send alerts, shift summaries and status updates to Discord channels directly from your pipelines. This guide covers choosing between a webhook and a bot, setting either up in Discord, the connection and function fields, and what to do when Discord refuses a message.

Overview

The Discord connector enables you to:

• Post messages of up to 2000 characters to a channel
• Attach rich embeds: titles, colours, fields, footers and timestamps, up to 10 per message
• Keep mentions inert by default: @everyone, @here, role and user mentions in pipeline text are shown but ping nobody unless the function allows mentions
• Choose how to connect: an incoming webhook for one channel, or a bot that can post to any channel it has access to
• Pick channels from a list when the connection uses a bot

Webhook or bot?

	Incoming webhook (default)	Bot
Set up in	The channel's settings, one click	The Discord Developer Portal, plus an invite to your server
Posts to	The webhook's own channel only	Any channel the bot may write to, chosen per function
Name and avatar	Per message, from the function (Username Override, Avatar URL Override)	The bot's own
Channel picker	Not available	Lists the server's text and announcement channels
Best for	One alert channel	Several channels from one connection

Prerequisites

For a webhook

1. You can manage webhooks in the channel (the Manage Webhooks permission).
2. In Discord, open the channel's Edit Channel → Integrations → Webhooks → New Webhook, name it, and click Copy Webhook URL. It looks like https://discord.com/api/webhooks/123456789012345678/AbCdEf….

warning

The webhook URL is a credential: anyone who has it can post to the channel. MaestroHub stores it encrypted and never shows it again; if it leaks, delete the webhook in Discord and create a new one.

For a bot

1. In the Discord Developer Portal, create an application and open its Bot page.
2. Click Reset Token and copy the token. Enter it without the Bot prefix; MaestroHub adds it.
3. Under OAuth2 → URL Generator, select the bot scope and the View Channels, Send Messages and Embed Links permissions, open the generated URL and add the bot to your server.
4. To find IDs, turn on User Settings → Advanced → Developer Mode in Discord; then right-click a server or channel and choose Copy Server ID or Copy Channel ID.

Connection Configuration

Creating a Discord Connection

Navigate to Connections → New Connection → Discord and configure the following:

Zoom

Create a Discord connection with a webhook or a bot

1. Profile Information

Field	Default	Description
Profile Name	-	A descriptive name for this connection profile (required, max 100 characters)
Description	-	Optional description for this Discord connection

2. Authentication

Field	Default	Description
Authentication	Webhook	Webhook posts through one channel's incoming webhook. Bot posts as a bot to any channel it may write to
Webhook URL	-	Webhook mode: the URL from Copy Webhook URL (required, stored encrypted)
Bot Token	-	Bot mode: the bot's token, without the Bot prefix (required, stored encrypted)

The field of the mode you did not choose is hidden and not saved.

3. Advanced

Field	Default	Description
Custom API URL	https://discord.com/api/v10	Only when your company routes Discord traffic through its own gateway or proxy. Both modes send every request here: a webhook's id and token are taken from its URL and sent to this address

Notes

• Test Connection makes a real request: in webhook mode it reads the webhook, in bot mode it reads the bot's own user. A deleted webhook or a revoked token fails here, not at the first alert.
• Security: The webhook URL and the bot token are stored encrypted and masked on edit. Leave the field empty to keep the stored value.

Function Builder

Creating Discord Functions

After saving the connection:

1. Open the connection and go to its Functions tab → New Function
2. Select Send Message. It is the only Discord function type; the channel list only fills the form's picker
3. Configure the message

Zoom

Create reusable Discord functions

Send Message Function

Purpose: Post a message, with optional embeds, to a Discord channel.

Field	Type	Required	Default	Description
Function Name	String	Yes	-	A descriptive name, e.g. line-3-alerts. Max 100 characters
Channel	String	Bot mode	-	The channel to post to. Enter a Server ID to list its channels, or enter the Channel ID by hand. Disabled in webhook mode, with the reason: the webhook’s own channel is used. Supports parameters
Message	String	Yes	-	Up to 2000 characters. Supports parameters: ((machine)), ((temperature)). If its parameters resolve to nothing at run time, the message is sent only when embeds are set
Embeds (JSON)	JSON text	No	-	A JSON array of Discord embed objects, or one object; at most 10 and 6000 characters of embed text in all. Supports parameters
Username Override	String	No	-	Webhook mode only: the name the message is posted under (max 80 characters). Supports parameters. Disabled, with the reason, on a bot connection
Avatar URL Override	String	No	-	Webhook mode only: an image URL for the message’s avatar. Disabled, with the reason, on a bot connection
Allow Mentions	Switch	No	Off	Off: @everyone, @here, role and user mentions ping nobody. On: Discord's default, every mention in the text pings
Timeout	Duration	No	30s	Bound on this single send

An embed example:

[{
  "title": "Line 3 stopped",
  "description": "Bearing temperature ((temperature)) °C",
  "color": 15158332,
  "fields": [{ "name": "Shift", "value": "((shift))", "inline": true }],
  "footer": { "text": "MaestroHub" }
}]

A message is checked before it is sent, and refused with nothing sent, when the message resolves to nothing and no embeds are set, the message is over 2000 characters, the embeds are not valid JSON or exceed Discord's limits, a bot-mode function has no channel, or a field of the other mode is set (a channel on a webhook connection, a username or avatar on a bot connection).

Zoom

Parameters detected from the message

Using Parameters

Use ((parameterName)) in Message, Embeds, Channel (bot mode) and Username Override (webhook mode) to fill them from pipeline data at run time. A parameter inside embeds is substituted into the JSON text, so a value containing a double quote breaks the JSON and the send is refused before anything is sent; keep such values in the message text.

Pipeline Integration

Use the Send Message functions you configure here as Discord Send Message nodes in the Pipeline Designer. See the Discord node page for the node's output.

Retries. Discord refusing a message (an unknown channel, a missing permission, an invalid embed) is a permanent error; retrying sends the same message to the same refusal. A timeout, a dropped connection, a 5xx or a rate limit leaves the outcome unknown: the message may already be posted, so Retry on Fail and store-and-forward can post it twice. Store-and-forward is available for this function; set a short maximum age so a buffered alert does not arrive long after the incident.

Common Use Cases

Line-stop alert with an embed

Pipeline Flow: OPC UA Read → Condition (status = fault) → Discord Send Message to #maintenance through a webhook.

Message:  Line ((line)) stopped
Embeds:   [{"title": "Fault ((code))", "description": "((reason))", "color": 15158332}]
Username Override: Line ((line))

Shift summary to several channels

One bot connection, one function per channel (or one function with ((channelId)) as the channel), posting the shift's OEE and scrap counts at the end of each shift.

Troubleshooting

Error	Cause	Fix
Unknown Webhook — Discord code 10015	The webhook was deleted	Create a new webhook and update the connection's Webhook URL
Invalid Webhook Token — Discord code 50027	The URL was mistyped or truncated	Copy the webhook URL again
401: Unauthorized (bot)	The bot token was reset or is wrong	Reset the token in the Developer Portal and update the connection
Unknown Channel — Discord code 10003	The channel ID is wrong, or the bot is not in that server	Check the ID; invite the bot to the server
Missing Access — Discord code 50001	The bot cannot see the channel	Grant the bot View Channel there
Missing Permissions — Discord code 50013	The bot may not post there	Grant Send Messages, and Embed Links for embeds
Invalid Form Body — Discord code 50035	Discord refused a field; the error names it (e.g. embeds.0.title: Must be 256 or fewer in length.)	Fix the named field
rate limited … retry after …	Too many messages to this webhook or channel	Send less often, or batch several events into one message
listing channels needs a bot connection	The channel picker was used on a webhook connection	A webhook always posts to its own channel; no channel needs choosing