Skip to main content

Revoking a user's real-time access

REQUIREMENTS

To be able to implement this guide, you need to learn how to insert PHP snippets to your website.

You can find guide here: WP Beginner

Denying a user's REST requests stops what they can load from now on, but a browser that is already connected keeps its WebSocket session. To cut a member off at once — a suspended account, a member who is no longer eligible — tell the WebSocket server. It closes every open session of the user and refuses new ones until you let them back.

This applies to the WebSocket version, 3.0.13 or newer.

Revoking cuts the user off every conversation at once. To take them out of one conversation or chat room and leave the rest alone, see Only one conversation.

When something changes on your side#

Call the action from whatever marks the member as ineligible:

<?php
// The member is suspended: close their sessions now and refuse new ones.
do_action( 'better_messages_revoke_user', $user_id );

// The member is reinstated: let them connect again.
do_action( 'better_messages_restore_user', $user_id );

Both work for guests too (negative user IDs).

Deciding eligibility in one place#

If eligibility follows from something Better Messages can check, such as a role, use the filter instead:

<?php
add_filter( 'better_messages_user_can_connect', function( $can_connect, $user_id ){
    $user = get_userdata( $user_id );

    if( $user && in_array( 'suspended', (array) $user->roles, true ) ){
        return false;
    }

    return $can_connect;
}, 10, 2 );

Better Messages checks the filter before giving a page its connection details, and again whenever a user's role changes: it revokes the user when the filter says no, and lets them back when it says yes again. A user you revoked with the action stays revoked until you call better_messages_restore_user.

Only one conversation#

The WebSocket server follows each conversation's participants, so taking a user out of a conversation is enough to cut them off it. Their open sessions stop receiving it at once, it disappears from their messenger, and nothing they send reaches it any more. Their other conversations are not touched.

For a private or group conversation, remove the user, and add them again to let them back:

<?php
// Take the user out of the conversation.
Better_Messages()->functions->remove_participant_from_thread( $thread_id, $user_id );

// Let them back in.
Better_Messages()->functions->add_participant_to_thread( $thread_id, $user_id );

A chat room lets anyone whose role allows it join again, so ban the user as well, as the Ban button does. The ban's length is in minutes:

<?php
// Ban the user from the chat room for a week and take them out of it.
Better_Messages()->moderation->restrict_user( 'ban', $user_id, $thread_id, 7 * 24 * 60 );
Better_Messages()->functions->remove_participant_from_thread( $thread_id, $user_id );

// Lift the ban early. The user can join the room again.
Better_Messages()->moderation->un_restrict_user( 'ban', $user_id, $thread_id );
  • Chat rooms where only present users are participants keep no participant list, and the ban alone does it: the user's open sessions are taken out of the room, and they cannot come back until the ban is lifted or expires.
  • Chat rooms that can be read without joining stay readable to a banned user. The ban keeps them from joining and writing.
  • Conversations that belong to a group — a BuddyPress, PeepSo or Ultimate Member group, a course or a community space — follow the group's members and add back anyone missing. Remove the user from the group itself.

Built in#

  • Ultimate Member: when an approved member's account status changes to anything else (inactive, rejected, back to review), their sessions are revoked, and restored when the account is approved again. A member whose status is not approved is also never given connection details, however the status was set.

Events already on their way when the revocation is processed (a matter of milliseconds) can still arrive. Nothing sent after it reaches the revoked sessions.