Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update mastodon documentation #36735

Open
wants to merge 4 commits into
base: next
Choose a base branch
from
Open

Update mastodon documentation #36735

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5fdba0c
Update mastodon documentation
andrew-codechimp Jan 5, 2025
d1b5c5b
Merge branch 'next' into mastodon-post-action
andrew-codechimp Jan 5, 2025
2c37e50
Fix nitpicks
andrew-codechimp Jan 5, 2025
cef281c
Nitpicks
andrew-codechimp Jan 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 76 additions & 43 deletions source/_integrations/mastodon.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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'
Expand All @@ -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 %}

Expand All @@ -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
Expand Down
Loading