Relay Subscriptions

GoToSocial allows you (as admin) to create subscriptions to ActivityPub relays in order to populate your instance with posts that you may not otherwise have seen by just following other accounts across the fediverse.

What is a relay?

An ActivityPub relay is a software that exposes one or more ActivityPub-compatible actors, which accept posts in one or more inboxes, and then forward (ie., "Announce") those posts to actors who are subscribed to (ie., "Follow") the relay actor(s).

What happens when you subscribe to a relay?

When you create a relay subscription (see below), the service actor for your instance will send a follow request to the relay actor. When the follow request is accepted, either automatically, or pending a manual action by the administrator of the relay, your instance service actor will begin to receive posts from the relay in its inbox. Posts received in this way will be ingested into your instance and shown in the federated timeline (if applicable).

Create a relay subscription

You can subscribe to a relay by using the admin settings panel to input the relay actor URI, and select flags that you would like to apply to the relay connection.

Relay actor URI

A relay actor URI usually looks something like https://relay.example.org/actor, but for the precise URI you should check the documentation or homepage of the relay you would like to connect to.

Flags

The flag checkboxes allow you to customize which posts should be ingested by the relay subscription.

Ingest public visibility posts:

By checking this flag, you instruct GoToSocial to ingest Public posts via this relay subscription. If the box is not checked, then posts with Public visibility will never be ingested by the relay subscription.

Ingest unlisted visibility posts:

By checking this flag, you instruct GoToSocial to ingest Unlisted (aka Unlocked, aka Quiet Public) posts via this relay subscription. If the box is not checked, then posts with Unlisted visibility will never be ingested by the relay subscription.

Never ingest posts marked as sensitive:

With this flag checked, this relay subscription will never ingest a post that was marked as sensitive by the author, even if such a post would normally be matched and ingested.

Never ingest posts with media:

With this flag checked, this relay subscription will never ingest a post that has media attachments, even if such a post would normally be matched and ingested. This can be useful to avoid ballooning an instance's storage size when it subscribes to a relay that has lots of media posts.

Never ingest replies/comments:

With this flag checked, this relay subscription will never ingest replies or comments that are forwarded to it by the relay. In this context, a reply or comment is a post that replies to the post of another author. Note that even if you check this flag, GoToSocial will still try to dereference comments on top-level posts or self-reply thread posts that are sent to it by the relay.

Match posts by default:

With this flag checked, you tell GoToSocial that all posts sent to it via this relay subscription should be matched by default. In other words, any posts (of appropriate visibilities) that are not ignored because of other flags will be ingested, unless their content is matched by an exclude matcher. With the flag unchecked, posts will only be ingested if their content is matched by one or more matchers.

Any posts that should not be ingested by the relay subscription, according to the above flags, will be dropped.

Relay matchers

Using relay matchers, you can either include or exclude posts from relaying by matching keywords (whole words or partial) in the post.

To create a relay matcher, open the detailed view of a relay connection. Below the relay update form, you will see a "Matchers" section. Here, you can view existing matchers, create a new matcher, and/or delete an existing matcher.

The matcher keyword is the phrase to be matched. For example, "sloth". Matcher keywords are case insensitive, so "Sloth", "sloth", and "SLOTH" etc are all equivalent.

If you want to match the keyword as a whole word, tick the "Match whole word" checkbox when creating a matcher. With this checkbox ticked, the matcher "sloth" will match a post with content "I saw a cool sloth today", but will not match with the post "I saw some cool sloths today". By contrast, with the box unticked, any post containing a word with the fragment "sloth" in it will match. So "I saw some cool sloths today" will match.

Keyword matches are made against a post's content and its content warning (if present).

To create an exclude matcher, tick the checkbox "Exclude posts matched by this matcher" when creating a new matcher. When a post matches an exclude matcher, it is never relayed, even if other matchers would include it, or the relay connection matches all posts by default.