Mastodon
The mastodon platform uses Mastodon
Setup
Go to Preferences in the Mastodon web interface, then to Development and create a new application.
Check the following scopes read:accounts, write:statuses and write:media.
Select Submit to create the application and generate the key, secret, and token required for the integration.
Configuration
To add the Mastodon service to your Home Assistant instance, use this My button:
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 Mastodon.
-
Follow the instructions on screen to complete the setup.
The client secret for the application created within your Mastodon account web interface.
Sensors
The integration will create sensors for the Mastodon account showing total followers, following, and posts. Sensors are updated once an hour.
Actions
The Mastodon integration has the following actions:
mastodon.post
The previous notify.mastodon service has been deprecated in favor of the new mastodon.post action. If you’re upgrading from a previous version, you’ll need to update your automations to use the new action format shown below.
Action mastodon.post
Post a status to your Mastodon account
| Data attribute | Optional | Description |
|---|---|---|
config_entry_id |
No | The ID of the Mastodon config entry to post to. |
status |
No | The status text to post. |
visibility |
Yes | If not used, will default to account setting. public: post will be public, unlisted: post will be public but not appear on the public timeline, private: post will only be visible to followers, and direct: post will only be visible to mentioned users. |
content_warning |
Yes | Text will be shown as a warning before the text of the status. If not used, no warning will be displayed. |
media |
Yes | Attach an image or video to the post. |
media_description |
Yes | If an image or video is attached, will add a description for this media for people with visual impairments. |
media_warning |
Yes | If an image or video is attached, True will mark the media as sensitive. False is default. |
You can get your config_entry_id by using actions within Developer Tools, using one of the above actions and viewing the YAML.
Examples
Example status post action
Example post action that will post a status using your account’s default visibility:
- action: mastodon.post
config_entry_id: YOUR_MASTODON_CONFIG_ENTITY_ID
status: "A toot from Home Assistant"
Example private post action
This will post a status to Mastodon, but visibility is marked as private so only followers will see it.
- action: mastodon.post
config_entry_id: YOUR_MASTODON_CONFIG_ENTITY_ID
status: "A private toot from Home Assistant"
visibility: private
Example media post action
This will post a status to Mastodon that includes an image.
- action: mastodon.post
config_entry_id: YOUR_MASTODON_CONFIG_ENTITY_ID
status: "A media toot from Home Assistant"
media: /config/www/funny_meme.png
Example post with media and a content warning that will not be visible in the public timeline
This will post a status to Mastodon that includes an image, with a description, a content warning, and a visibility of unlisted, so it doesn’t show in the public timeline.
- action: mastodon.post
config_entry_id: YOUR_MASTODON_CONFIG_ENTITY_ID
status: "A media toot from Home Assistant"
visibility: unlisted
media: /config/www/funny_meme.png
media_description: "A funny meme"
content_warning: "This might not be funny enough"
For more on how to use notifications in your automations, please see the getting started with automation page.
Known limitations
The integration only allows reading the status of the authenticated account and posting to that account. It does not provide functionality to get the stream, favorite, bookmark, or boost posts of that account.
Removing the integration
This integration follows standard integration removal, once the integration is removed you can remove the application registration (assuming it was only used by this integration) from your Mastodon account by going to Preferences in the Mastodon web interface, then to Development and deleting the application you created for Home Assistant.
To remove an integration instance from Home Assistant
- Go to Settings > Devices & services and select the integration card.
- From the list of devices, select the integration instance you want to remove.
- Next to the entry, select the three-dot
menu. Then, select Delete.