Discord
Hermoso posts into your Discord server and helps you run it: messages with embeds and native polls, forum posts and threads, announcements published to the servers that follow a channel, a direct message to a member, roles, the member list, pinned messages and scheduled events. Everything on this page costs no credits.
Two ways to connect
| Connection | What it can do |
|---|---|
| The Hermoso bot (Connectors, Discord, Add to Discord) | Everything on this page, in any channel the bot can see. One brand can add the bot to several servers; name one with discordServer. |
A channel webhook (paste its URL as announceWebhookUrl) | Posting into that one channel, with text, files, embeds, a poll, text-to-speech, and a display name and avatar for a single post. Editing, deleting and reading back the messages it posted. Nothing else. |
From an agent, connect_connector with {"provider": "discord"} and no fields returns the one-click link that adds the bot. A tool that needs the bot answers a brand that has only a webhook with a "not connected" error that says to add the bot.
After the bot is added, pick the channel it posts to by default with list_discord_channels and set_discord_channel, or on the Discord card. Any call can name another with channel (an id or #name).
Post: text, files, embeds, polls
post_to_discord sends one message. Mentions never ping anyone unless you pass mentions: true.
| Field | What it does | Discord's limit |
|---|---|---|
text | The message | 2,000 characters |
imageUrl, imageUrls, videoUrl | Files attached to the message | 10 files; 25 MB a message through the bot, 20 MB a file through a webhook. A larger file goes in as a link, and the reply says so. |
embeds | Rich cards under the text | 10 embeds, 6,000 characters across all of them |
poll | A native Discord poll | 10 answers, open 1 to 768 hours |
tts | A text-to-speech message, read aloud to people who have the channel open | |
crosspost | Bot only, announcement channels: also publish the post to every server that follows the channel | |
username, avatarUrl | Webhook posts only: a display name and avatar for this one post | Name up to 80 characters |
replyTo, threadId, startThread, threadName | Bot only: reply to a message, post inside a thread, open a thread under the post, or title a forum post | Thread name up to 100 characters |
silent | Post without a notification |
Anything over a limit is refused with the number, before anything is sent. Nothing is ever shortened for you.
Embeds
{
"text": "Release 2.3 is live.",
"embeds": [{
"title": "What changed",
"description": "Faster exports and a new editor.",
"url": "https://example.com/changelog",
"color": "#5865F2",
"fields": [
{ "name": "Exports", "value": "Twice as fast", "inline": true },
{ "name": "Editor", "value": "Rebuilt", "inline": true }
],
"author": { "name": "Acme", "url": "https://example.com", "iconUrl": "https://example.com/icon.png" },
"footer": { "text": "Thanks for the feedback" },
"image": "https://example.com/hero.png",
"thumbnail": "https://example.com/thumb.png",
"timestamp": "2026-12-01T18:00:00Z"
}]
}
| Part | Limit |
|---|---|
title | 256 characters |
description | 4,096 characters |
fields | 25 fields; each name 256 and value 1,024 characters |
footer.text | 2,048 characters |
author.name | 256 characters |
| All of the above, across every embed in the message | 6,000 characters |
color is a hex color such as #5865F2 or a whole number. image, thumbnail and the icons are full https:// links. timestamp is an ISO time, or "now". An embed key Discord does not let an app set (a video, for example) is refused by name.
Polls
{
"poll": {
"question": "Which feature next?",
"answers": ["Dark mode", { "text": "Mobile app", "emoji": "📱" }],
"durationHours": 48,
"multiselect": false
}
}
The question is up to 300 characters and each answer up to 55. A poll stays open 24 hours unless you say otherwise. Discord does not let a poll be edited once it is posted.
get_discord_pollreads the results: votes per answer, whether it is still open, and when it closes.voters: truealso lists who voted for each answer. Discord sometimes leaves the counts out of a read; that comes back as unknown, never as zero votes.end_discord_pollcloses a poll early. It is permanent, so the first call returns the votes so far and changes nothing; call again withconfirm: true.
Publish an announcement to following servers
Other servers can follow an announcement channel. crosspost: true on post_to_discord publishes the new post to all of them, and crosspost_discord_message does the same for a message that is already up. It works in announcement channels only, and it cannot be taken back short of deleting the message.
Scheduled posts
schedule_post with discord in channels takes the same parts in one field, discordExtras, next to discordChannel, discordServer, discordReplyTo, discordStartThread and discordMentions:
{
"channels": ["discord"],
"message": "Vote before Friday.",
"at": "2026-12-01T18:00:00Z",
"discordExtras": {
"embeds": [{ "title": "What we are deciding" }],
"poll": { "question": "Which feature next?", "answers": ["Dark mode", "Mobile app"] },
"tts": false,
"crosspost": false
}
}
An embed or a poll over a limit is refused when you schedule it, not when it fires.
Edit, delete and read
edit_discord_messagechanges the text of a message Hermoso posted.delete_discord_messagedeletes one. The first call quotes the message and deletes nothing; call again withconfirm: true.get_discord_messagereads a message back: its text, its embeds (title, description, fields, footer, link), its poll or poll result, what kind of message it is (a pin notice or a poll result is a message Discord writes itself), who posted it, and its reactions, the only engagement number Discord gives.read_discord_channelreads a channel's recent messages for context.
Threads
create_discord_threadstarts a thread in a text or announcement channel, on its own or under a message (messageId).kindispublic,private(text channels only) orannouncement.autoArchiveMinutesis 60, 1440, 4320 or 10080;slowmodeSecondsis 0 to 21600. It returns athreadIdthatpost_to_discordtakes.update_discord_threadarchives, reopens, locks or renames a thread. A locked thread can only be reopened by moderators.- A forum channel starts a thread with a post:
post_to_discordwiththreadName.
Direct messages
send_discord_dm sends one member a message from the Hermoso bot: text, embeds and files. userId is the member id that search_discord_members returns.
Discord decides who can be messaged. A bot can only message someone who shares a server with it and who allows direct messages from that server's members. When Discord refuses, you get its reason as it is. Their replies are read one person at a time: read_discord_channel with member, or list_inbox with discordMember (Discord gives a bot no list of its DMs). Discord also asks that a DM follow something the person did, and it blocks bots that open many DMs quickly, so this is for one person who is expecting it, never a broadcast. Hermoso only messages members of a server your brand added the bot to.
In the inbox
What people say to the Hermoso bot shows up in the inbox, in the app (Automations, then Inbox) and through list_inbox: messages that mention the bot or reply to one of its posts, from the channels with the newest messages. Each says which channel it is in and whether the bot has answered. reply_to_inbox_item answers one with a reply in that channel, where everyone in the channel can read it. Sending the same reply to the same message twice posts it once.
A direct message is read one member at a time, because Discord gives a bot no list of its DMs: list_inbox with discordMember, or read_discord_channel with member. Opening one sends nothing. The answer goes back as a DM. Slack works the same way for the direct messages people send the Hermoso app, and those are all listed with no argument.
Roles
| Tool | What it does | Needs a yes first |
|---|---|---|
list_discord_roles | Every role with what it may do, how many members hold it, and whether the bot can manage it | No |
create_discord_role | A new role: name (up to 100 characters), color, shown separately, mentionable, permissions by name | No |
update_discord_role | Change any of those | When the permissions change on a role people hold |
delete_discord_role | Delete a role for good; it comes off every member who holds it | Always |
assign_discord_role | Give one member a role | Always |
remove_discord_role | Take a role away from one member | Always |
"Needs a yes" means the first call changes nothing and returns a sentence to show the person: the role, the member, what the role carries and how many members hold it. Call again with confirm: true.
Discord only lets a bot manage roles that sit below its own role in the server's role list. If a role is refused for that reason, open Server Settings, Roles and drag the Hermoso role above it. Two roles at the same place in the list are ordered by age, the older one higher, so a role Hermoso creates sits below the Hermoso role and Hermoso can edit and delete it. The @everyone role and roles that belong to an app or to Discord (a bot's role, the booster role) cannot be handed out or deleted.
Members
search_discord_membersfinds members whose username or nickname starts with yourquery, or reads one byuserId. Use it to turn a name into the member id the DM and role tools take.list_discord_memberslists the server a page at a time:limit1 to 1000 (100 by default), then pass the returnednextAfterasafter.
Discord hands the full member list only to a bot with its Server Members setting switched on. When Discord withholds the list, the answer says so; it is never reported as an empty server, and searching by name keeps working.
Pinned messages
pin_discord_messagepins any message in a channel the bot can see, andunpin_discord_messagetakes it off the list.list_discord_pinslists a channel's pins, newest first, 50 a page.
A channel holds at most 250 pinned messages.
Scheduled events
Events appear in the server's Events panel, and members can mark themselves interested.
{
"name": "Founder AMA",
"description": "Bring your questions.",
"startsAt": "2026-12-01T18:00:00Z",
"endsAt": "2026-12-01T19:00:00Z",
"kind": "external",
"location": "https://example.com/live",
"imageUrl": "https://example.com/cover.png"
}
kind | Where it happens | Needs |
|---|---|---|
external | Outside Discord: a place or a link | location (up to 100 characters) and endsAt |
voice | A voice channel | channel |
stage | A stage channel | channel, plus three extra permissions (see below) |
create_discord_event: name up to 100 characters, description up to 1,000, and an optional cover (a JPG, PNG or GIF).list_discord_events: every event with its status and how many people are interested.update_discord_event: change the details, or move it withstatus:activestarts it,completedends a running event,canceledcalls off an upcoming one and keeps it in the server's history. Ending or cancelling is permanent and needsconfirm: true.delete_discord_event: removes it with no record. Needsconfirm: true.
A server can have 100 upcoming or running events at a time.
Permissions
When the bot is added it asks for the permissions these tools use:
| Permission | Used for |
|---|---|
| View Channel, Read Message History | Reading a channel, replying |
| Send Messages, Embed Links, Attach Files | Posts, embeds, files, publishing an announcement |
| Mention Everyone | Only when you pass mentions: true |
| Create Public Threads, Create Private Threads, Send Messages in Threads | Threads |
| Manage Threads | Archiving and locking a thread |
| Send Text-to-Speech Messages | tts |
| Send Polls | Polls |
| Pin Messages | Pinning and unpinning |
| Manage Roles | Roles, for roles below the Hermoso role only |
| Create Events, Manage Events, Connect | Scheduled events, including events in a voice channel |
The bot never asks for Manage Messages, Manage Channels, Administrator, or any permission to kick, ban or mute members. Two things follow from that:
- The bot publishes its own announcements. Publishing a message somebody else wrote needs Manage Messages on the Hermoso role.
- An event in a stage channel needs Manage Channels, Mute Members and Move Members for the Hermoso role in that channel. Tick them yourself if you want stage events; voice and external events need nothing extra.
Added the bot before 15 November 2026? It was added with a smaller set: polls, text-to-speech, pins, private threads, archiving threads, roles and events will answer that a permission is missing. Add the bot to the server again from Connectors, Discord (the invite now asks for the full set, and your channels and settings stay as they are), or tick the missing permission on the Hermoso role under Server Settings, Roles. check_discord_permissions tells you exactly what a server is missing, feature by feature.
A missing permission always comes back as a sentence that names the permission and says how to grant it, together with Discord's own words.
Every Discord tool
| Area | Tools |
|---|---|
| Posting | post_to_discord, edit_discord_message, delete_discord_message, get_discord_message, crosspost_discord_message |
| Channels | list_discord_channels, set_discord_channel, read_discord_channel |
| Polls | get_discord_poll, end_discord_poll |
| Threads | create_discord_thread, update_discord_thread |
| Direct messages | send_discord_dm |
| Roles | list_discord_roles, create_discord_role, update_discord_role, delete_discord_role, assign_discord_role, remove_discord_role |
| Members | list_discord_members, search_discord_members |
| Pins | list_discord_pins, pin_discord_message, unpin_discord_message |
| Events | list_discord_events, create_discord_event, update_discord_event, delete_discord_event |
| Setup | check_discord_permissions |
Over the REST API the same calls live under /api/discord/. Alerts into a Discord channel are a separate connection: see Alerts.