Discord
The Discord integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] lets you send notifications from Home Assistant to Discord channels and users via a bot. You can add channels or users as notification targets to send messages from the UI. You can use the notify action to attach files (such as images or videos) from local paths or remote URLs, and use Discord embeds for rich formatting.
This integration is for outgoing messages only. It cannot read incoming Discord messages or use them as triggers for automations.
Prerequisites
Creating a Discord application
To send notifications from Home Assistant, first create a Discord application with a bot user:
- Open the Discord Developer Portal and select New Application.
- Give the application a name and create it.
- In the application settings, open Bot.
- Under Token, select Reset Token to generate a bot token and store it securely. You will need this token when adding the Discord integration to Home Assistant.
Use the bot token from the Bot page. Do not use the Public Key or another application credential. Treat the bot token like a password and do not share it.
The name you give your application determines the name of the notify action. For example, if you enter “Home Assistant Notifications”, the action will be named notify.home_assistant_notifications.

Installing the bot on a Discord server
To allow the bot to send messages to a server:
- In the Discord Developer Portal, open Installation for your application.
- Under Installation Contexts, make sure Guild Install is enabled. User Install is not used by this Home Assistant integration and can be disabled.
- Under Install Link, select Discord Provided Link.
- Under Default Install Settings for Guild Install, add the
botscope. - Select the permissions the bot needs. To send notifications, grant Send Messages. Also grant Embed Links or Attach Files if you plan to use embeds or attachments.
- Save the changes, copy the install link, and open it in your browser.
- Select Add to server, choose the server, and authorize the application.
You need permission to manage the server to install the application.


For more information, see Discord’s application installation documentation.
Getting a channel ID
After the bot has been added to your server, get the channel ID of the channel you want the bot to send messages to:
- Open Discord and go to User Settings > Advanced.
- Enable Developer Mode.
- Right-click the channel name and select Copy Channel ID.
The channel ID, or a user ID for direct messages, is used when adding a notification target or when calling the notification action.
Add Discord integration to Home Assistant
Configuration
To add the Discord service to your Home Assistant instance, use this My button:
Manual configuration steps
If the above My button doesn’t work, you can also perform the following steps manually:
-
Browse to your Home Assistant instance.
-
In the bottom right corner, select the
Add Integration button. -
From the list, select Discord.
-
Follow the instructions on screen to complete the setup.
When adding the Discord integration, enter the bot token from the Discord application’s Bot page when asked for the API key.
Notification targets
A notification target is a Discord channel, user, or direct message that the bot can send messages to. Each target you add becomes a entityAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more] of the type notify, so you can send a message to it from the UI, an automation, or a script without needing the channel or user ID each time.
Add a notification target
- Go to Settings > Devices & services and select the Discord integration.
- Next to the Discord bot, select Add target.
- In Target ID, enter the ID of the channel, user, or direct message you want to send notifications to.
- Select Submit.
Home Assistant creates a notify entity named after the channel or user. Repeat these steps to add more targets.
Test a notification target
After adding a target, you can test it without creating an automation first:
- Go to Settings > Tools > Actions.
- Select the Notify entity: Send a message action.
- In Target, select the notify entity for your Discord target.
- Enter a message.
- Select Perform action.
Legacy notify action
Discord also provides a notify action that matches the name of your Discord application. Use this action when you need Discord embeds or file attachments, which the notify entity does not support.
Test a Discord notification
After setting up the integration, you can test the legacy action without creating an automation first:
- In Home Assistant, go to Settings > Tools > Actions.
- Select the
notifyaction that matches the name of your Discord application, for examplenotify.home_assistant_notifications. - Enter a message.
- In Target, enter the Discord channel ID or user ID.
- Select Perform action.
If the action does not appear, check that the Discord integration is configured successfully.
Use Discord in an automation
To send a message to a notification target from the automation editor:
- Go to Settings > Automations & scenes and create or edit an automation.
- Add an action and select Notify entity: Send a message.
- In Target, select the notify entity for your Discord target and enter the message.
- Save the automation.
To use Discord embeds or file attachments, use the legacy notify action instead. The examples below show the available Discord-specific options.
Set Message entry
The message field treats all input as literal text, including quotation marks.
For example: message: Hello, world! will appear exactly as is, while message: "Hello, world!" will include the quotation marks in the message.
Set Channel IDs as necessary
The target field is for the channel IDs where the message should be sent. Accepted data type is string for a single channel or string[] for multiple channels.
For example: "someChannelID" or ["someChannelID", "anotherChannelID"]
Pinging users, roles, or linking to other channels in the same server
You can use standard Discord methods to ping users, roles, and channels within the server.
| Type | Format |
|---|---|
User |
<@userID> |
Role |
<@&roleID> |
Channel |
<#channelID> |
Discord action data
The following attributes can be placed inside the data key of the action for extended functionality:
| Attribute | Optional | Description |
|---|---|---|
images |
yes | The file(s) to attach to message. |
urls |
yes | The file(s) to download from a remote URL and attach to message. |
verify_ssl |
yes | A boolean to determine if SSL certs should be verified when calling the remote URLs in the url attribute. Defaults to True. |
embed |
yes | Array of Discord embeds. NOTE: if using embed, message is still required. |
To include messages with embedding, use these attributes underneath the embed key:
| Attribute | Optional | Description |
|---|---|---|
title |
yes | Title of the embed. |
description |
yes | Description of the embed. |
color |
yes | Color code of the embed. This value is an int. |
url |
yes | Sets an embedded link for the title. |
author |
yes | Sets the author for the embed content. |
footer |
yes | Sets the footer for the embed content. |
thumbnail |
yes | Sets the thumbnail for the embed content. |
image |
yes | Sets the image for the embed content. |
fields |
yes | Adds a field to the embed object. name and value are required, inline is true by default. |
Example action
- action: notify.home_assistant_notifications
data:
message: "A message from Home Assistant"
target: ["1234567890", "0987654321"]
data:
images:
- "/tmp/garage_cam"
- "/tmp/garage.jpg"
Example action with attachments sourced from remote URLs
- action: notify.home_assistant_notifications
data:
message: "A message from Home Assistant"
target: ["1234567890", "0987654321"]
data:
verify_ssl: false
urls:
- "https://example.com/image.jpg"
- "https://example.com/video.mp4"
Note that verify_ssl defaults to True, and that any remote hosts will need to be in your allowlist_external_urls list. Discord limits attachment size to 8MB, so anything exceeding this will be skipped and noted in the error log.
Example embed action
- action: notify.home_assistant_notifications
data:
message: ""
target: ["1234567890", "0987654321"]
data:
embed:
title: 'title'
description: 'description'
url: 'https://www.home-assistant.io'
color: 199363
author:
name: 'Author Home Assistant'
url: 'https://www.home-assistant.io'
icon_url: 'https://www.home-assistant.io/images/favicon-192x192-full.png'
footer:
text: 'Footer Text'
icon_url: 'https://www.home-assistant.io'
thumbnail:
url: 'https://www.home-assistant.io/images/favicon-192x192-full.png'
image:
url: 'https://www.home-assistant.io/images/favicon-192x192-full.png'
fields:
- name: 'fieldname1'
value: 'valuename1'
inline: false
- name: 'fieldname2'
value: 'valuename2'
- name: 'fieldname3'
value: 'valuename3'
- name: 'fieldname4'
value: 'valuename4'
inline: false
Notes
You can tag any user inside a channel by using their user ID in the message like so: <@userid> replacing userid with the ID you copied. To get the user ID, right-click on the username to copy the ID like you did for the channel ID up above.
For more information about creating and authorizing bots, see Discord’s developer documentation.
To use notifications effectively, see the getting started with automation page.
Images are uploaded to Discord when a message is sent. As such, a local path to the image is required (that is, /config/www/garage.jpg as opposed to /local/garage.jpg), and updating an image after sending it in a message will not update the message in Discord.