Friends

Finding Friends

Finding friends asks the server for the current online and room status of the given user ids (FindFriends(userIds) in C++, findFriends(userIds) in JavaScript). The result holds one entry per requested id.

Friends are identified purely by user id, so friend queries only work when players authenticate with stable, known user ids. The SDK does not store a friend graph: who is friends with whom lives in your backend or platform service, and the server only reports the live status of the ids you pass in.

C++	JavaScript	Description
`UserId`	`userId`	The id this entry describes.
`IsOnline`	`isOnline`	Whether the user is online.
`RoomName`	`roomName`	The room the user is in, empty when not in a room.
`IsInRoom`	`isInRoom`	Whether the user is in a room.

Look up two friends and join the first one who is in a room:

C++

JavaScript

C++

Task<Result<void>> JoinAFriend(RealtimeClient& client)
{
    std::vector<RealtimeCore::Common::StringType> friendIds = {PHOTON_STR("erwin"), PHOTON_STR("theodor")};

    Result<std::vector<FriendInfo>, FindFriendsError> friends = co_await client.FindFriends(friendIds);
    if (friends.IsErr())
    {
        co_return Result<void>::Err(friends.GetError());
    }

    for (const FriendInfo& info : friends.GetValue())
    {
        if (info.IsInRoom)
        {
            Result<Room, JoinRoomError> joined = co_await client.JoinRoom(info.RoomName);
            if (joined.IsErr())
            {
                co_return Result<void>::Err(joined.GetError());
            }
            co_return Result<void>::Ok();
        }
    }

    co_return Result<void>::Err(ErrorCode::RoomNotFound, PHOTON_STR("No friend is in a room right now"));
}

/* The rt_* blob helpers, copied from "Blob Helpers" on the C API page. */
#include "photon_blob.h"

static const char* friendIds[] = {"erwin", "theodor"};

realtime_find_friends(client, friendIds, 2);

/* FindFriendsResult carries [int32 count] then, per friend,
   [string userId][u8 isOnline][string roomName][u8 isInRoom] */
if (e->type == RealtimeEventType_FindFriendsResult && e->mode == 0 && e->blobOffset >= 0)
{
    rt_reader r     = rt_read(blob + e->blobOffset, e->blobLength);
    int32_t   count = rt_get_i32(&r);

    for (int32_t i = 0; i < count; ++i)
    {
        int32_t     userIdLen = 0;
        (void)rt_get_str(&r, &userIdLen);
        (void)rt_get_u8(&r); /* isOnline */

        int32_t     roomLen = 0;
        const char* room    = rt_get_str(&r, &roomLen);
        uint8_t     inRoom  = rt_get_u8(&r);

        if (inRoom && roomLen > 0 && roomLen < 64)
        {
            /* The blob dies at the next flush, so copy the name before joining. */
            char name[64];
            memcpy(name, room, (size_t)roomLen);
            name[roomLen] = '\0';

            realtime_join_room(client, name, 0);
            break;
        }
    }
}

/* realtime_find_friends takes an array of null-terminated UTF-8 strings
   and its count. realtime_get_friend_list returns the same layout for the
   last result without a round trip, and realtime_get_friend_list_age
   reports its age in milliseconds. */

JavaScript

const friends = await client.findFriends(['erwin', 'theodor']);

const friend = friends.find((info) => info.isInRoom);
if (friend) {
    await client.joinRoom(friend.roomName);
} else {
    console.log('No friend is in a room right now');
}

The Friend List

The client keeps the most recently fetched results and returns them without a server round trip (GetFriendList() in C++, friendList in JavaScript). It also reports the age of that snapshot in milliseconds (GetFriendListAge() in C++, friendListAge in JavaScript). Use the age to decide when a refresh warrants a new friend query instead of re-querying on every frame.

Last updated on 27/10/2026

Finding Friends
The Friend List