Session
The Session
object is a short-lived object that actively communicates with the fediverse. It can be created by yourself, or you can get it when an event handler is called.
Creating a session
You can create a session by calling the Bot.getSession()
method:
const session = bot.getSession("https://mydomain");
It takes a single argument, the origin of the server to which your bot belongs. In practice, you would have an environment variable that contains the hostname of your server, and you would pass it to the getSession()
method:
const SERVER_NAME = Deno.env.get("SERVER_NAME");
if (SERVER_NAME == null) {
console.error("The SERVER_NAME environment variable is not set.");
Deno.exit(1);
}
const session = bot.getSession(`https://${SERVER_NAME}`);
Getting a session from an event handler
When an event handler is called, you can get a session from the Session
object that is passed as the first argument:
bot.onMention = async (session, message) => {
// `session` is a `Session` object
};
To learn more about event handlers, see the Events section.
Determining the actor URI of the bot
The Session
object has an actorId
property that contains the URI of the bot actor. You can use this URI to refer to the bot in messages:
bot.onFollow = async (session, actor) => {
await session.publish(
text`Hi, ${actor}! I'm ${session.actorId}. Thanks for following me!`
);
};
Determining the fediverse handle of the bot
The Session
object has an actorHandle
property that contains the fediverse handle of the bot. It looks like an email address except that it starts with an @
symbol: @myBot@myDomain
. You can use this handle to refer to the bot in messages:
bot.onFollow = async (session, actor) => {
await session.publish(
markdown(`I'm ${session.actorHandle}. Thanks for following me!`)
);
};
Getting the bot's Actor
object
The Session
object has a getActor()
method that returns the Actor
object of the bot:
const actor: Actor = session.getActor();
Publishing a message
See the Publishing a message section in the Message concept document.
Getting published messages
See the Getting published messages section in the Message concept document.
Following an actor
Your bot can follow an actor by calling the Session.follow()
method. The following example shows how to get the bot
follow back all of its followers:
bot.onFollow = async (session, actor) => {
await session.follow(actor);
};
CAUTION
The follow()
method just sends a follow request to the actor, but it does not guarantee that the actor will accept the follow request. The actor may reject the follow request, and your bot will not be able to follow the actor.
If you want to know whether the actor has accepted or rejected the follow request, you need to register the Bot.onAcceptFollow
and Bot.onRejectFollow
event handlers.
TIP
It takes several kinds of objects as an argument, such as Actor
, string
, and URL
:
Actor
- The actor to follow.
URL
- The URI of the actor to follow. E.g.,
new URL("https://example.com/users/alice")
. string
- The URI or the fediverse handle of the actor to follow. E.g.,
"https://example.com/users/alice"
or"@alice@example.com"
.
NOTE
If you try to follow an actor that is already followed, the method will just do nothing.
Unfollowing an actor
Likewise, your bot can unfollow an actor by calling the Session.unfollow()
method. The following example shows how to make the bot
unfollow if any of its followers unfollow it:
bot.onUnfollow = async (session, actor) => {
await session.unfollow(actor);
};
TIP
Like the follow()
method, the unfollow()
method takes several kinds of objects as an argument, such as Actor
, string
, and URL
.
NOTE
If you try to unfollow an actor that is not followed, the method will just do nothing.
Checking if the bot follows an actor
The Session
object has a follows()
method that returns a boolean value indicating whether your bot follows a given actor. The following example shows how to check if your bot follows an actor and respond accordingly:
bot.onMention = async (session, message) => {
const follows = await session.follows(message.author);
await session.publish(
follows
? text`Hi ${message.author}, I'm already following you!`
: text`Hi ${message.author}, I don't follow you yet.`
);
};
TIP
Like other methods, follows()
accepts several types of arguments such as Actor
, string
, and URL
.
NOTE
This method returns false
if the given actor doesn't exist or is inaccessible.