mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-19 15:26:59 +00:00
Update mastodon documentation (#36735)
* Update mastodon documentation * Fix nitpicks * Nitpicks
This commit is contained in:
Andrew Jackson
GitHub
parent
02928815d0
commit
77f122e6a8
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user