21

DispatchMetaReference

by August. . 815 reads.

NSNexus Documentation

Last updated on Sunday, January 31st, 2021. If you find this dispatch helpful, please upvote.
Logo: Betmet


| ABOUT | CREATIVE USES | OPEN SOURCE | NSNEXUS | NSVERIFY | PRIVACY | PSEUDO-API | RMB COMMANDS | STATISTICS | STOCK EXCHANGE |


NSNexus is a feature of the AugustinAndroid v2 Discord bot. It links all Discord servers that operate any edition of the bot, allowing for easy and seamless inter-server communication between their members. Servers can connect to any or all of the following: the global news stream, which permits official updates from regions and organizations; the global chat stream, which permits general chatter; and embassies, which are two-way portals between a pair of servers.

Using a stream is easy. A member simply sends a message in the stream's channel on their server, and it is instantly transmitted to all other servers connected to that stream, even ones using a different edition of the bot. The message and sender appear identically in every server, even if the sender is not in that server. The screenshot below shows an exchange from two members of separate servers, viewed from a third server.

As of writing, the system is public and fully operational. See the next section for instructions on adding it to your server.

Return to top


Global Streams

If AugustinAndroid v2 is not currently on your server:
1. LinkInvite the bot to your server and complete the initial setup process. This process automatically starts in the server owner's private messages, and cannot be completed elsewhere.
2. Congratulations! You are done. The setup process creates and activates the global stream channels for you.

If AugustinAndroid v2 is already on your server:
1. Open the settings menu with the command >settings. Navigate to submenu ⓿ and enable NSNexus.
2. Create a channel for the stream you want. You can name it anything, but we will use #nsn_global_news as an example.
3. Use the command >nexus set_channel news #nsn_global_news.
4. Congratulations! You are done. Repeat this process, replacing "news" with "chat," to get both global streams.

Embassy Streams

1. Make sure AugustinAndroid v2 is on your server and the server you wish to invite, and has NSNexus enabled on both.
2. Get the server ID of the server you wish to invite. If you are in the other server, you can right-click its icon and select "Copy ID," or use the command >nexus list_servers.
3. Use the command >nexus invite [server ID] (no brackets) on your server.
4. Wait for the other server to respond. The invitation times out in six minutes, so it is a good idea to coordinate things with the other server's staff first.
5. Congratulations (or not)! You are done. If the other server accepted, an embassy channel will be set up and activated automatically. If not, better luck next time.

Return to top


Behind the scenes, NSNexus uses a complex series of handoffs to transfer messages between servers with discrete instances of the bot.

Delivery: Global Streams

1. A member sends a message in a stream channel on one server.
2. The bot on that server makes sure the sender and message meet all necessary conditions (verified, not globally blacklisted from bot usage, not a bot or bot command).
3. It converts the message to an embed, preserving the member's color and nickname and nullifying @mentions in the message, and saves the member's avatar.
4. It deletes the original message.
5. It iterates through all its servers (including the one where the message originated) and checks in each one that the sender meets all necessary conditions (not banned, muted, or ignored).
6. In each server, it uses a webhook to send the message with the avatar and nickname of the original sender. This webhook is created ahead of time and cached for speed. When the bot first starts, this cache will be empty, and delivery will be slightly slower.
7. A direct link to each message is saved to a database, tied to the original message.
8. It drops the message in the stream hub (not accessible to normal users) on its support server, where other instances of the bot pick it up and repeat step 4 for all their own servers (except the support server).

Delivery: Embassy Streams

1. A member sends a message in a stream channel on one server.
2. The bot on that server makes sure the sender and message meet all necessary conditions (not globally blacklisted from bot usage and not a bot or bot command).
3. It converts the message to an embed, preserving the member's color and nickname and nullifying @mentions in the message, and saves the member's avatar.
4. It deletes the original message and replaces it with the embed for aesthetic consistency.
5. If the bot is in the destination server, it checks that the sender meets all necessary conditions (not banned, muted, or ignored) in that server, and uses a webhook to send the message with the avatar and nickname of the original sender. This webhook is created ahead of time and cached for speed. When the bot first starts, this cache will be empty, and delivery will be slightly slower.
6. Otherwise, it drops the message in the stream hub (not accessible to normal users) on its support server, where other instances of the bot pick it up and complete step 5 if they are in the destination server.

Delivery: Embassy Invites
1. A server administrator uses the >nexus invite command.
2. The bot makes sure the server meets all necessary conditions (it does not already have an outbound invitation pending, it is not sending an invitation to itself, it does not have too many channels for the bot to create another one, and it does not have an embassy with the other server already).
3. It converts the invitation to an embed, preserving the server's name and icon and the sender's name.
4. If the bot in that server is also in the destination server, it makes sure the destination server meets all necessary conditions (it does not have too many channels for the bot to create another one, and it has a moderation or administration channel where the invitation can be delivered).
5. It delivers the invitation there and waits up to six minutes for a reaction (✅ or ❌).
6. A staff member on the destination server reacts to the invite, or it times out.
7. The bot sends a receipt back to the first server informing them of the result.
8. If the invitation was accepted, the bot creates and activates an embassy channel in both servers, each named after the other.
9. If the bot in the first server is not in the destination server, it drops the invitation or receipt in the stream hub (not accessible to normal users) on its support server, where other instances of the bot pick it up and complete steps 4-8 if they are in the destination server.

Preventing Users from Sending/Viewing Messages
-It is the responsibility of server administrators to set the appropriate permissions in NSNexus channels on their server. The bot does not attempt to do this for them.
-Messages from users that are banned/muted/ignored in a particular server are suppressed in that server. These messages cannot be viewed (except in other servers), but in the interest of preserving some context and eliminating confusion, the bot informs the channel that a banned/muted/ignored user sent a message.
-The above also applies to messages sent by servers that are ignored in a particular server, though for obvious reasons one server cannot be banned or muted in another.
-Messages sent by users and servers that are globally blacklisted from bot usage are not delivered at all.
-Unfortunately, if User A has blocked User B, messages sent through NSNexus by User B will still be visible to User A. This is because a bot-controlled webhook is the actual sender of each message, even though the messages originate from human users.

Content Enforcement
-Messages may be deleted at the developer's discretion. This will generally apply to messages that contain graphic, explicit content (such as nudity and gore) and personally identifying information. This option will always be exercised against clearly objectionable content, not criticism and personal disagreements.
-NSNexus Global Moderators, stationed on the bot's support server, can use a command to delete all copies of a message from a global stream. This command cannot be used on messages sent through embassy streams.
-Messages sent through the global news stream that are not official, formal updates from a region, organization, or project may also be deleted without warning.
-It is the responsibility of server administrators to enforce their own server's rules and police their own NSNexus channels. Tools at their disposal include the >ignore, >mute, >ban, and >delete commands, all of which are explained in the bot's help menu under the Mod Suite submenu.

Return to top


All NSNexus commands begin with >nexus, and are usable by Moderators and above. As a reminder, the bot's permissions tier progression is Standard User -> Power User -> Moderator -> Administrator -> Server Owner -> Developer. Arguments should not include [brackets].

>nexus set_channel [stream] [channel]
Set the channel where a given stream runs.

The [stream] argument can be news, chat, or the ID of a server that has an NSN embassy with yours. The [channel] argument can be the #mention, name, or ID of a channel within the current server. For example, if you have a channel named #nsn_global_news in your server, type >nexus set_channel news #nsn_global_news to start the global news stream in that channel. The NSNexus logo will be posted in the channel and pinned, along with a short description of the stream.

>nexus list_streams
List the streams running in the server and the channels where they run.

This command provides embassy server IDs and instructions for using >nexus list_servers.

>nexus list_servers
List the servers connected to at least one global stream.

IDs, rather than names, are required for ignoring and inviting servers. This command provides a directory that matches the names of NSNexus-enabled servers to their IDs.

>nexus invite [server ID]
Invite another server to establish an embassy with yours.

The [server ID] argument can be the ID of any other server that has NSNexus enabled. The invitation appears in the other server and times out after six minutes. The maximum number of channels a server can have is 500, so if either server has that many, the bot will be unable to create another channel to hold the embassy. In that case, it will not deliver the invitation, and it will inform the sending server. It will also fail to deliver the invitation and inform the sending server if the destination server has no moderation or administration channel to receive the invitation.

Return to top


The Nexus is moderated. Any Nexus message is subject to deletion by moderators at any time without warning. Any user may be temporarily or permanently muted or banned by a moderator at any time without warning. Typically, message deletions and warnings will precede mutes and bans.

Global Chat
1. You may post invite links to NS-based servers. You must state the purpose of the server (eg, a specific region, trading cards, etc). Do not post any given link more than once a day. The Nexus moderation team does not accept responsibility for the content on servers advertised through the Nexus, but reserves the right to prohibit the advertisement of any server known to contain objectionable content.
2. Do not post sexual imagery or text.
3. Do not post personally identifying information belonging to another user without that user's consent.
4. Do not threaten or harass other users. If a user asks you to leave them alone, do so immediately.
5. Do not advertise for-profit organizations, companies, products, etc.
6. Do not recommend that users violate NS rules, or discuss ways to do so.
7. Do not post messages that are devoid of meaning, such as "foaisjdfoij" or a single letter or emoji with no context.
8. Respect the authority of the Nexus moderators. If you are asked to stop doing something, stop.

Global News
1. This stream is intended for formal updates only. Effort is a non-negotiable requirement. Messages containing excessive misspellings/typos, insufficient detail, outright recruitment ("join this region"), or responses ("Nice update") will be deleted.
2. This stream is out-of-character only, not in-character. For example, you may announce a roleplay event hosted by your region and invite players to join, but you may not announce an event taking place within your fictional nation that you are roleplaying.
3. Any NS-based organization, region, or project (such as AugustinAndroid itself) may post updates. Individuals not representing one of these three entities should not post.

Return to top

Created by August. Do not reproduce, in whole or in part, without explicit permission.

August

Edited:

RawReport