---
updatedAt: 2026-03-19T19:39:11.000Z
agentTools:
  projectIndex: https://developers.miro.com/llms.txt
---

# Session

**<span><img alt="Experimental feature" src="https://files.readme.io/4598fa6-experimental-flask-color.svg" width="24" ></span> Experimental**

##### 🔒 Requires scope: [boards:write](https://developers.miro.com/reference/scopes#boardswrite "boards:write")

An application can start and manage collaborative sessions for participants on a board through the `miro.board.collaboration` namespace. In order to implement collaborative features, such as setting the focus and viewport control of other users on a board, an application must first start an active session.

#### Concurrent sessions

Applications support the ability to run multiple active sessions at one time on a board (for example, breakout rooms). Only one application can run active, concurrent sessions on a board at a time. Participants on a board can only be in **one** unique session at a time.

ℹ️ Note: Once you start the [session](https://developers.miro.com/miro-ea/docs/websdk-reference-collaboration#startSession), you get a session object returned, with this object you can perform further operations, such as [ending](https://developers.miro.com/miro-ea/docs/websdk-reference-session#end) the session.

<figure>
  <img src="https://files.readme.io/0ed9666-session-flow.jpg" />
  <figcaption>A flow diagram which shows collaboration.startSession() method returns a session object, which allows you to access session methods.</figcaption>
</figure>

## Methods

***

### invite(...)

<pre class="sdk-reference-type">(users: Array&lt;<a href="#onlineuserinfo" title="OnlineUserInfo">OnlineUserInfo</a>&gt; | Array&lt;Array&lt;<a href="#onlineuserinfo" title="OnlineUserInfo">OnlineUserInfo</a>&gt;&gt;) =&gt; Promise&lt;void&gt;</pre>

##### 🚦 Rate limit: [Level 1](https://developers.miro.com/docs/rate-limiting "1")

##### 🔒 Requires scope: [boards:write](https://developers.miro.com/reference/scopes#boardswrite "boards:write")

Invites users on the board to a session. Accepts a list of [OnlineUsers](https://developers.miro.com/miro-ea/docs/boards#getonlineusers) to be invited to a session.

```typescript
const session = await miro.board.collaboration.startSession({
  name: 'My session'
});

const onlineUsers = await miro.board.getOnlineUsers();

// invites the online users to the session
await session.invite(onlineUsers)
```

***

### join(...)

<pre class="sdk-reference-type">() =&gt; Promise&lt;void&gt;</pre>

##### 🚦 Rate limit: [Level 1](https://developers.miro.com/docs/rate-limiting "1")

##### 🔒 Requires scope: [boards:write](https://developers.miro.com/reference/scopes#boardswrite "boards:write")

Joins current user to a session without an invitation.

```typescript
const session = await miro.board.collaboration.startSession({
  name: 'My session'
})
// joins the current user to the session, without invitation
await session.join()
```

***

### leave(...)

<pre class="sdk-reference-type">() =&gt; Promise&lt;void&gt;</pre>

##### 🔒 Requires scope: [boards:write](https://developers.miro.com/reference/scopes#boardswrite "boards:write")

##### 🚦 Rate limit: [Level 1](https://developers.miro.com/docs/rate-limiting "1")

Removes the current user from a session.

```typescript
const session = await miro.board.collaboration.startSession({
  name: 'My session'
});

// joins the current user to the session, without invitation
await session.join()

// leaves session as current user
await session.leave()
```

***

### getUsers(...)

<pre class="sdk-reference-type">() =&gt; Promise&lt;Array&lt;Pick&lt;<a href="#onlineuserinfo" title="OnlineUserInfo">OnlineUserInfo</a>, 'id'&gt;&gt;&gt;</pre>

##### 🔒 Requires scope: [boards:read](https://developers.miro.com/reference/scopes#boardsread "boards:read")

##### 🚦 Rate limit: [Level 1](https://developers.miro.com/docs/rate-limiting "1")

Retrieves users currently in a session.

```typescript
const session = await miro.board.collaboration.startSession({
  name: 'My session'
});

const onlineUsers = await miro.board.getOnlineUsers();
const usersInSession = await session.getUsers();


const unassignedUsers = onlineUsers.filter((online) => 
    !usersInSession.some(inSession => inSession.id === online.id)
);
```

***

### hasJoined(...)

<pre class="sdk-reference-type">(user: string) =&gt; Promise&lt;boolean&gt;</pre>

##### 🚦 Rate limit: [Level 1](https://developers.miro.com/docs/rate-limiting "1")

##### 🔒 Requires scope: [boards:read](https://developers.miro.com/reference/scopes#boardsread "boards:read")

Checks if the specified user has joined the session.

```typescript
const session = await miro.board.collaboration.startSession({
  name: 'My session'
});

const onlineUsers = await miro.board.getOnlineUsers();

const [participant] = onlineUsers

// invites the online users to the session
const hasJoined = await session.hasJoined(participant);
if (hasJoined) {
    const [frame] = await miro.board.get({ type: 'frame' });
    await miro.board.collaboration.zoomTo(participant, frame);
}
```

***

### on(...)

<pre class="sdk-reference-type">(<a href="#name" <a href="#title" title="title">title</a>="name">name</a>: 'user-joined', handler: (event: UserSessionEvent) =&gt; Promise&lt;void&gt;) =&gt; Promise&lt;void&gt;</pre>

Subscribes to specific session events in your app:

* `user-joined`: triggered when a user joins the session.
* `user-left`: triggered when a user leaves the session.
* `invitation-responded`: triggered when user responds to an invitation for a session.

Both `user-joined` and `user-left` events will receive a [UserSessionEvent](#usersessionevent) object as a parameter.

The `invitation-responded` event will receive an [InvitationResponseEvent](#invitationresponseevent) object as a parameter.

#### UserSessionEvent

<table><tr><th>Property</th><th>Type</th></tr>
<tr>
  <td><code>id</code></td>
  <td>
    <pre class="sdk-reference-type">string</pre>
  </td>
</tr>
<tr>
  <td><code>sessionId</code></td>
  <td>
    <pre class="sdk-reference-type">string</pre>
  </td>
</tr>
<tr>
  <td><code>userId</code></td>
  <td>
    <pre class="sdk-reference-type">string</pre>
  </td>
</tr></table>

#### InvitationResponseEvent

<table><tr><th>Property</th><th>Type</th></tr>
<tr>
  <td><code>response</code></td>
  <td>
    <pre class="sdk-reference-type">{
  reason: 'clicked-button' | 'timed-out' | 'clicked-outside'
  <a href="#status" title="status">status</a>: 'accepted' | 'rejected'
  user: string
}</pre>
  </td>
</tr></table>

```typescript
const session = await miro.board.collaboration.startSession({
  name: 'My session'
});

const handlerJoined = (event: UserSessionEvent) => console.log(`User ${event.user} has joined the session.`)
const handlerLeft = (event: UserSessionEvent) => console.log(`User ${event.user} has left the session.`)
const handlerInvitationResponded = (event: InvitationResponseEvent) => console.log(`User ${event.user} has ${event.status} the invitation due to ${event.reason}.`)

await session.on('user-joined', handlerJoined);
await session.on('user-left', handlerLeft);
await session.on('invitation-responded', handlerInvitationResponded);
```

***

### off(...)

<pre class="sdk-reference-type">(<a href="#name" <a href="#title" title="title">title</a>="name">name</a>: 'user-joined', handler: (event: UserSessionEvent) =&gt; Promise&lt;void&gt;) =&gt; Promise&lt;void&gt;</pre>

Unsubscribes from previously subscribed session events in your app:

* `user-joined`: triggered when a user joins the session.
* `user-left`: triggered when a user leaves the session.
* `invitation-responded`: triggered when user responds to an invitation for a session.

```typescript
const session = await miro.board.collaboration.startSession({
  name: 'My session'
});

const handlerJoined = (event: UserSessionEvent) => console.log(`User ${event.user} has joined the session.`)
const handlerLeft = (event: UserSessionEvent) => console.log(`User ${event.user} has left the session.`)
const handlerInvitationResponded = (event: InvitationResponseEvent) => console.log(`User ${event.user} has ${event.status} the invitation due to ${event.reason}.`)

await session.on('user-joined', handlerJoined);
await session.on('user-left', handlerLeft);
await session.on('invitation-responded', handlerInvitationResponded);

// Unsubscribe to events
await session.off('user-joined', handlerJoined);
await session.off('user-left', handlerLeft);
await session.off('invitation-responded', handlerInvitationResponded);
```

***

### end(...)

<pre class="sdk-reference-type">() =&gt; Promise&lt;void&gt;</pre>

##### 🚦 Rate limit: [Level 1](https://developers.miro.com/docs/rate-limiting "1")

##### 🔒 Requires scope: [boards:write](https://developers.miro.com/reference/scopes#boardswrite "boards:write")

Ends the session and automatically clears all events associated with the session.

```typescript
const session = await miro.board.collaboration.startSession({
  name: 'My session'
});

const handler = (event) => console.log('Session event', { event })

await session.on('user-joined', handler);

// events are automatically cleared up
await session.end();
```

***

## All properties

<table><tr><th>Property</th><th>Type</th></tr>
<tr>
  <td><code>color</code></td>
  <td>
    <pre class="sdk-reference-type">readonly string</pre>
  </td>
</tr>
<tr>
  <td><code>description</code></td>
  <td>
    <pre class="sdk-reference-type">readonly string</pre>
  </td>
</tr>
<tr>
  <td><code>id</code></td>
  <td>
    <pre class="sdk-reference-type">readonly string</pre>
  </td>
</tr>
<tr>
  <td><code>name</code></td>
  <td>
    <pre class="sdk-reference-type">readonly string</pre>
  </td>
</tr>
<tr>
  <td><code>starterId</code></td>
  <td>
    <pre class="sdk-reference-type">readonly string</pre>
  </td>
</tr>
<tr>
  <td><code>starterName</code></td>
  <td>
    <pre class="sdk-reference-type">readonly string</pre>
  </td>
</tr>
<tr>
  <td><code>end(...)</code></td>
  <td>
    <pre class="sdk-reference-type">() =&gt; Promise&lt;void&gt;</pre>
  </td>
</tr>
<tr>
  <td><code>getUsers(...)</code></td>
  <td>
    <pre class="sdk-reference-type">() =&gt; Promise&lt;Array&lt;Pick&lt;<a href="#onlineuserinfo" title="OnlineUserInfo">OnlineUserInfo</a>, 'id'&gt;&gt;&gt;</pre>
  </td>
</tr>
<tr>
  <td><code>hasJoined(...)</code></td>
  <td>
    <pre class="sdk-reference-type">(user: string) =&gt; Promise&lt;boolean&gt;</pre>
  </td>
</tr>
<tr>
  <td><code>invite(...)</code></td>
  <td>
    <pre class="sdk-reference-type">(users: Array&lt;<a href="#onlineuserinfo" title="OnlineUserInfo">OnlineUserInfo</a>&gt; | Array&lt;Array&lt;<a href="#onlineuserinfo" title="OnlineUserInfo">OnlineUserInfo</a>&gt;&gt;) =&gt; Promise&lt;void&gt;</pre>
  </td>
</tr>
<tr>
  <td><code>join(...)</code></td>
  <td>
    <pre class="sdk-reference-type">() =&gt; Promise&lt;void&gt;</pre>
  </td>
</tr>
<tr>
  <td><code>leave(...)</code></td>
  <td>
    <pre class="sdk-reference-type">() =&gt; Promise&lt;void&gt;</pre>
  </td>
</tr>
<tr>
  <td><code>off(...)</code></td>
  <td>
    <pre class="sdk-reference-type">(<a href="#name" <a href="#title" title="title">title</a>="name">name</a>: 'user-joined', handler: (event: UserSessionEvent) =&gt; Promise&lt;void&gt;) =&gt; Promise&lt;void&gt;</pre>
  </td>
</tr>
<tr>
  <td><code>on(...)</code></td>
  <td>
    <pre class="sdk-reference-type">(<a href="#name" <a href="#title" title="title">title</a>="name">name</a>: 'user-joined', handler: (event: UserSessionEvent) =&gt; Promise&lt;void&gt;) =&gt; Promise&lt;void&gt;</pre>
  </td>
</tr></table>

# Sibling pages

* [Interact with boards and items](https://developers.miro.com/miro-ea/docs/websdk-reference-interact-with-boards-and-items.md)
* [Rate limiting](https://developers.miro.com/miro-ea/docs/websdk-reference-rate-limiting.md)
* [Error handling](https://developers.miro.com/miro-ea/docs/websdk-reference-error-handling.md)
* [Board](https://developers.miro.com/miro-ea/docs/websdk-reference-board.md)
* [Card](https://developers.miro.com/miro-ea/docs/websdk-reference-card.md)
* [Board UI](https://developers.miro.com/miro-ea/docs/websdk-reference-ui.md)
* [Viewport](https://developers.miro.com/miro-ea/docs/websdk-reference-viewport.md)
* [Notifications](https://developers.miro.com/miro-ea/docs/websdk-reference-notifications.md)
* [App card](https://developers.miro.com/miro-ea/docs/websdk-reference-app-card.md)
* [Experimental](https://developers.miro.com/miro-ea/docs/websdk-reference-experimental.md)
* [Realtime Events](https://developers.miro.com/miro-ea/docs/websdk-reference-events.md)
* [Tag](https://developers.miro.com/miro-ea/docs/websdk-reference-tag.md)
* [Custom Action Management](https://developers.miro.com/miro-ea/docs/websdk-reference-custom-action-management.md)
* [Shape](https://developers.miro.com/miro-ea/docs/websdk-reference-shape.md)
* [Frame](https://developers.miro.com/miro-ea/docs/websdk-reference-frame.md)
* [Image](https://developers.miro.com/miro-ea/docs/websdk-reference-image.md)
* [Sticky Note](https://developers.miro.com/miro-ea/docs/websdk-reference-sticky-note.md)
* [Shape experimental](https://developers.miro.com/miro-ea/docs/websdk-reference-shape-experimental.md)
* [Embed](https://developers.miro.com/miro-ea/docs/websdk-reference-embed.md)
* [Connector](https://developers.miro.com/miro-ea/docs/websdk-reference-connector.md)
* [Unsupported](https://developers.miro.com/miro-ea/docs/websdk-reference-unsupported.md)
* [Mindmap Node](https://developers.miro.com/miro-ea/docs/websdk-reference-mindmap-node.md)
* [Preview](https://developers.miro.com/miro-ea/docs/websdk-reference-preview.md)
* [Text](https://developers.miro.com/miro-ea/docs/websdk-reference-text.md)
* [Storage collection](https://developers.miro.com/miro-ea/docs/websdk-reference-collection.md)
* [Storage](https://developers.miro.com/miro-ea/docs/websdk-reference-storage.md)
* [Collaboration](https://developers.miro.com/miro-ea/docs/websdk-reference-collaboration.md)
* [Attention](https://developers.miro.com/miro-ea/docs/websdk-reference-attention.md)
* [Group](https://developers.miro.com/miro-ea/docs/websdk-reference-group.md)
* [History](https://developers.miro.com/miro-ea/docs/websdk-reference-history.md)
* [Tools](https://developers.miro.com/miro-ea/docs/websdk-reference-tools.md)