From 77f122e6a81cb47b13cf00c65d8ae9ce6c1c7761 Mon Sep 17 00:00:00 2001 From: Andrew Jackson Date: Fri, 31 Jan 2025 14:20:59 +0000 Subject: [PATCH] Update mastodon documentation (#36735) * Update mastodon documentation * Fix nitpicks * Nitpicks --- source/_integrations/mastodon.markdown | 114 ++++++++++++++++--------- 1 file changed, 72 insertions(+), 42 deletions(-) diff --git a/source/_integrations/mastodon.markdown b/source/_integrations/mastodon.markdown index 108b8969de4..3d5b0bacd5e 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,13 +12,12 @@ 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 @@ -44,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 integration will create a `notify` action matching the name of the integration entry. +The Mastodon integration has the following actions: -### Action usage +- `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. +{% 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 `mastodon.post` + +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 %} -This will post a message to Mastodon that includes an image. +{% enddetails %} + +{% 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 %} -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. +{% enddetails %} + +{% details "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 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