Update Discord integration documentation#44701
Update Discord integration documentation#44701ranarn wants to merge 1 commit intohome-assistant:nextfrom
Conversation
home-assistant
Bot
added
has-parent
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Updates the Discord integration documentation to match the rewritten Home Assistant integration (config flow + per-channel/user notify entities) and the new discord.send_message service capabilities.
Changes:
- Replaces legacy
notify.discord/targetdocumentation with config-flow + “add entry” channel/user entity workflow. - Documents
discord.send_messagefields including attachments (local + URL) and embed structure. - Updates Discord links to
discord.comand refreshes examples.
| Next, decide what permissions your bot will have within your server. Under the 'Bot' section, select the permissions you want to grant and copy the permissions integer from the bottom field. | ||
| 1. In the Developer Portal, go to **OAuth2** > **URL Generator**. | ||
| 2. Under **Scopes**, select `bot`. | ||
| 3. Under **Bot Permissions**, select at minimum **Send Messages** (and **Attach Files** if you want to send images). |
There was a problem hiding this comment.
Discord bots generally also need View Channels (and potentially Read Message History) to post into a channel, depending on server/channel permission overrides. The instructions currently claim Send Messages is the minimum, which can lead to a bot that cannot see/post in the target channel. Update the minimum permissions list to include View Channels (and consider mentioning Read Message History as commonly required).
| 3. Under **Bot Permissions**, select at minimum **Send Messages** (and **Attach Files** if you want to send images). | |
| 3. Under **Bot Permissions**, select at minimum **View Channels** and **Send Messages**. **Read Message History** is also commonly required, and select **Attach Files** if you want to send images. |
| 1. Go to **Settings** > **Devices & Services** > **Discord**. | ||
| 2. Click **Add entry** under your bot. | ||
| 3. Enter the **Channel or User ID** you copied from Discord. | ||
| 4. Click **Submit** — Home Assistant will verify the channel exists and create a notification entity for it. |
There was a problem hiding this comment.
Step 4 says Home Assistant will verify the channel exists, but this flow also supports user IDs. Adjust wording to reflect both cases (e.g., 'verify the channel or user exists') to avoid confusing users adding a user ID.
| 4. Click **Submit** — Home Assistant will verify the channel exists and create a notification entity for it. | |
| 4. Click **Submit** — Home Assistant will verify the channel or user exists and create a notification entity for it. |
| target: | ||
| entity_id: notify.my_bot_general | ||
| data: | ||
| message: "" |
There was a problem hiding this comment.
The table above marks message as required, but the rich-embed example uses an empty string. If the service enforces a non-empty message (or Discord rejects empty content), this example will fail. Either provide a non-empty message in the example (e.g., a short summary) or clarify in the field docs whether an empty message is acceptable when embed is provided.
| message: "" | |
| message: "Home Assistant Alert" |
Proposed change
Updates the Discord integration documentation to reflect the rewrite of the integration.
notify.discordservice andtargetfield documentationdiscord.send_messageaction with embeds, file attachments, and URL attachmentsType of change
nextbranch)Additional information
Companion core PRs:
discord.send_messageservice to comeChecklist
nextbranch