diff --git a/source/_integrations/mastodon.markdown b/source/_integrations/mastodon.markdown index 2d69ed5232f8..3d5b0bacd5e2 100644 --- a/source/_integrations/mastodon.markdown +++ b/source/_integrations/mastodon.markdown @@ -1,8 +1,9 @@ --- title: Mastodon -description: Instructions on how to add Mastodon notifications to Home Assistant. +description: Instructions on how to add Mastodon posts and account statistics to Home Assistant. ha_category: - Notifications + - Sensor ha_release: 0.67 ha_codeowners: - '@fabaff' @@ -11,18 +12,20 @@ ha_domain: mastodon ha_iot_class: Cloud Polling ha_platforms: - diagnostics - - notify - sensor ha_integration_type: service ha_config_flow: true --- -The `mastodon` platform uses [Mastodon](https://joinmastodon.org/) to deliver notifications from Home Assistant. +The `mastodon` platform uses [Mastodon](https://joinmastodon.org/) to post status updates and get account statistics. ### Setup Go to **Preferences** in the Mastodon web interface, then to **Development** and create a new application. -If you want to grant only required accesses, uncheck all checkboxes then check only **read:accounts** and **write:statuses**. + +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. {% include integrations/config_flow.md %} @@ -41,74 +44,104 @@ Access token: The integration will create sensors for the Mastodon account showing total followers, following, and posts. Sensors are updated once an hour. -## Notifications +## Actions + +The Mastodon integration has the following actions: + +- `mastodon.post` -The integration will create a `notify` action matching the name of the integration entry. +{% note %} +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. +{% endnote %} -### Action usage +### Action `mastodon.post` -Mastodon is a notify platform, and can be used by calling notify action as described in the [notify documentation](/integrations/notify/). It will toot messages using -your account. An optional **target** parameter can be given to specify whether your toot will be public, private, unlisted, or direct. +Post a status to your Mastodon account | Data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `message` | no | Body of the notification. -| `target` | 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. -| `data` | yes | See below for extended functionality. +|------------------------|----------|-------------| +| `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_warning` | Yes | If an image or video is attached, `True` will mark the media as sensitive. `False` is default. | -### Action data +{% tip %} +You can get your `config_entry_id` by using actions within [Developer Tools](/docs/tools/dev-tools/), using one of the above actions and viewing the YAML. +{% endtip %} -The following attributes can be placed inside `data` for extended functionality. +### Examples -| Data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `media` | yes | Attach an image or video to the message. -| `media_warning` | yes | If an image or video is attached, `True`: will marked the media as sensitive. `False` is default. -| `content_warning` | yes | Text will be be shown as a warning before the text of the status. If not used, no warning will be displayed. +{% details "Example status post action" %} -### Example action +Example post action that will post a status using your account's default visibility: -This will post a message to Mastodon. Visibility will default to your account's setting. +{% raw %} ```yaml -- action: notify.mastodon - message: "A toot from Home Assistant" +- action: mastodon.post + config_entry_id: YOUR_MASTODON_CONFIG_ENTITY_ID + status: "A toot from Home Assistant" ``` -### Example action - private +{% endraw %} -This will post a message to Mastodon, but visibility is marked as `private` so only followers will see it. +{% enddetails %} + +{% details "Example private post action" %} + +This will post a status to Mastodon, but visibility is marked as `private` so only followers will see it. + +{% raw %} ```yaml -- action: notify.mastodon - message: "A private toot from Home Assistant" - target: private +- action: mastodon.post + config_entry_id: YOUR_MASTODON_CONFIG_ENTITY_ID + status: "A private toot from Home Assistant" + visibility: private ``` -### Example action - with media +{% endraw %} + +{% enddetails %} -This will post a message to Mastodon that includes an image. +{% details "Example media post action" %} + +This will post a status to Mastodon that includes an image. + +{% raw %} ```yaml -- action: notify.mastodon - message: "A media toot from Home Assistant" - data: - media: /config/www/funny_meme.png +- 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 action - with media and content warning to hide post behind a warning +{% endraw %} + +{% enddetails %} + +{% details "Example post with media and a content warning that will not be visible in the public timeline" %} -This will post a message to Mastodon that includes an image and a target of `unlisted`, so it doesn't show in the public timeline. +This will post a status to Mastodon that includes an image, with a content warning and a visibility of `unlisted`, so it doesn't show in the public timeline. + +{% raw %} ```yaml -- action: notify.mastodon - message: "A media toot from Home Assistant" - target: unlisted - data: - media: /config/www/funny_meme.png - content_warning: "This might not be funny enough" +- 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 + content_warning: "This might not be funny enough" ``` +{% endraw %} + +{% enddetails %} + For more on how to use notifications in your automations, please see the [getting started with automation page](/getting-started/automation/). ## Known limitations