strangers-js

Creates a bot instance. Nothing is sent over the network until you call login, loginWithCookie, or signup.

Logs in with a username and password. Starts the heartbeat automatically. Returns the logged in user, also stored as bot.user.

const user = await bot.login('bot_testing', '12345678');
console.log('logged in as', user.username);

Logs in using a saved session token instead of a password. Starts the heartbeat automatically.

await bot.loginWithCookie('the-saved-token');

Creates a brand new account and logs in as it. Starts the heartbeat automatically.

await bot.signup({
  username: 'my_new_bot',
  password: 'a-strong-password',
  inviteKey: 'AB12-CD34-EF56' // only needed if invites are required
});

Logs out and stops the heartbeat.

await bot.logout();

Gets the current session token, so you can save it and skip the password next time with loginWithCookie.

const token = bot.getSessionCookie();

Manually stop or start the automatic heartbeat without logging out.

Stops all timers. Call this if the process is not exiting cleanly on its own.

Same as bot.signup, but does not update bot.user or start the heartbeat.

Same as bot.login, but does not update bot.user or start the heartbeat.

Logs out on the server. Does not clear the local session or stop the heartbeat, use bot.logout for that.

Gets the currently logged in account fresh from the server.

const me = await bot.auth.me();

Updates account settings, like bio or display name.

await bot.auth.updateMe({
  bio: 'a friendly bot',
  displayName: 'Bot Testing'
});

Permanently deletes the logged in account. There is no undo.

Gets a user's public profile.

const { user } = await bot.users.profile('someusername');

A user's own posts, newest first. Pass the createdAt of the oldest post you already have as before, to load older ones.

A user's replies to other posts.

Posts a user has relayed.

Who follows this user.

Who this user follows.

Follows a user. If their account is private, this creates a pending follow request instead.

await bot.users.follow('someusername');

Unfollows a user.

Blocks a user. Cuts off following, messaging, and visibility in both directions.

Unblocks a user.

Everyone the logged in account has blocked.

Reports a user for moderation. Returns { ok: true }.

Pending follow requests this account has received, only relevant for private accounts.

Accepts a pending follow request.

Rejects a pending follow request.

The main feed. Pass before to page further back.

const { posts } = await bot.posts.feed();

Creates a post.

await bot.posts.create({ text: 'hello world' });

// a reply
await bot.posts.create({ text: 'nice post', replyToId: postId });

// a poll
await bot.posts.create({
  text: 'cats or dogs?',
  poll: {
    durationHours: 24,
    options: [{ text: 'cats' }, { text: 'dogs' }]
  }
});

Gets one post and its reply thread.

Deletes a post the bot authored.

Pins a post to the top of the bot's profile.

Unpins a post.

Likes a post.

Removes a like.

Relays a post. Pass quoteText to make it a quote relay instead of a plain one.

await bot.posts.relay(postId);
await bot.posts.relay(postId, 'this is great');

Removes a relay.

Marks a post as viewed, for its view count.

Votes on a poll. optionId comes from the post's poll.options list.

Reports a post for moderation. Returns { ok: true }.

The bot's own bookmarks, newest saved first.

Returns { posts, hasMore }. Each post has the same shape a regular post has everywhere else in this API, plus two bookmark-specific fields always set on every item here:

{
  "posts": [
    {
      // same fields as a regular post duh
      "bookmarked": true,
      "bookmarkedAt": "2026-09-07T14:32:10.000Z"
    }
  ],
  "hasMore": false
}

Bookmarks a post. Returns { bookmarked: true }. Safe to call twice on the same post: a repeat call is a no-op, not an error.

Removes a bookmark. Returns { bookmarked: false }.

The bot's notifications, newest first, plus an unread count.

Marks every notification as read.

Polls in the background and calls onNotification once for each new notification. Keeps the process running until you call the returned stop function.

const { NotificationType } = require('./strangers-js');

const stop = bot.notifications.watch((notif) => {
  console.log(notif.actor.username, 'followed you');
}, { types: [NotificationType.Follow] });

The notif object passed to onNotification, same shape returned by list()'s notifications array, and by each event on the SSE stream the frontend uses:

// example notif for a like
{
  "id": "a1b2c3d4-...",
  "type": "like",
  "createdAt": "2026-09-07T14:32:10.000Z",
  "read": false,
  "actor": {
    "username": "someusername",
    "displayName": "Some User",
    "avatarUrl": "https://files.shibbystudios.xyz/..."
  },
  "postId": "e5f6...",
  "postPreview": "the first 80 characters of the liked post"
}

postId/postPreview are only populated for post-related types: like, relay, reply, mention_post. For follow, mention_bio, and any message-related notification, both are null.

How many accounts are online right now, site wide. Returns { online }, a plain count, deduped so one account open in several tabs still only counts once.

Searches users, hashtags, and posts. Prefix q with @ for users only, or # for a hashtag only.

const results = await bot.search.search('cats');
const onlyUsers = await bot.search.search('@someusername');

Always returns { users, hashtags, posts }. Whichever of the three don't apply to your query (e.g. posts for an @-prefixed search) just come back as empty arrays, rather than being left out. With quick: true, posts is always [], since quick search never runs the post query at all; that's what makes it fast.

{
  "users": [
    {
      "id": "7c1a...",
      "username": "someusername",
      "displayName": "Some User",
      "bio": "...",
      "avatarUrl": "https://files.shibbystudios.xyz/...",
      "bannerUrl": null,
      "isPrivate": false,
      "isVerified": false,
      "isPremium": false,
      "isAdultOnly": false
    }
  ],
  "hashtags": ["catsofstrangers", "catpics"],
  "posts": []
}

Currently trending hashtags. Returns { hashtags }, where each entry is { tag, postCount }. Unlike search results, these come back as objects (with a count), not plain strings.

{
  "hashtags": [
    { "tag": "catsofstrangers", "postCount": 142 },
    { "tag": "mcm", "postCount": 98 }
  ]
}

Posts carrying a given hashtag, without the leading #. Returns { posts }.

Uploads an image and returns its hosted url, ready to use as a post's imageUrl.

const fs = require('fs');
const buffer = fs.readFileSync('./photo.png');
const { url } = await bot.media.upload(buffer, 'image/png');

await bot.posts.create({ text: 'check this out', imageUrl: url });

Returns just { url }, nothing else. That url is what you hand back in as imageUrl for a post, poll option, blog cover, or profile avatar/banner; the server rejects any image field that isn't a URL it issued itself.

Looks up title, author, and thumbnail for a YouTube video id.

{
  "title": "Some Video Title",
  "author": "Some Channel",
  "thumbnailUrl": "https://i.ytimg.com/vi/.../hqdefault.jpg"
}

Every conversation the bot is part of, including its own pending sent requests. Returns { conversations }, each shaped:

{
  "conversations": [
    {
      "id": "9f2e...",
      "status": "accepted",
      "otherUser": {
        "id": "7c1a...",
        "username": "someusername",
        "displayName": "Some User",
        "bio": "...",
        "avatarUrl": "https://files.shibbystudios.xyz/...",
        "bannerUrl": null,
        "isPrivate": false,
        "isVerified": false,
        "isPremium": false,
        "isAdultOnly": false
      },
      "lastMessage": { "text": "hey there", "senderId": "7c1a..." },
      "lastMessageAt": "2026-09-07T14:32:10.000Z",
      "unreadCount": 1,
      "isRequester": false
    }
  ]
}

Message requests other people sent to the bot, waiting to be accepted. Returns { requests }, same shape as a conversation above, minus isRequester (every row here was, by definition, sent by someone else).

A single conversation's full message history. Returns { conversation, messages }:

{
  "conversation": {
    "id": "9f2e...",
    "status": "accepted",
    "isRequester": false,
    "otherUser": { // same shape as conversations() above }
  },
  "messages": [
    {
      "id": "a4b2...",
      "text": "hey there",
      "senderId": "7c1a...",
      "createdAt": "2026-09-07T14:32:10.000Z",
      "read": true
    }
  ]
}

Sends a message to a user by username. Creates a new conversation if one does not exist yet. If the recipient is the one replying to the bot's still-pending request, that reply auto-accepts it.

await bot.messages.send('someusername', 'hey there');

Returns { conversation: { id, status }, message: { id, text, senderId, createdAt, read } }. message.read is always false here, since it was just sent.

{
  "conversation": { "id": "9f2e...", "status": "pending" },
  "message": {
    "id": "a4b2...",
    "text": "hey there",
    "senderId": "7c1a...",
    "createdAt": "2026-09-07T14:32:10.000Z",
    "read": false
  }
}

Accepts a pending message request. Returns { ok: true }.

Deletes or denies a conversation. Returns { ok: true }.

Polls one conversation in the background and calls onMessage for each new message.

const stop = bot.messages.watch(conversationId, (message) => {
  console.log(message.text);
});

Published blog posts, newest first. Returns { posts, hasMore }, each post shaped:

{
  "posts": [
    {
      "id": "3d9c...",
      "title": "What's new this month",
      "body": "## Heading\n\nSome **markdown** text.",
      "imageUrl": null,
      "createdAt": "2026-09-01T12:00:00.000Z",
      "updatedAt": "2026-09-01T12:00:00.000Z",
      "author": { "username": "admin", "displayName": "Strangers Team", "avatarUrl": "https://files.shibbystudios.xyz/..." }
    }
  ],
  "hasMore": false
}

A single blog post. Returns { post }, same shape as one entry from list() above.

sort can be "popular" or "recent". Returns { items, hasMore }. hasMore is only ever true for "recent"; "popular" always returns its full ranked window in one response, there's no next page. Each item:

{
  "items": [
    {
      "id": "e1f0...",
      "title": "Dark mode retro",
      "description": "",
      "imageUrl": "https://files.shibbystudios.xyz/...",
      "likes": 12,
      "liked": false,
      "createdAt": "2026-08-30T09:00:00.000Z",
      "author": { "username": "someusername", "displayName": "Some User", "avatarUrl": "...", "isVerified": false },
      "isOwn": false
    }
  ],
  "hasMore": true
}

A single template, including the full CSS. Returns { item }, same shape as list() above, but with a css field included this time (the actual CSS text).

{
  "item": {
    // same fields as list()
    "css": "body { background: #14181a; }"
  }
}

Shares a template. data can include title, description, css, and imageUrl. Returns { item }, same full shape as get() above (css included).

Removes a template the bot submitted. Returns { ok: true }.

Likes a template. Returns { liked: true }.

Removes a like. Returns { liked: false }.

Searches for GIFs. Returns { gifs, ads, page, hasMore }:

{
  "gifs": [
    {
      "id": "482910",
      "title": "",
      "url": "https://static.klipy.com/.../full.gif",
      "width": 480,
      "height": 270,
      "previewUrl": "https://static.klipy.com/.../preview.gif"
    }
  ],
  "ads": [
    { "id": "ad-4", "isAd": true, "htmlContent": "<html>...</html>", "width": 320, "height": 50 }
  ],
  "page": 1,
  "hasMore": true
}

Currently trending GIFs. Returns the same { gifs, ads, page, hasMore } shape as search() above.

Public instance config, including whether invite keys are required to sign up. Returns { inviteKeysEnabled, featureFlags }. featureFlags is the same object featureFlags() below returns, folded in here so a caller that fetches this once at startup doesn't need a second request.

{
  "inviteKeysEnabled": true,
  "featureFlags": {
    "messages": true,
    "blog": true,
    "bookmarks": true,
    "css_library": true,
    "gifs": true,
    "polls": true,
    "premium": true,
    "presence": true,
    "search": true
  }
}

Which optional features are currently turned on. Returns { featureFlags }, a plain { [key]: boolean } map. Keys currently include messages, blog, bookmarks, css_library, gifs, polls, premium, presence, search. A key that's missing entirely (rather than false) hasn't happened yet in practice, but should be treated as enabled if it ever does.

{ "featureFlags": { "messages": true, "gifs": false, /* ... */ } }

The oldest unacknowledged warning, or null if there is none. Returns { warning }, where warning is { id, reason, createdAt } or null. If the account has more than one outstanding warning, this always returns the oldest first; you have to acknowledge it before the next one shows up here.

{ "warning": { "id": "c8e1...", "reason": "Spam", "createdAt": "2026-09-05T10:00:00.000Z" } }

Acknowledges a warning so it stops being returned by current(). Returns { ok: true }.

Claims Premium from a Ko-fi purchase that was not auto matched. data can include transactionId and or email; transactionId is tried first if given, otherwise the most recent unclaimed order for that email. Returns { ok: true } on success. An order that's already been claimed by any account (including this one) is rejected rather than silently re-granting.