Updating Friends API & Deprecating IsOnline property from GetFriendsAsync

[Update] September 30, 2024


Hi Creators,

Great news! Over the coming months, we’ll be raising the friends limit, gradually increasing it to 1,000. Increasing the friend limit is one of the most popular requests among our user and creator communities. We know that this change is important because friends who can easily play and stay together in experiences leads to stronger engagement.

To make this improvement, we are making some Engine API and Friends API changes next month to support the new friends limit. These changes will start to roll out on October 21st.

Those changes include:
Engine API

  • Deprecating IsOnline property from GetFriendsAsync
  • Alternative Methods
  • Reason for Deprecation

Friends API

  • FindFriends Endpoint
  • Updates to Endpoints
  • Alternative Methods

Let’s dive into the details.

Engine API

Click here to view changes to the Engine API:

Deprecating IsOnline property from GetFriendsAsync

Starting October 21, when you use the GetFriendsAsync function from the Players Service, the IsOnline property in the FriendPages object will be deprecated. However, the ID, Username, and DisplayName properties will continue to work as usual, and there are no plans to change them. To prevent existing games from breaking, IsOnline will still exist but always return False even if the friend is not actually offline.

Current

{
	Id: number,
	Username: string,
	DisplayName: string,
	IsOnline: boolean,
}

New

{
	Id: number,
	Username: string,
	DisplayName: string,
}

Alternative Method

To check which friends are online, it’s better to use the GetFriendsOnline method from the Player object. This method only shows online friends and also provides more useful information that GetFriendsAsync does not include like LastLocation, PlaceId, and more.

Reason for Deprecation

This change is being made as we move towards increasing the friend limit and because checking all friends’ online statuses is not supported on the new friends endpoint. This is why we recommend utilizing the alternative methods mentioned above for those cases.


Friends API

Click here to view changes to the Friends API:

FindFriends Endpoint

We introduced the FindFriends Endpoint one year ago and want to highlight some of its capabilities. We recommend fetching all of your friends using the paginated FindFriends (/users/{userId}/friends/find) endpoint in the Friends API. This endpoint supports the FriendScore userSort, an upgraded score that incorporates more signals to determine friend closeness.

curl --request GET \
--url 'https://friends.roblox.com/v1/users/{userId}/friends/find?userSort=FriendScore' \

{
	"PreviousCursor": null,
	"PageItems": [
		{
			"id": 00000000,
			"hasVerifiedBadge": false
		},
             ...
		{
			"id": 00000001,
			"hasVerifiedBadge": false
		}
	],
	"NextCursor": "xxxxxxxxxxx",
	"HasMore": null
}

--url 'https://friends.roblox.com/v1/users/{userId}/friends/find?userSort=FriendScore&cursor=xxxxxxxxxxx' \

{
	"PreviousCursor": "yyyyyyyyyyy",
	"PageItems": [
		{
			"id": 00000003,
			"hasVerifiedBadge": false
		},
             ...
		{
			"id": 00000004,
			"hasVerifiedBadge": false
		}
	],
	"NextCursor": "zzzzzzzzzzzz",
	"HasMore": null
}

The non paginated GetAllFriends (/users/{userId}/friends) endpoint currently returns at most 200 friends, and this non paginated endpoint will continue to be capped at 200 friends when we increase the friends limit.

Updates to Endpoints

In order to keep the Friends API lean and efficient in support of the new friends limit, we will also remove names, frequent scores, and presence information from the responses of Friends API. Specifically, we will update these endpoints -

/v1/users/{userId}/friends

  • Remove user related fields such as name, displayName, externalDisplayName, created, description, hasVerifiedBadge, and isBanned
  • Remove isOnline and presenceType fields
  • We will also deprecate the userSort parameter and default to sorting by FriendScore when you are fetching your own friends, and sort by friendship CreatedDate otherwise
Click here to view what the new API response will look like:
{
  "data": [
    {
      "isDeleted": true,
      "id": 0,
    },
    {
      "isDeleted": false,
      "id": 1,
    }
  ]
}

/v1/users/{userId}/friends/find

  • Remove hasVerifiedBadge field
  • Remove HasMore field, since NextCursor can tell you whether there are more records to retrieve
Click here to view what the new API response will look like:
{
  "PreviousCursor": "prevCursorString",
  "PageItems": [
    {
      "id": 0
    },
    {
      "id": 1
    },
    {
      "id": 2
    }
  ],
  "NextCursor": "nextCursorString",
}

/v1/users/{userId}/friends/online

  • Remove name and displayName fields
  • We will also remove the userSort parameter and default to sorting by FriendScore
Click here to view what the new API response will look like:
{
  "data": [
    {
      "userPresence": {
        "UserPresenceType": "string",
        "UserLocationType": "string",
        "lastLocation": "string",
        "placeId": 0,
        "rootPlaceId": 0,
        "gameInstanceId": "sample-game-instance-id",
        "universeId": 0,
        "lastOnline": "2024-09-01T16:27:57.563Z"
      },
      "id": 0,
    }
  ]
}

/v1/users/{targetUserId}/followers and /v1/users/{targetUserId}/followings

  • Remove user related fields such as name, displayName, externalDisplayName, created, description, hasVerifiedBadge, and isBanned
  • Remove friendFrequentScore and friendFrequentRank
Click here to view what the new API response will look like:
{
  "previousPageCursor": "string",
  "nextPageCursor": "string",
  "data": [
    {
      "isOnline": true,
      "presenceType": 0,
      "isDeleted": true,
      "id": 0,
    }
  ]
}

/v1/my/friends/requests

  • Remove user related fields such as name, displayName, externalDisplayName, created, description, hasVerifiedBadge, and isBanned
Click here to view what the new API response will look like:
{
  "previousPageCursor": "string",
  "nextPageCursor": "string",
  "data": [
    {
      "friendRequest": {
        "sentAt": "2024-09-01T16:32:24.012Z",
        "senderId": 0,
        "sourceUniverseId": 0,
        "originSourceType": 0,
        "contactName": "string",
        "senderNickname": "string"
      },
      "mutualFriendsList": [
        "string"
      ],
      "id": 0,
    }
  ]
}

/v1/users/{userId}/friends/inactive

  • Remove user related fields such as name, displayName, externalDisplayName, created, description, hasVerifiedBadge, and isBanned
  • Remove isOnline and presenceType
  • Remove friendFrequentScore and friendFrequentRank

Here’s what the new API response will look like below:

Click here to view what the new API response will look like:
{
  "data": [
    {
      "isDeleted": true,
      "id": 0,
    },
    {
      "isDeleted": false,
      "id": 1,
    }
  ]
}

Alternative Methods

If you still need a user’s name and verified badge status, you can fetch these fields from the User Profile API. We highly recommend using the names.combinedName request field to fetch names and allow the API to return the most appropriate name for display.

CombinedName will return either the user alias, contact name or display name based on availability. Please only request the fields you need.

Click here to view a Sample Call & a Sample Response:

Sample call:

curl -X 'POST' \
    'https://apis.roblox.com/user-profile-api/v1/user/profiles/get-profiles' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{ "fields": [ "names.combinedName", "isVerified" ],
          "userIds": [ UserId1, UserId2, UserId3 ] }'

Sample response:

{
    "profileDetails": [
        { 
            "userId": UserId1,
            "names": {
                "combinedName": "DisplayName1",
            },
            "isVerified": true
        },
        {
            "userId": UserId2,
            "names": {
                "combinedName": "AliasName2"
            },
            "isVerified": false
        },
        {
            "userId": UserId3,
            "names": {
                "combinedName": "ContactName3"
            },
            "isVerified": false
        }
    ] ,
    "errors": [ ]
}

If you need to fetch presence related fields such as UserPresenceType, UserLocationType, lastLocation, lastOnline, placeId, rootPlaceId, universeId or gameInstanceId, you can call /v1/presence/users in the Presence API. Documentation can be found in the Presence API documentation page

While not encouraged, if you still need to fetch other user related fields such as externalDisplayName, created, description or isBanned, you can call /v1/users or /v1/user/{userId} in the Users API. Documentation can be found in the Users API documentation page


Please let us know if you have any questions below!
Thank you.


FAQ

When will the friend limit increase?

  • Our goal is to increase the friend limit in the coming months!

What happens if I don’t do anything?

  • If you are using the Friends API GetAllFriends endpoint to get Username/DisplayName or Presence information for friends, those fields will stop working. Changes are necessary to maintain functionality of features using those fields.

  • If you are using the Friends API GetAllFriends endpoint just to get Friend userIds, the endpoint will only return 200 top friends as we raise the friends limit.

  • If you are using the Engine API GetFriendsAsync endpoint isOnline field, all friends will appear offline.

150 Likes

This topic was automatically opened after 10 minutes.

This is incredible! We will finally be able to get more friends now!

19 Likes

Incredible update by roblox as usual. I’ve always supported the moves done by roblox. W Update as usual.

12 Likes

Amazing, this was anticipated and extremely popular! This will strengthen connections between people and enable more possibilities for prople who connect alot.

Though, will there be a Best Friend or similar future like back then so that we can select certain friends that can join us in games/see our inventory etc.?

18 Likes

Great update, can’t wait for more of those.

6 Likes

Are we going to get an option to access specific users followings and followers list easily as well as checking if there is a following between 2 users? Currently the following system doesn’t really have any proper use so we could at least find some in our custom in-experience systems and mechanisms.

10 Likes

This seems like a good update!
I’ve got so many questions however, with the addition of 1,000 Friends limit, will we be able to have some sort of “best friends” list?
Perhaps making it a client sided thing or private list?

I would also like to know, if we will get some more privacy customization?
Here are some examples:

(if there won’t be a best friends feature)

  • Whitelist (similar to private servers) for joins
  • Whitelist (similar to private servers) for users that can invite us to team create
  • Whitelist (similar to private servers) for users that can see our inventory & trade
  • Whitelist (similar to provate servers) for users that can add you to parties

(if there will be a best friends feature)

  • Allowing only best friends to trade/see inventory
  • Allowing only best friends to team create
  • Allowing only best friends to join us
  • Allowing only best friends to add to parties

Additionally, a new set of privacy would be nice:

  • making followers & friends list only visible to a certain amount of people
  • being able to customize our online status: invisible, online, dnd mode, etc

I would really love to start accepting a lot of friends requests when this feature is coming out! However I’m afraid of people inviting me to inappropriate games in team create, people randomly joining me when I only want to play with best friends, etc.

Would be nice to have any of these features come out with the increased limit!

29 Likes

So is there still a way to check if there’s something Online or not? I think there’s some other functions but just wondering. As i think that it’s always important to clarify alternatives, especially since I haven’t touched that API or anything close to it for very long.

3 Likes

See below


7 Likes

Oh cool, I don’t think that was there before.

3 Likes

Can we please get a way to be online without showing anyone that we’re online? I get chronically annoyed by people and it’s getting hard to tell them to leave me alone.

17 Likes

yeah, something like the discord invisible status. that would be nice

10 Likes

I’d like to bump this topic in relation to friends limit going up.

6 Likes

HUGE hype for the increased friend limit - for the past 6 years, my friend count has always been hovering around the 200 limit and it’s infuriating having to treat my friends list like an actual contact list and remove people that I deem to be ‘unworthy’ in favor of friending someone new. Hopefully Roblox will explore into making the friend system more robust than it currently is & has been for over the past 9 years in addition to this change.

A long time ago, Roblox used to have this feature (alongside an unlimited friend limit)! Sometime around 2014/2015 though, it was removed in favor of the modern friend system that stands today.

4 Likes

Finally I can drop my alts :rofl:

I primarily used my “alts stand savers” to add more friends, now with the limit being at 1k they aren’t required anymore.

2 Likes

Well made update. I am looking forward for this!
A thousand friends I can’t imagine lol. Is there any way for servers to have higher capacities to even fit such high numbers after the 1000 friend limit? Such as DataStore request #s, service requesting, etc?

1 Like

Awesome update, will the “IsOnline” show if the user is on studio or the website?

3 Likes

In light of friends updates, can we get custom status like discord to appear invisible or do not disturb.

2 Likes

Those used to exist before actually! But they got removed for some reason. Oh, I thought you meant like the status texts

3 Likes