From 360bff82666661a5f5fe7cf314b5862f077d772f Mon Sep 17 00:00:00 2001 From: Chris Caron Date: Fri, 11 Nov 2022 14:57:28 -0500 Subject: [PATCH] Created Notify_mastodon (markdown) --- Notify_mastodon.md | 112 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 Notify_mastodon.md diff --git a/Notify_mastodon.md b/Notify_mastodon.md new file mode 100644 index 0000000..0db3c2c --- /dev/null +++ b/Notify_mastodon.md @@ -0,0 +1,112 @@ +## Mastodon Notifications +* **Source**: https://joinmastodon.org +* **Attachment Support**: Yes +* **Icon Support**: No +* **Message Format**: Text +* **Message Limit**: 500 + +### Account Setup +Sign up for any Mastodon based service. [Here are a few you can choose from today](https://joinmastodon.org/servers). + +In the **Settings** of your account, you can access the **Development** tab and create an **Application**. This is what Apprise will use to send your notifications. + +At the bare minimum you need to grant the: + +- `write:statuses`: So Apprise can post a message +- `write:media`: So Apprise can send an attachment +- `read:accounts`: If you want to be able to send a DM to yourself + +**Note**: If you change/add/remove scope entries associated with your Mastodon Application, you **MUST** regenerate your **Access Token** or your app will not take in effect the scope changes. + +After you create your Application, revisit it's configuration as it will now provide you with a `key`, `secret`, and `access_token`. You ONLY need the **Access Token** to have Apprise work. + +### Syntax +Valid syntax is as follows: +* `mastodon://{token}@{host}` +* `mastodons://{token}@{host}` +* `toot://{token}@{host}` +* `toot://{token}@{host}` +* `mastodon://{token}@{host}/{targets}` +* `mastodons://{token}@{host}/{targets}` +* `toot://{token}@{host}/{targets}` +* `toot://{token}@{host}/{targets}` + +Simply use `mastodon://` or `toot://` if access in an insecure server and `mastodons://` or `toots://` if accessing a secure one (https). + +### Parameter Breakdown +| Variable | Required | Description +| --------------- | -------- | ----------- +| token | Yes | The Access Token associated with the Application you created (in Mastodon's Account Settings). Your token MUST have at the bare minimum `write:statuses` access. Additionally provide `write:media` if you intend to provide attachments. +| visibility | No | The Mastodon visibility you want to operate in. Possible values are
`direct` for Private Direct Messages)
`private` for posts that will be visible only to followers
`unlisted` for posts that will be public but not appear on the public timeline
`public` for public posts
`default` for post visibility based on the accounts _default-visiblity_ setting.

By default if `toot://` is used, it is presumed you want a public post (unless you explicitly specify the `visibility=` flag. However if you use `mastodon://` then your post by default will take on the _default-visibility_ associated with your account unless explicitly over-ridden here with the `visibility=`. +| batch | No | By default images are batched together. However if you want your attachments to be posted 1 toot per attachment, set this to False. +| sensitive | No | If this is set to `Yes` then any attachments provided will be marked as sensitive. By default this is set to `No` +| spoiler | No | Optionally provide _spoiler text_ that should be associated with the status message posted. +| language | No | Optionally provide a ISO 639 language code with your status post. E.g. `en`, `fr`, etc. +| key | No | Prevent duplicate submissions of the same status. Idempotency keys are stored for up to 1 hour, and can be any arbitrary string. Consider using a hash or UUID generated client-side. + +### Smart Processing +With Mastodon, routing of `direct` messages entirely depends on the `@users` identified in the message body. For this reason it's possible to post a status message like: +```bash +apprise -b "Hey guys, this message was sent from Apprise" \ + "mastodon://accesskey/host/@caronc?visibility=direct" +``` + +This will cause the message body to be created as +``` +Hey guys, this message was sent from Apprise @caronc +``` + +It's important to state that if you identify `/@users` entries on your Apprise URL, they will be appended into the message so they are notified. However, that said, if you prepare a URL for `direct` visibility and do not provide a user. Apprise will look up your own credentials automatically and send the message to yourself. +``` +# Here is an example where we're specifying a `direct` message +# as our intentions are to create a DM. This will cause Apprise to look +# ourselves up and notify our own account. You MUST have the +# 'read:accounts' scope enabled on your Mastodon application or this +# will not work. +# +# Also consider there is overhead with this call as it requires an +# extra hit on the website to get your data. For efficiency, it's +# ideal that you specify your @user if this is your intention. +apprise -b "Hey guys, this message was sent from Apprise" \ + "mastodon://accesskey/host/?visibility=direct" +``` + +Apprise is also smart enough to pre-scan the message being posted and if it finds a `@user` identified in the body that is also identified in the URL, it will NOT be added to the end of the body. Hence; consider a status message that reads: +```bash +apprise -b "Hey @caronc, Thanks for showing me the Apprise plugin!" \ + "mastodon://accesskey/host/@caronc?visibility=direct" +``` +In the above case, `@caronc` is identified as both a target to be delivered to AND also already exists in the status message being sent. As a result, no `@caronc` will be appended at the end and the message will be sent as is. +``` +Hey @caronc, Thanks for showing me the Apprise plugin! +``` + +Let's do one more example just to show other cases: + +Consider the following: +```bash +apprise -b "Hey @caronc, Thanks for showing me the Apprise plugin!" \ + "mastodon://accesskey/host/@caronc/@joe/@sam?visibility=direct" +``` +The following has 3 people set up as targets, but it has already identified 1 of them in the message. The other 2 are automatically appended to the end of your status message: +``` +Hey @caronc, Thanks for showing me the Apprise plugin! @joe @sam +``` + +#### Example +Send a Mastodon toot: +```bash +# Assuming our {AccessKey} is T1JJ3T3L2 +# Assuming our {Host} is noc.social +apprise -vv -t "Test Message Title" -b "Test Message Body" \ + "mastodons://T1JJ3T3L2@noc.social" +``` + +Send a Mastodon DM to @testaccount: +```bash +# Assuming our {AccessKey} is T1JJ3T3L2 +# Assuming our {Host} is noc.social +# our user is @testaccount +apprise -vv -t "Test Message Title" -b "Test Message Body" \ + "mastodons://T1JJ3T3L2@noc.social/@testaccount?visibility=direct" +```