Mastodon


The mastodon platform uses Mastodon to deliver notifications from Home Assistant.

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.

Configuration

To add Mastodon to your installation, add the following to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI.[Learn more] file. After changing the configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI.[Learn more] file, restart Home Assistant to apply the changes. To view the changes, go to Settings > Devices & services > Entities.

# Example configuration.yaml entry
notify:
  - name: NOTIFIER_NAME
    platform: mastodon
    access_token: !secret mastodon_access_token
    client_id: !secret mastodon_client_id
    client_secret: !secret mastodon_client_secret

Configuration Variables

name string (Optional, default: notify)

The optional parameter name allows multiple notifiers to be created. The notifier will bind to the service notify.NOTIFIER_NAME.

access_token string Required

Your Mastodon access token.

client_id string Required

Your Mastodon client ID

client_secret string Required

Your Mastodon client secret.

base_url string (Optional)

URL of the Mastodon instance to use.

Usage

Mastodon is a notify platform, and can be used by calling notify service as described in the notify documentation. 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.

Service 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.

Service data

The following attributes can be placed inside data for extended functionality.

Service 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.

Example service call

This will post a message to Mastodon. Visibility will default to your account’s setting.

- service: notify.mastodon
  message: "A toot from Home Assistant"

Example service call - private

This will post a message to Mastodon, but visibility is marked as private so only followers will see it.

- service: notify.mastodon
  message: "A private toot from Home Assistant"
  target: private

Example service call - with media

This will post a message to Mastodon that includes an image.

- service: notify.mastodon
  message: "A media toot from Home Assistant"
  data:
    media: /config/www/funny_meme.png

Example service call - with media and content warning to hide post behind a warning

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.

- service: 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"

For more on how to use notifications in your automations, please see the getting started with automation page.