Skip to main content

Attention

Experimental feature Experimental

attention is the namespace that groups methods that apps can use to focus board attention on specific online users.
Through miro.board.collaboration.attention, apps can access methods to:

  • Start following another user on the board.
  • Make a list of users follow another specified user on the board.
  • Bring a list of users to the current user on the board.
  • Stop following another user on the board.
  • Stop a list of users from following a specified user on the board.
  • Check if a user is already following another user on the board.
  • Get details about the user that is currently being followed on the board.

When a user follows another user on the board, the follower sees the same viewport as the user they are following. This can be convenient in a scenario where a user wants to view or participate in another user's actions on the board. For example, during a presentation; or when a moderator wishes to check a user's work on the board.

To make the feature available on a board, the follower needs to install a dedicated app that manages attention.

  • follow: initiates the process of following a specified online user(s), referred to as the followed user.
  • unfollow: is used to stop a user(s) from following another user.
  • isFollowing: checks whether the current user is already following another user on the board.
  • getFollowedUser: if a user is following another user, the method returns the followed user details.

Methods

follow(...)

(followee: OnlineUserInfo, options?: FollowUserSessionsOptions) => Promise<void>
🚦 Rate limit: Level 1

Experimental feature Experimental

The follow method is part of the miro.board.collaboration.attention namespace. It initiates the process of following a specified online user, referred to as the followed user.

Here's an example of how to use this method:

await miro.board.collaboration.attention.follow(followedUser, sessionOptions);

Typically, the user who initiates the following is considered the follower. However, when sessionOptions are provided, the followers are determined by the sessionOptions.

The sessionOptions parameter can include an array of followers. This allows facilitators to create a custom list of users who will follow the specified followee user. All followers should be in a collaboration session initiated by this app.

ℹ️ Note:

  • Users cannot follow themselves: a user cannot be both the follower and the followed user simultaneously.
  • If the promise doesn't return within 3 seconds, the method times out.
  • An error occurs if the followers list contains the initiating follower or if any listed followers are not part of the collaboration session.

To start a following session, a dedicated attention manager app must be installed. This app is responsible for managing the collaboration session and ensuring that all followers are part of the session.

Follow example:

// Get current online users.
const onlineUsers = await miro.board.getOnlineUsers();

// Retrieve the user that you want to follow.
const followedUser = onlineUsers.find((user) => user.name.includes("Sara"));

// The current user (follower) starts following the user called "Sara" (followed user or followee).
await miro.board.collaboration.attention.follow(followedUser);

Initiate a following session for a group of users to collectively follow a specific user:

// Get current online users.
const onlineUsers = await miro.board.getOnlineUsers();

// Retrieve the user that you want to follow.
const followedUser = onlineUsers.find((user) => user.name.includes("Sara"));

// Specify the followers.
const followers = onlineUsers.filter(
  (user) => user.name.includes("John") || user.name.includes("Alice")
);

// John and Alice (followers) are set to follow Sara (followed user or followee).
// Note: All followers must be in a collaboration session.
await miro.board.collaboration.attention.follow(followedUser, { followers });

Bring several users to the current user example (set of users will follow current user):

const currentUser = await miro.board.getUserInfo(); // Get the current user.
const onlineUsers = await miro.board.getOnlineUsers();

// The current user (follower) starts a following session.
// John and Alice, will follow the current user.
const followers = onlineUsers.filter(
  (user) => user.name.includes("John") || user.name.includes("Alice")
);

// Note: All followers must be in a collaboration session.
await miro.board.collaboration.attention.follow(currentUser, { followers });

unfollow(...)

(options?: UnfollowUserSessionsOptions) => Promise<void>
🚦 Rate limit: Level 1

Experimental feature Experimental

The unfollow method is used to stop a user from following another user. If a user is currently following another user, invoking this method will stop the following session. If there's no following session in progress, the method returns an error.

Before invoking unfollow, check if a following session is in progress by running isFollowing.

The unfollow method includes support for an additional optional sessionOptions parameter, which enhances its functionality:

  • You can include an array of followers and followee in the sessionOptions parameter. This provides more flexibility and control over the unfollowing process.

  • An error will not occur if the followee is included in the followers array or if there is no ongoing following session. This ensures a smoother handling of the unfollow operation, preventing disruptions in the execution flow.

  • If the sessionOptions parameter is provided, the unfollow operation will be executed only for the specified list of followers and followee, not the current user. This allows developers to tailor the unfollow action to a specific set of users, offering a more customized and targeted approach.

However, an error will occur if some of the followers are not in a collaboration session. It's important to ensure that all followers are in a collaboration session before attempting to unfollow.

Example of unfollowing without specifying the followers:

// Get the current user.
const currentUser = await miro.board.getUserInfo();

// The current user initiates the unfollow operation.
await miro.board.collaboration.attention.unfollow();

Example of unfollowing with specifying the followers:

// Get the current user.
const currentUser = await miro.board.getUserInfo();

// Example with specifying followers:
const followers = onlineUsers.filter(
  (user) => user.name.includes("John") || user.name.includes("Alice")
);

// The current user initiates the unfollow operation for John and Alice.
// The specified followers will stop following the followee (if they are following).
// Each follower should be in collaboration session, otherwise error will occur.
await miro.board.collaboration.attention.unfollow({
  followers,
  followee: currentUser,
});

isFollowing(...)

() => Promise<boolean>
🚦 Rate limit: Level 1

Experimental feature Experimental

Checks whether the current user is already following another user on the board.

  • If the user is following another user, the method returns true.
  • Otherwise, it returns false.

Example:

// Check if the current user is following another user.
const isFollowing = await miro.board.experimental.attention.isFollowing();

// Get currently online users.
const onlineUsers = await miro.board.getOnlineUsers();

// You can implement custom logic to return the user object
// that you want to assign to the follower as a followed user.
const followedUser = onlineUsers.find((user) => user.name.contains('Sara'));

// In case the session starter is already following a user other than "Sara":
if (isFollowing) {
  // Get the details of the current followed user.
  const currentFollowedUser = await miro.board.experimental.attention.getFollowedUser();

  if (currentFollowedUser.id !== followedUser.id) {
    // Unfollow the current followed user.
    await miro.board.experimental.attention.unfollow();
  }
}

// Start following the user called "Sara".
await miro.board.experimental.attention.follow(followedUser);

getFollowedUser(...)

() => Promise<OnlineUserInfo>
🚦 Rate limit: Level 1

Experimental feature Experimental

If a user is following another user, the method returns the followed user details.
If there's no following session in progress, the method returns an error.

Before invoking getFollowedUser, check if a following session is in progress by running isFollowing.

Example:

// Check if the current user is following another user.
const isFollowing = await miro.board.experimental.attention.isFollowing();

// Get currently online users.
const onlineUsers = await miro.board.getOnlineUsers();

// You can implement custom logic to return the user object
// that you want to assign to the follower as a followed user.
const followedUser = onlineUsers.find((user) => user.name.contains('Sara'));

// In case the session starter is already following a user other than "Sara":
if (isFollowing) {
  // Get the details of the current followed user.
  const currentFollowedUser = await miro.board.experimental.attention.getFollowedUser();

  if (currentFollowedUser.id !== followedUser.id) {
    // Unfollow the current followed user.
    await miro.board.experimental.attention.unfollow();
  }
}

// Start following the user called "Sara".
await miro.board.experimental.attention.follow(followedUser);

Type definitions

OnlineUserInfo
{ id: string; name: string }
FollowUserSessionsOptions
{ followers?: Array<OnlineUserInfo> }
UnfollowUserSessionsOptions
{ followee: OnlineUserInfo; followers: Array<OnlineUserInfo> }

All properties

PropertyType
follow(...) 
(followee: OnlineUserInfo, options?: FollowUserSessionsOptions) => Promise<void>
getFollowedUser(...) 
() => Promise<OnlineUserInfo>
isFollowing(...) 
() => Promise<boolean>
unfollow(...) 
(options?: UnfollowUserSessionsOptions) => Promise<void>