SidechatAPIClient

API client class for making requests to Sidechat's private API. You'll need to authenticate before using most of the methods.

Constructor

new SidechatAPIClient(tokenopt, rootUrl)

Create a new instance of the API client

Parameters:
NameTypeAttributesDescription
tokentypes.SidechatAuthToken<optional>

user bearer token

rootUrlString

custom API root URL for mocking or using other server

Since
  • 2.0.0-alpha.0

Members

apiRoot :String

Root URL for every API request

Type:
  • String
Default Value
  • "https://api.sidechat.lol"

(constant) defaultHeaders :Object

Default headers for every API request

Type:
  • Object

userToken :types.SidechatAuthToken

User bearer token

Type:
  • types.SidechatAuthToken

Methods

authorizeRealtimeChannel(socketID, channelName) → {Promise.<{auth: String}>}

Authorizes a realtime (Pusher) connection to subscribe to a private channel, such as private-chat-<chatID> for live direct messages. Pass the result to your Pusher client's channel authorizer. This hasn't been tested, and is mostly theoretical.

Parameters:
NameTypeDescription
socketIDString

socket ID assigned by Pusher

channelNameString

name of the private channel to subscribe to

Since
  • 2.7.0
Returns:

signed channel authorization

Type: 
Promise.<{auth: String}>

blockUser(postID, reportopt, postContextopt)

Blocks the author of a post or comment, hiding all of their content from the user. Replaces hidePostsFromUser.

Parameters:
NameTypeAttributesDescription
postIDString

alphanumeric ID of a post or comment by the user to block

reportBoolean<optional>

whether or not to also report the content

postContext"feed" | "chat"<optional>

where the content was seen

Since
  • 2.7.0

checkEmailVerification()

Check is the user's email is verified.

Since
  • 1.0.0

checkUsername(username) → {Promise.<Boolean>}

Checks if user can set their username to a string

Parameters:
NameTypeDescription
usernameString

string to check

Since
  • 2.3.6
Returns:

whether or not username is valid and unused

Type: 
Promise.<Boolean>

createComment(parentPostID, text, groupID, replyCommentIDopt, topLevelReplyIDopt, assetListopt, disableDMsopt, anonymousopt) → {Promise.<types.SidechatPostOrComment>}

Creates a comment on a post

Parameters:
NameTypeAttributesDescription
parentPostIDString

alphanumeric ID of post on which this comment is made

textString

text content of comment

groupIDString

alphanumeric ID of group in which the parent post resides

replyCommentIDString<optional>

alphanumeric ID of comment to reply to. Falls back to parentPostID

topLevelReplyIDString<optional>

alphanumeric ID of the top-level comment to reply to. Used only when replying to replies. Falls back to parentPostID

assetListArray.<types.SidechatSimpleAsset><optional>

list of assets to attach

disableDMsBoolean<optional>

prevent direct messages being sent to comment's author

anonymousBoolean<optional>

whether or not to hide user's name and icon on comment

Since
  • 2.2.0
Returns:

created comment

Type: 
Promise.<types.SidechatPostOrComment>

createLinkAttachment(url) → {Promise.<types.SidechatAttachment>}

Creates a link attachment that can be added to a post with createPost(). YouTube links are recognized and shown as embedded videos.

Parameters:
NameTypeDescription
urlString

URL to attach

Since
  • 2.7.0
Returns:

the created attachment

Type: 
Promise.<types.SidechatAttachment>

createPost(text, groupID, assetListopt, disableDMsopt, disableCommentsopt, anonymousopt, pollOptionsopt, attachmentIDsopt) → {Promise.<types.SidechatPostOrComment>}

Creates a new post in the specified group. Users can only make two posts a minute; if a post is rejected, the thrown error contains the reason from the server.

Parameters:
NameTypeAttributesDescription
textString

text content of comment

groupIDString

alphanumeric ID of group in which the parent post resides

assetListArray.<types.SidechatSimpleAsset><optional>

list of assets to attach.

disableDMsBoolean<optional>

prevent direct messages from being sent to post's author

disableCommentsBoolean<optional>

whether or not comments should be disabled on post

anonymousBoolean<optional>

whether or not to hide user's name and icon on post

pollOptionsArray.<String><optional>

List of poll options. If provided, a poll will be created with these options.

attachmentIDsArray.<String><optional>

IDs of link attachments created with createLinkAttachment()

Since
  • 2.2.0
Returns:

the created post

Type: 
Promise.<types.SidechatPostOrComment>

deleteAccount()

Permanently deletes the current user's account. This cannot be undone!

Since
  • 2.7.0

deletePostOrComment(postOrCommentID)

Deletes a post or comment that the user created

Parameters:
NameTypeDescription
postOrCommentIDString

alphanumeric ID of post to delete

Since
  • 2.2.0

flagPost(postID, reason, noteopt)

Reports a post or comment to the group's moderators

Parameters:
NameTypeAttributesDescription
postIDString

alphanumeric ID of post or comment to report

reasontypes.SidechatReportReason

why the content is being reported

noteString<optional>

explanation to send along with the report

Since
  • 2.7.0

getActivity(cursoropt) → {Promise.<types.SidechatActivityList>}

Gets the user's activity feed (notifications for comments, votes, followers, etc.)

Parameters:
NameTypeAttributesDescription
cursortypes.SidechatCursorString<optional>

cursor string

Since
  • 2.7.0
Returns:

activity items and cursor

Type: 
Promise.<types.SidechatActivityList>

getAssetLibrary() → {Promise.<Array.<types.SidechatLibraryAsset>>}

Retrieves the entire accessible asset library. Be warned that as of the time of this documentation, it's a 1.5MB JSON download and this request is very expensive.

Since
  • 2.0.6
Returns:
Type: 
Promise.<Array.<types.SidechatLibraryAsset>>

getAvailableGroups(onePage) → {Promise.<Array.<types.SidechatGroup>>}

Gets groups to be displayed on the "Explore Groups" page

Parameters:
NameTypeDescription
onePageBoolean

whether or not results should be returned as a single page

Since
  • 2.0.0-alpha.0
Returns:
Type: 
Promise.<Array.<types.SidechatGroup>>

getCurrentUser() → {Promise.<types.SidechatCurrentUser>}

Gets the current authenticated user and a list of the groups of which they are members.

Since
  • 2.1.0
Returns:
Type: 
Promise.<types.SidechatCurrentUser>

getDMForPost(postID) → {Promise.<types.SidechatDirectThread>}

Gets the existing direct message thread for a post or comment. Returns undefined if the user hasn't started one.

Parameters:
NameTypeDescription
postIDString

alphanumeric ID of post or comment

Since
  • 2.7.0
Returns:
Type: 
Promise.<types.SidechatDirectThread>

getDMThread(id) → {Promise.<types.SidechatDirectThread>}

Gets a single direct message thread

Parameters:
NameTypeDescription
idString

alphanumeric ID of the chat to fetch

Since
  • 2.4.4
Returns:
Type: 
Promise.<types.SidechatDirectThread>

getDMs(cursoropt) → {Promise.<Array.<types.SidechatDirectThread>>}

Gets a list of the user's direct messages

Parameters:
NameTypeAttributesDescription
cursortypes.SidechatCursorString<optional>

cursor string

Since
  • 2.4.4
Returns:
Type: 
Promise.<Array.<types.SidechatDirectThread>>

getGroupChats()

Retrieves joinable group chats

Since
  • 2.3.5

Gets a shareable invite link for a group. School groups don't have invite links and will throw an error.

Parameters:
NameTypeDescription
groupIDString

alphanumeric ID of group

Since
  • 2.7.0
Returns:

invite link URL

Type: 
Promise.<String>

getGroupMetadata(groupIDopt) → {Promise.<types.SidechatGroup>}

Gets the metadata of a group from its ID

Parameters:
NameTypeAttributesDescription
groupIDString<optional>

alphanumeric ID of a group to get. Falls back to user's primary group.

Since
  • 2.1.0
Returns:
Type: 
Promise.<types.SidechatGroup>

getGroupPosts(groupID, category, cursoropt, periodopt) → {Promise.<types.SidechatPostsAndCursor>}

Fetches posts from the specified category in a group

Parameters:
NameTypeAttributesDescription
groupIDString

group ID

category"hot" | "recent" | "top"

category to filter posts

cursortypes.SidechatCursorString<optional>

cursor string

period"day" | "week" | "month" | "year" | "all_time"<optional>

time period to pull top posts from (only if category is "top")

Since
  • 1.0.0
Returns:

List of posts and cursor

Type: 
Promise.<types.SidechatPostsAndCursor>

getGroups() → {Promise.<Array.<types.SidechatGroup>>}

Gets the groups the user is a member of

Since
  • 2.7.0
Returns:
Type: 
Promise.<Array.<types.SidechatGroup>>

getHomeFeed(typeopt, schoolGroupIDopt, cursoropt) → {Promise.<types.SidechatFeed>}

Fetches the home feed, which mixes posts from all of the user's groups

Parameters:
NameTypeAttributesDescription
type"for_you" | "hot" | "recent"<optional>

how the feed should be sorted

schoolGroupIDString<optional>

alphanumeric ID of the user's school group

cursortypes.SidechatCursorString<optional>

cursor string

Since
  • 2.7.0
Returns:

feed items and cursor

Type: 
Promise.<types.SidechatFeed>

getLeaderboard(groupID) → {Promise.<types.SidechatLeaderboard>}

Gets the yakarma leaderboard for a group, along with the user's own karma

Parameters:
NameTypeDescription
groupIDString

alphanumeric ID of group

Since
  • 2.7.0
Returns:
Type: 
Promise.<types.SidechatLeaderboard>

getPost(postID, includeDeleted) → {Promise.<types.SidechatPostOrComment>}

Fetches a single post with just its ID

Parameters:
NameTypeDescription
postIDString

ID of post to fetch

includeDeletedBoolean

undocumented

Since
  • 2.3.0
Returns:

post object

Type: 
Promise.<types.SidechatPostOrComment>

getPostComments(postID) → {Promise.<Array.<types.SidechatPostOrComment>>}

Get all the commments on a post

Parameters:
NameTypeDescription
postIDString

post ID to get comments for

Since
  • 2.0.0-alpha.0
Returns:

list of comments

Type: 
Promise.<Array.<types.SidechatPostOrComment>>

getSuggestedGroups(limitopt) → {Promise.<Array.<types.SidechatGroup>>}

Gets groups suggested for the user to join

Parameters:
NameTypeAttributesDescription
limitNumber<optional>

maximum number of groups to return

Since
  • 2.7.0
Returns:
Type: 
Promise.<Array.<types.SidechatGroup>>

getUpdates(groupIDopt)

Get updated status for user and group

Parameters:
NameTypeAttributesDescription
groupIDString<optional>

ID of a specific group to retrieve info from. Falls back to user's primary group.

Since
  • 2.1.0

getUserAndGroup(groupIDopt)

Get updated status for user and group

Parameters:
NameTypeAttributesDescription
groupIDString<optional>

ID of a specific group to retrieve info from. Falls back to user's primary group.

Since
  • 1.0.0
Deprecated
  • since 2.1.0, will be removed by 3.0.0. Please use `getUpdates` instead!

getUserContent(contentType) → {Promise.<Array.<types.SidechatPostOrComment>>}

Fetches the posts or comments that the user has created

Parameters:
NameTypeDescription
contentType"posts" | "comments"

type of user content to fetch

Since
  • 2.3.5
Returns:

post object

Type: 
Promise.<Array.<types.SidechatPostOrComment>>

getUserPosts(username) → {Promise.<Array.<types.SidechatPostOrComment>>}

Fetches a public user's posts

Parameters:
NameTypeDescription
usernameString

username of the user to fetch

Since
  • 2.6.0
Returns:
Type: 
Promise.<Array.<types.SidechatPostOrComment>>

getUserProfile(username) → {Promise.<types.SidechatProfile>}

Fetches a public user profile

Parameters:
NameTypeDescription
usernameString

username of the user to fetch

Since
  • 2.6.0
Returns:
Type: 
Promise.<types.SidechatProfile>

hidePostsFromUser(postID)

Hides posts from user

Parameters:
NameTypeDescription
postIDString

alphanumeric ID of post to hide

Since
  • 2.6.2
Deprecated
  • since 2.7.0. Please use `blockUser` instead!

joinGroupChat(groupChatID, displayName, emoji, primaryColor, secondaryColor)

Joins a group chat. To mimic the official client, use the user's display name and icon by default.

Parameters:
NameTypeDescription
groupChatIDString

alphanumeric ID of group chat to join

displayNameString

display name to use in chat

emojiString

emoji to use as icon

primaryColorString

hex string of primary color

secondaryColorString

hex string of secondary color

Since
  • 2.3.5

loginViaSMS(phoneNumber, useFallbackopt, captchaMethodopt, captchaResponseopt)

Initiate the login process with a phone number. Should be followed up with verifySMSCode(). If the response has an error_code of "captcha_required", the server wants a captcha solved before it will send a code, and the request should be repeated with a captcha response. I haven't been able to recreate this yet, so I honestly don't know what captcha provider they want.

Parameters:
NameTypeAttributesDescription
phoneNumberNumber

US phone number (WITHOUT +1) to send verification code to

useFallbackBoolean<optional>

send the code through the backup SMS route, which the official app offers when a code doesn't arrive

captchaMethodString<optional>

type of captcha being answered

captchaResponseString<optional>

solved captcha token

Since
  • 1.0.0

readActivity(activityID)

Marks an activity item as read

Parameters:
NameTypeDescription
activityIDString

alphanumeric ID of activity object

Since
  • 2.3.2

registerEmail(email)

Initiate the email setup process. Should be followed up with checkEmailVerification().

Parameters:
NameTypeDescription
emailString

school email address to send verification code to

Since
  • 1.0.0

reportDM(chatID, reason)

Reports a direct message thread

Parameters:
NameTypeDescription
chatIDString

alphanumeric ID of the thread to report

reasontypes.SidechatReportReason

why the thread is being reported

Since
  • 2.7.0

searchAvailableGroups(query) → {Promise.<Array.<types.SidechatGroup>>}

Searches for new groups based on a query keyword

Parameters:
NameTypeDescription
queryString

the string to search for. This will be encoded, so strings with spaces and special characters are okay.

Since
  • 2.6.0
Returns:
Type: 
Promise.<Array.<types.SidechatGroup>>

sendDM(chatID, text, clientID, assets, anonymous)

Sends a message to an existing direct message thread - note that you must first use startDM() to start a thread.

Parameters:
NameTypeDescription
chatIDString

alphanumeric ID of the chat to send to

textString

text content of message

clientIDString

alphanumeric device ID

assetsArray.<types.SidechatAsset>

array of assets to send

anonymousBoolean

whether the DM should be sent anonymously

Since
  • 2.4.4

sendRequest(endpoint, methodopt, bodyopt, headersopt, stripHeadersopt)

Run an arbitrary API request using the current client's authentication

Parameters:
NameTypeAttributesDescription
endpointString

API endpoint to request (e.g. "/v1/posts")

method"GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS"<optional>

HTTP method to use

bodyObject<optional>

body to send with the request

headersObject<optional>

custom headers to send with the request

stripHeadersBoolean<optional>

remove the default headers from the request

Since
  • 2.4.9

setAPIRoot(url)

Manually set the root URL for all API requests. This can be used for mocking requests or redirecting them to a different server

Parameters:
NameTypeDescription
urlString

new root URL to set

Since
  • 2.3.9

setAge(age, registrationID, timeZoneopt, inviteLinkURLopt)

Set the user's age. If this function succeeds, the user will be authenticated for future requests.

Parameters:
NameTypeAttributesDescription
ageNumber

user's age in years

registrationIDString

the registration ID generated by verifySMSCode()

timeZoneString<optional>

time zone of the user (e.g. "America/Chicago"). Falls back to the system time zone.

inviteLinkURLString<optional>

group invite link that the user signed up through

Since
  • 1.0.0

setDeviceID(deviceId, bundleIDopt)

Set the device ID of the current user

Parameters:
NameTypeAttributesDescription
deviceIdString

the device ID to set

bundleID"com.flowerave.sidechat" | "com.flowerave.yikyak"<optional>

bundle ID of the app the push token belongs to

Since
  • 1.0.0

setDeviceIdentifier(deviceIdentifier)

Set an identifier for this device, which will be sent with every request in the X-Device-ID header. Should be stable across sessions on the same device.

Parameters:
NameTypeDescription
deviceIdentifierString

stable identifier for this device

Since
  • 2.7.0

setGroupMembership(groupID, isMember)

Joins or leaves a group

Parameters:
NameTypeDescription
groupIDString

alphanumeric ID of group to join or leave

isMemberBoolean

whether or not the user should be a member of the group

Since
  • 2.3.8

setNotificationPreferences(preferences)

Sets which push notifications the user receives

Parameters:
NameTypeDescription
preferencestypes.SidechatNotificationPreferences

notification types to enable or disable

Since
  • 2.7.0

setPostFollowing(postID, following) → {Promise.<{post: types.SidechatPostOrComment}>}

Follows or unfollows a post. Followed posts send activity notifications when they get new comments.

Parameters:
NameTypeDescription
postIDString

alphanumeric ID of post

followingBoolean

whether or not the user should follow the post

Since
  • 2.7.0
Returns:

the updated post

Type: 
Promise.<{post: types.SidechatPostOrComment}>

setToken(token)

Manually set the currently signed in user's token. Generally try to avoid this and instead either pass a token to the constructor or login automatically through the auth functions

Parameters:
NameTypeDescription
tokentypes.SidechatAuthToken

user bearer token

setUserBio(userID, bio)

Sets the bio text of a user

Parameters:
NameTypeDescription
userIDString

alphanumeric ID of user

bioString

text to set as bio

Since
  • 2.5.6

setUserIcon(userID, emoji, primaryColor, secondaryColor)

Sets the conversation icon of a user

Parameters:
NameTypeDescription
userIDString

alphanumeric ID of user

emojiString

emoji to set as icon

primaryColorString

hex string (including #) of primary color

secondaryColorString

hex string (including #) of secondary color

Since
  • 2.2.1

setUsername(userID, username)

Changes the username of the current user

Parameters:
NameTypeDescription
userIDString

alphanumeric ID of user

usernameString

new username to set

Since
  • 2.3.6

setVote(postID, action)

Upvote or downvote, or unvote a post

Parameters:
NameTypeDescription
postIDString

post ID to vote on

actiontypes.SidechatVoteString

whether to upvote, downvote, or reset vote

Since
  • 2.0.0-alpha.0

startDM(text, clientID, postID, anonymous, postContext)

Creates a new direct message thread

Parameters:
NameTypeDescription
textString

text content of message

clientIDString

alphanumeric ID of devide

postIDString

alphanumeric ID of post or comment

anonymousBoolean

whether the DM should be sent anonymously

postContext"feed"

context of post (mostly undocumented, defaults to "feed")

Since
  • 2.4.4

unhidePostsFromAllUsers()

Unhides all posts from all users

Since
  • 2.6.2
Deprecated
  • since 2.7.0. No longer used by the official app and may stop working.

uploadAsset(uri, mimeType, nameopt, contextopt) → {Promise.<String>}

Uploads an asset to AWS S3 for use in posts and comments. Supports images and videos (videos must be under 50MB and are processed after upload)

Parameters:
NameTypeAttributesDescription
uriString

URI of the asset to upload

mimeTypeString

mimetype of the asset (e.g. "image/png" or "video/mp4")

nameString<optional>

filename of the asset

context"post" | "post_vod_source" | "chat" | "chat_icon" | "group_icon" | "profile_picture_icon"<optional>

where the asset will be used. Videos default to "post_vod_source", which is required for them to be processed into a playable stream.

Since
  • 2.5.1
Returns:

URL of the uploaded asset

Type: 
Promise.<String>

verifyEmailWithThirdParty(authToken, authType, isIncomingFreshmanopt)

Verifies the user's school email by signing in with Google or Microsoft instead of clicking an emailed link. Returns the same object as checkEmailVerification(). This was discovered from me decompiling the new Android app, I haven't tested this but based on the implementation it should work fine and might resolve the problem that a lot of people have with their accounts not being associated with their school automatically.

Parameters:
NameTypeAttributesDescription
authTokenString

token from the Google or Microsoft sign-in

authType"google" | "microsoft"

provider the token came from

isIncomingFreshmanBoolean<optional>

whether or not the user is an incoming freshman

Since
  • 2.7.0

verifySMSCode(phoneNumber, code)

Verify the code sent via SMS with loginViaSMS(). If this function succeeds, the user will be authenticated for future requests.

Parameters:
NameTypeDescription
phoneNumberNumber

US phone number (WITHOUT +1) that verification code was sent to

codeString

the verification code

Since
  • 1.0.0

viewPollResults(pollId)

Marks that the user has viewed results on a poll. Note that this does not actually return the results of the poll.

Parameters:
NameTypeDescription
pollIdString

alphanumeric ID of poll to vote on

Since
  • 2.5.4

voteOnPoll(pollId, choiceIndex)

Votes on a poll attached to a post

Parameters:
NameTypeDescription
pollIdString

alphanumeric ID of poll to vote on

choiceIndexNumber

index of the choice to vote on

Since
  • 2.5.4