hermosodocs

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

ConnectionWhat 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.

FieldWhat it doesDiscord's limit
textThe message2,000 characters
imageUrl, imageUrls, videoUrlFiles attached to the message10 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.
embedsRich cards under the text10 embeds, 6,000 characters across all of them
pollA native Discord poll10 answers, open 1 to 768 hours
ttsA text-to-speech message, read aloud to people who have the channel open
crosspostBot only, announcement channels: also publish the post to every server that follows the channel
username, avatarUrlWebhook posts only: a display name and avatar for this one postName up to 80 characters
replyTo, threadId, startThread, threadNameBot only: reply to a message, post inside a thread, open a thread under the post, or title a forum postThread name up to 100 characters
silentPost 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"
  }]
}
PartLimit
title256 characters
description4,096 characters
fields25 fields; each name 256 and value 1,024 characters
footer.text2,048 characters
author.name256 characters
All of the above, across every embed in the message6,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.

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

Threads

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

ToolWhat it doesNeeds a yes first
list_discord_rolesEvery role with what it may do, how many members hold it, and whether the bot can manage itNo
create_discord_roleA new role: name (up to 100 characters), color, shown separately, mentionable, permissions by nameNo
update_discord_roleChange any of thoseWhen the permissions change on a role people hold
delete_discord_roleDelete a role for good; it comes off every member who holds itAlways
assign_discord_roleGive one member a roleAlways
remove_discord_roleTake a role away from one memberAlways

"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

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

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"
}
kindWhere it happensNeeds
externalOutside Discord: a place or a linklocation (up to 100 characters) and endsAt
voiceA voice channelchannel
stageA stage channelchannel, plus three extra permissions (see below)

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:

PermissionUsed for
View Channel, Read Message HistoryReading a channel, replying
Send Messages, Embed Links, Attach FilesPosts, embeds, files, publishing an announcement
Mention EveryoneOnly when you pass mentions: true
Create Public Threads, Create Private Threads, Send Messages in ThreadsThreads
Manage ThreadsArchiving and locking a thread
Send Text-to-Speech Messagestts
Send PollsPolls
Pin MessagesPinning and unpinning
Manage RolesRoles, for roles below the Hermoso role only
Create Events, Manage Events, ConnectScheduled 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:

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

AreaTools
Postingpost_to_discord, edit_discord_message, delete_discord_message, get_discord_message, crosspost_discord_message
Channelslist_discord_channels, set_discord_channel, read_discord_channel
Pollsget_discord_poll, end_discord_poll
Threadscreate_discord_thread, update_discord_thread
Direct messagessend_discord_dm
Roleslist_discord_roles, create_discord_role, update_discord_role, delete_discord_role, assign_discord_role, remove_discord_role
Memberslist_discord_members, search_discord_members
Pinslist_discord_pins, pin_discord_message, unpin_discord_message
Eventslist_discord_events, create_discord_event, update_discord_event, delete_discord_event
Setupcheck_discord_permissions

Over the REST API the same calls live under /api/discord/. Alerts into a Discord channel are a separate connection: see Alerts.