[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.
