Notifications and filtering

Notifications

These functions allow you to get information about a user’s notifications as well as to clear all or some notifications and to mark conversations as read.

Reading

Fetch notifications (mentions, favourites, reblogs, follows) for the logged-in user. Pass account_id to get only notifications originating from the given account.

There are different types of notifications:

follow - A user followed the logged in user
follow_request - A user has requested to follow the logged in user (for locked accounts)
favourite - A user favourited a post by the logged in user
reblog - A user reblogged a post by the logged in user
mention - A user mentioned the logged in user
poll - A poll the logged in user created or voted in has ended
update - A status the logged in user has reblogged (and only those, as of 4.0.0) has been edited
status - A user that the logged in user has enabned notifications for has enabled notify (see account_follow())
admin.sign_up - For accounts with appropriate permissions: A new user has signed up
admin.report - For accounts with appropriate permissions: A new report has been received
severed_relationships - Some of the logged in users relationships have been severed due to a moderation action on this server
moderation_warning - The logged in user has been warned by a moderator

Parameters exclude_types and types are array of these types, specifying them will in- or exclude the types of notifications given. It is legal to give both parameters at the same tine, the result will then be the intersection of the results of both filters. Specifying mentions_only is a deprecated way to set exclude_types to all but mentions.

Can be passed an id to fetch a single notification.

Added: Mastodon v1.0.0, last changed: Mastodon v3.5.0

Mastodon.notifications_unread_count() → UnreadNotificationsCount[source]

Fetch the number of unread notifications for the logged-in user.

Added: Mastodon v4.3.0, last changed: Mastodon v4.3.0 (parameters), Mastodon v4.3.0 (return value)

Writing

Mastodon.notifications_clear()[source]

Clear out a user’s notifications

Added: Mastodon v1.0.0, last changed: Mastodon v1.0.0

Mastodon.notifications_dismiss(id: Notification | str | int | MaybeSnowflakeIdType | datetime)[source]

Deletes a single notification

Added: Mastodon v1.3.0, last changed: Mastodon v2.9.2

Mastodon.conversations_read(id: Conversation | str | int | MaybeSnowflakeIdType | datetime)[source]

Marks a single conversation as read.

The returned object reflects the conversation’s new read status.

Added: Mastodon v2.6.0, last changed: Mastodon v2.6.0

Grouped notifications

This is the more modern notification API, which delivers notifications grouped.

Fetch grouped notifications for the user. Requires scope read:notifications.

For base parameters, see notifications().

grouped_types controls which notication types can be grouped together - all, if not specified. NB: “all” here means favourite, follow and reblog - other types are not groupable and are returned individually (with a unique group key) always.

Pass include_filtered=True to include filtered notifications in the response.

Pass expand_accounts=”full” to include full account details in the response, or “partial_avatars” to include a smaller set of account details (in the partial_accounts field) for some (but not all - the most recent account triggering a notification is always returned in full) of the included accounts. The default is partial_avatars.

Added: Mastodon v4.3.0, last changed: Mastodon v4.3.0 (parameters), Mastodon v4.3.0 (return value)

Mastodon.grouped_notification(group_key: str) → GroupedNotificationsResults[source]

Fetch details of a single grouped notification by its group key. Requires scope read:notifications.

Added: Mastodon v4.3.0, last changed: Mastodon v4.3.0 (parameters), Mastodon v4.3.0 (return value)

Mastodon.dismiss_grouped_notification(group_key: str) → None[source]

Dismiss a single grouped notification. Requires scope write:notifications.

Added: Mastodon v4.3.0, last changed: Mastodon v4.3.0

Mastodon.grouped_notification_accounts(group_key: str) → NonPaginatableList[Account][source]

Fetch accounts associated with a grouped notification. Requires scope write:notifications.

Added: Mastodon v4.3.0, last changed: Mastodon v4.3.0

Fetch the count of unread grouped notifications. Requires scope read:notifications.

For parameters, see notifications() and grouped_notifications().

Added: Mastodon v4.3.0, last changed: Mastodon v4.3.0

Source filtering for notifications

These functions allow you to get information about source filters as well as to create and update filters, and to accept or reject notification requests for filtered notifications.

Mastodon.notifications_policy() → NotificationPolicy[source]

Fetch the user’s notification filtering policy. Requires scope read:notifications.

Added: Mastodon v4.3.0, last changed: Mastodon v4.3.0 (parameters), Mastodon v4.3.0 (return value)

Mastodon.update_notifications_policy(for_not_following: str | None = None, for_not_followers: str | None = None, for_new_accounts: str | None = None, for_private_mentions: str | None = None, for_limited_accounts: str | None = None) → NotificationPolicy[source]

Update the user’s notification filtering policy. Requires scope write:notifications.

for_not_following: “accept”, “filter”, or “drop” notifications from non-followed accounts.
for_not_followers: “accept”, “filter”, or “drop” notifications from non-followers.
for_new_accounts: “accept”, “filter”, or “drop” notifications from accounts created in the past 30 days.
for_private_mentions: “accept”, “filter”, or “drop” notifications from private mentions.
for_limited_accounts: “accept”, “filter”, or “drop” notifications from accounts limited by moderators.

Added: Mastodon v4.3.0, last changed: Mastodon v4.3.0 (parameters), Mastodon v4.3.0 (return value)

Fetch notification requests filtered by the user’s policy. Requires scope read:notifications.

NB: Notification requests are what happens when the user has set their policy to filter notifications from some source.

Added: Mastodon v4.3.0, last changed: Mastodon v4.3.0

Mastodon.notification_request(id: NotificationRequest | str | int | MaybeSnowflakeIdType | datetime) → NotificationRequest[source]

Fetch a single notification request by ID. Requires scope read:notifications.

Added: Mastodon v4.3.0, last changed: Mastodon v4.3.0 (parameters), Mastodon v4.3.0 (return value)

Mastodon.accept_notification_request(id: NotificationRequest | str | int | MaybeSnowflakeIdType | datetime) → None[source]

Accept a notification request. This moves filtered notifications from a user back into the main notifications feed and allows future notifications from them. Requires scope write:notifications.

Added: Mastodon v4.3.0, last changed: Mastodon v4.3.0

Mastodon.dismiss_notification_request(id: NotificationRequest | str | int | MaybeSnowflakeIdType | datetime) → None[source]

Dismiss a notification request, removing it from pending requests. Requires scope write:notifications.

Added: Mastodon v4.3.0, last changed: Mastodon v4.3.0

Mastodon.accept_multiple_notification_requests(ids: List[NotificationRequest | str | int | MaybeSnowflakeIdType | datetime]) → None[source]

Accept multiple notification requests at once. This moves filtered notifications from those users back into the main notifications feed and allows future notifications from them. Requires scope write:notifications.

Added: Mastodon v4.3.0, last changed: Mastodon v4.3.0

Mastodon.dismiss_multiple_notification_requests(ids: List[NotificationRequest | str | int | MaybeSnowflakeIdType | datetime]) → None[source]

Dismiss multiple notification requests, removing them from pending requests. Requires scope write:notifications.

Added: Mastodon v4.3.0, last changed: Mastodon v4.3.0

Mastodon.notifications_merged() → bool[source]

Check whether accepted notification requests have been merged into the main notification feed. Accepting a notification request schedules a background job that merges the filtered notifications. Clients can poll this endpoint to check if the merge has completed. Requires scope read:notifications.

Added: Mastodon v4.3.0, last changed: Mastodon v4.3.0

Keyword Filters (v2)

These functions allow you to get information about keyword filters as well as to create and update filters.

NB: The filters are checked server side, but the server still returns all statuses to the client, just with a filtered attribute. Filtered notifications most likely end up as notification requests, but I have not validated this.

Mastodon.filters_v2() → NonPaginatableList[FilterV2][source]

Fetch all filters for the authenticated user.

Added: Mastodon v4.0.0, last changed: Mastodon v4.0.0

Mastodon.filter_v2(filter_id: Filter | str | int | MaybeSnowflakeIdType | datetime) → Filter[source]

Fetch a specific filter by its ID.

Added: Mastodon v4.0.0, last changed: Mastodon v4.0.0 (parameters), Mastodon v3.1.0 (return value)

Mastodon.create_filter_v2(title: str, context: List[str], filter_action: str, expires_in: int | None = None, keywords_attributes: List[Dict[str, str | bool]] | None = None) → FilterV2[source]

Create a new filter with the given parameters.

title is a human readable name for the filter.

context is list of contexts where the filter should apply. Valid values are:

“home”: Filter applies to the home timeline.
“notifications”: Filter applies to notifications. Filtered notifications land in notification requests.
“public”: Filter applies to the public timelines.
“thread”: Filter applies to conversations.
“account”: Filter applies to account timelines.

filter_action gives the policy to be applied when the filter is matched. Valid values are:

“warn”: The user is warned if the content matches the filter.
“hide”: The content is completely hidden if it matches the filter.

NB: Even if you specify “hide”, the status will still be returned - it will just have the “filtered” attribute set.

pass a number of seconds as expires_in to make the filter expire in that many seconds. Use None for no expiration.

pass a list of keyword dicts to initially as keywords_attributes, each with the following values:

“keyword”: The term to filter on.
“whole_word”: Whether word boundaries should be considered.

Added: Mastodon v4.0.0, last changed: Mastodon v4.0.0 (parameters), Mastodon v4.0.0 (return value)

Update an existing filter with the given parameters.

Parameters are as in create_filter_v2(). Only the parameters you want to update need to be provided.

Added: Mastodon v4.0.0, last changed: Mastodon v4.0.0 (parameters), Mastodon v4.0.0 (return value)

Mastodon.delete_filter_v2(filter_id: FilterV2 | str | int | MaybeSnowflakeIdType | datetime) → None[source]

Delete an existing filter.

Added: Mastodon v4.0.0, last changed: Mastodon v4.0.0

Mastodon.filter_keywords_v2(filter_id: FilterV2 | str | int | MaybeSnowflakeIdType | datetime) → NonPaginatableList[FilterKeyword][source]

Fetch all keywords associated with a given filter.

Added: Mastodon v4.0.0, last changed: Mastodon v4.0.0

Mastodon.add_filter_keyword_v2(filter_id: FilterV2 | str | int | MaybeSnowflakeIdType | datetime, keyword: str, whole_word: bool = False) → FilterKeyword[source]

Add a single keyword to an existing filter.

Parameters are as in create_filter_v2() keywords_attributes.

Added: Mastodon v4.0.0, last changed: Mastodon v4.0.0 (parameters), Mastodon v4.0.0 (return value)

Mastodon.delete_filter_keyword_v2(keyword_id: FilterKeyword | str | int | MaybeSnowflakeIdType | datetime) → None[source]

Delete a single keyword from any filter.

Added: Mastodon v4.0.0, last changed: Mastodon v4.0.0

Mastodon.filter_statuses_v2(filter_id: FilterV2 | str | int | MaybeSnowflakeIdType | datetime) → List[FilterStatus][source]

Retrieve all status-based filters for a FilterV2.

Added: Mastodon v4.0.0, last changed: Mastodon v4.0.0

Mastodon.add_filter_status_v2(filter_id: FilterV2 | str | int | MaybeSnowflakeIdType | datetime, status_id: Status | str | int | MaybeSnowflakeIdType | datetime) → FilterStatus[source]

Add a status to a filter, which will then match on that status in addition to any keywords. Includes reblogs, does not include replies.

Added: Mastodon v4.0.0, last changed: Mastodon v4.0.0 (parameters), Mastodon v4.0.0 (return value)

Mastodon.filter_status_v2(filter_status_id: FilterStatus | str | int | MaybeSnowflakeIdType | datetime) → FilterStatus[source]

Fetch a single status-based filter by its ID.

Added: Mastodon v4.0.0, last changed: Mastodon v4.0.0 (parameters), Mastodon v4.0.0 (return value)

Mastodon.delete_filter_status_v2(filter_status_id: FilterStatus | str | int | MaybeSnowflakeIdType | datetime) → None[source]

Remove a status filter from a FilterV2.

Added: Mastodon v4.0.0, last changed: Mastodon v4.0.0

Push notifications

Mastodon supports the delivery of notifications via webpush.

These functions allow you to manage webpush subscriptions and to decrypt received pushes. Note that the intended setup is not Mastodon pushing directly to a user’s client - the push endpoint should usually be a relay server that then takes care of delivering the (encrypted) push to the end user via some mechanism, where it can then be decrypted and displayed.

Mastodon allows an application to have one webpush subscription per user at a time.

All crypto utilities require Mastodon.py’s optional “webpush” feature dependencies (specifically, the “cryptography” and “http_ece” packages).

Mastodon.push_subscription() → WebPushSubscription[source]

Fetch the current push subscription the logged-in user has for this app.

Only one webpush subscription can be active at a time for any given app.

Added: Mastodon v2.4.0, last changed: Mastodon v2.4.0 (parameters), Mastodon v4.4.0 (return value)

Mastodon.push_subscription_set(endpoint: str, encrypt_params: Dict[str, str], follow_events: bool | None = None, favourite_events: bool | None = None, reblog_events: bool | None = None, mention_events: bool | None = None, poll_events: bool | None = None, follow_request_events: bool | None = None, status_events: bool | None = None, policy: str = 'all', update_events: bool | None = None, admin_sign_up_events: bool | None = None, admin_report_events: bool | None = None, standard: bool = None) → WebPushSubscription[source]

Sets up or modifies the push subscription the logged-in user has for this app.

endpoint is the endpoint URL mastodon should call for pushes. Note that mastodon requires https for this URL. encrypt_params is a dict with key parameters that allow the server to encrypt data for you: A public key pubkey and a shared secret auth. You can generate this as well as the corresponding private key using the push_subscription_generate_keys() function.

policy controls what sources will generate webpush events. Valid values are all, none, follower and followed.

The rest of the parameters controls what kind of events you wish to subscribe to. Events whose names start with “admin” require admin privileges to subscribe to.

follow_events controls whether you receive events when someone follows the logged in user.
favourite_events controls whether you receive events when someone favourites one of the logged in users statuses.
reblog_events controls whether you receive events when someone boosts one of the logged in users statuses.
mention_events controls whether you receive events when someone mentions the logged in user in a status.
poll_events controls whether you receive events when a poll the logged in user has voted in has ended.
follow_request_events controls whether you receive events when someone requests to follow the logged in user.
status_events controls whether you receive events when someone the logged in user has subscribed to notifications for posts a new status.
update_events controls whether you receive events when a status that the logged in user has boosted has been edited.
admin_sign_up_events controls whether you receive events when a new user signs up.
admin_report_events controls whether you receive events when a new report is received.

Pass standard=True to use the standard webpush subscription format, instead of the pre-release RFC format mastodon was using before.

Added: Mastodon v2.4.0, last changed: Mastodon v4..0 (parameters), Mastodon v4.4.0 (return value)

Modifies what kind of events the app wishes to subscribe to.

Parameters are as in push_subscription_set().

Returned object reflects the updated push subscription.

Added: Mastodon v2.4.0, last changed: Mastodon v2.4.0 (parameters), Mastodon v4.4.0 (return value)

Mastodon.push_subscription_generate_keys() → Tuple[Dict[str, str], Dict[str, str]][source]

Generates a private key, public key and shared secret for use in webpush subscriptions.

Returns two dicts: One with the private key and shared secret and another with the public key and shared secret.

Mastodon.push_subscription_decrypt_push(data: bytes, decrypt_params: Dict[str, str], encryption_header: str, crypto_key_header: str) → PushNotification[source]

Decrypts data received in a webpush request. Requires the private key dict from push_subscription_generate_keys() (decrypt_params) as well as the Encryption and server Crypto-Key headers from the received webpush

Added: Mastodon v2.4.0, last changed: Mastodon v2.4.0 (parameters), Mastodon v2.4.0 (return value)

Usage example

This is a minimal usage example for the push API, including a small http server to receive webpush notifications.

api = Mastodon(...)
keys = api.push_subscription_generate_keys()
api.push_subscription_set(endpoint, keys[1], mention_events=1)

class Handler(http.server.BaseHTTPRequestHandler):
    def do_POST(self):
        self.send_response(201)
        self.send_header('Location', '')  # Mastodon doesn't seem to care about this
        self.end_headers()
        data = self.rfile.read(int(self.headers['content-length']))
        np = api.push_subscription_decrypt_push(data, keys[0], self.headers['Encryption'], self.headers['Crypto-Key'])
        n = api.notifications(id=np.notification_id)
        s = n.status
        self.log_message('\nFrom: %s\n%s', s.account.acct, s.content)
httpd = http.server.HTTPServer(('', 42069), Handler)

try:
    httpd.serve_forever()
except KeyboardInterrupt:
    pass
finally:
    httpd.server_close()
    api.push_subscription_delete()

Keyword filters (v1, deprecated)

These functions allow you to get information about keyword filters as well as to create and update filters.

These APIs are deprecated in favor of the v2 APIs - I would recommend using those instead.

Reading

Mastodon.filters() → NonPaginatableList[Filter][source]

Fetch all of the logged-in user’s filters.

Added: Mastodon v2.4.3, last changed: Mastodon v2.4.3

Mastodon.filter(id: Filter | str | int | MaybeSnowflakeIdType | datetime) → Filter[source]

Fetches information about the filter with the specified id.

Added: Mastodon v2.4.3, last changed: Mastodon v2.4.3 (parameters), Mastodon v3.1.0 (return value)

Mastodon.filters_apply(objects: PaginatableList[Status] | PaginatableList[Notification], filters: NonPaginatableList[Filter] | NonPaginatableList[FilterV2], context: str) → PaginatableList[Status] | PaginatableList[Notification][source]

Helper function: Applies a list of filters to a list of either statuses or notifications and returns only those matched by none. This function will apply all filters that match the context provided in context, i.e. if you want to apply only notification-relevant filters, specify ‘notifications’. Valid contexts are ‘home’, ‘notifications’, ‘public’ and ‘thread’.

NB: This is for v1 filters. v2 filters are applied by the server, which adds the “filtered” attribute to filtered statuses.

Added: Mastodon v2.4.3, last changed: Mastodon v2.4.3

Writing

Mastodon.filter_create(phrase: str, context: str, irreversible: bool = False, whole_word: bool = True, expires_in: int | None = None) → Filter[source]

Creates a new keyword filter. phrase is the phrase that should be filtered out, context specifies from where to filter the keywords. Valid contexts are ‘home’, ‘notifications’, ‘public’ and ‘thread’.

Set irreversible to True if you want the filter to just delete statuses server side. This works only for the ‘home’ and ‘notifications’ contexts.

Set whole_word to False if you want to allow filter matches to start or end within a word, not only at word boundaries.

Set expires_in to specify for how many seconds the filter should be kept around.

Returns the newly created filter.

Added: Mastodon v2.4.3, last changed: Mastodon v2.4.3 (parameters), Mastodon v3.1.0 (return value)

Updates the filter with the given id. Parameters are the same as in filter_create().

Returns the updated filter.

Added: Mastodon v2.4.3, last changed: Mastodon v2.4.3 (parameters), Mastodon v3.1.0 (return value)

Deletes the filter with the given id.

Added: Mastodon v2.4.3, last changed: Mastodon v2.4.3