From 5fdba0c29434570f6501658315f9d15ff8d05377 Mon Sep 17 00:00:00 2001 From: Andrew Jackson Date: Sun, 5 Jan 2025 14:40:07 +0000 Subject: [PATCH 1/3] Update mastodon documentation --- source/_integrations/mastodon.markdown | 136 +++++++++++++++++-------- 1 file changed, 93 insertions(+), 43 deletions(-) diff --git a/source/_integrations/mastodon.markdown b/source/_integrations/mastodon.markdown index 40149c2e01e1..b8009d4ff352 100644 --- a/source/_integrations/mastodon.markdown +++ b/source/_integrations/mastodon.markdown @@ -3,6 +3,7 @@ title: Mastodon description: Instructions on how to add Mastodon notifications to Home Assistant. ha_category: - Notifications + - Sensor ha_release: 0.67 ha_codeowners: - '@fabaff' @@ -11,91 +12,140 @@ 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 %} +{% configuration_basic %} +URL: + description: The URL of your Mastodon instance, for example `https://mastodon.social`. +Client key: + description: The client key for the application created within your Mastodon account web interface. +Client secret: + description: The client secret for the application created within your Mastodon account web interface. +Access token: + description: The access token for the application created within your Mastodon account web interface. +{% endconfiguration_basic %} + ## Sensors -The integration will create sensors for the Mastodon account showing total followers, following, and posts. +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. +### 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 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 marked 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 accounts 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 %} + +{% enddetails %} -This will post a message to Mastodon, but visibility is marked as `private` so only followers will see it. +{% 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 %} + +{% details "Example media post action" %} + +This will post a status to Mastodon that includes an image. -This will post a message 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 + +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. + +{% include integrations/remove_device_service.md %} From 2c37e50cae45f2c923220f1c1ed5c51d6ac7ff1c Mon Sep 17 00:00:00 2001 From: Andrew Jackson Date: Sun, 5 Jan 2025 16:12:12 +0000 Subject: [PATCH 2/3] Fix nitpicks --- source/_integrations/mastodon.markdown | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/_integrations/mastodon.markdown b/source/_integrations/mastodon.markdown index b8009d4ff352..89938081af3d 100644 --- a/source/_integrations/mastodon.markdown +++ b/source/_integrations/mastodon.markdown @@ -59,9 +59,9 @@ Post a status to your Mastodon account | `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 be shown as a warning before the text of the status. If not used, no warning will be displayed. | +| `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 marked the media as sensitive. `False` is default. | +| `media_warning` | Yes | If an image or video is attached, `True` will mark the media as sensitive. `False` is default. | {% 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. From cef281c542f193f446295da873ece3be3389420a Mon Sep 17 00:00:00 2001 From: Andrew Jackson Date: Sun, 5 Jan 2025 16:21:54 +0000 Subject: [PATCH 3/3] Nitpicks --- source/_integrations/mastodon.markdown | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/source/_integrations/mastodon.markdown b/source/_integrations/mastodon.markdown index 89938081af3d..3d5b0bacd5e2 100644 --- a/source/_integrations/mastodon.markdown +++ b/source/_integrations/mastodon.markdown @@ -1,6 +1,6 @@ --- 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 @@ -50,6 +50,10 @@ The Mastodon integration has the following actions: - `mastodon.post` +{% 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 @@ -71,7 +75,7 @@ You can get your `config_entry_id` by using actions within [Developer Tools](/do {% details "Example status post action" %} -Example post action that will post a status using your accounts default visibility: +Example post action that will post a status using your account's default visibility: {% raw %}