> For the complete documentation index, see [llms.txt](https://docs.apryse.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apryse.com/web/collaboration/mentions-api.md).

# Mentions

Enhance collaboration with WebViewer's mention feature. Capture and send data, notify users, and customize settings for seamless real-time interaction. Learn how to import user data, set callbacks, an

To make the realtime collaboration flow even better, WebViewer provides APIs that can be used to capture mentions in the notes panel. The mentions contain the data that can be sent to a server, and notify other users in the same collaboration session.

![](https://3532544125-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FX9YnTSKIHvV7m0A36LbO%2Fuploads%2Fgit-blob-d48fa48e1c969c4b1911f7c6e3b8130c435124ef%2F6b2f620384e6587a2022dca06a0966b69fc68b2b-1898x628.gif?alt=media)

## Import user data into the viewer

The first thing to enable the mentions feature in the viewer is to import user data using [setUserData](https://sdk.apryse.com/api/web/UI.MentionsManager.html#setUserData__anchor).

{% tabs %}
{% tab title="JavaScript (SDK v8.0+)" %}
{% code lineNumbers="true" %}

```js
WebViewer(...)
  .then(instance => {
    const userData = [
      {
        value: 'John Doe', // required property
        email: 'johndoe@gmail.com', // optional property
        // you can have more optional properties here, and they will be passed back in the mentionChanged event callback
      },
      {
        value: 'Jane Doe',
        email: 'janedoe@gmail.com'
      },
    ];

    instance.UI.mentions.setUserData(userData);
  });
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript (SDK v7.0+)" %}
{% code lineNumbers="true" %}

```js
WebViewer(...)
  .then(instance => {
    const userData = [
      {
        value: 'John Doe', // required property
        email: 'johndoe@gmail.com', // optional property
        // you can have more optional properties here, and they will be passed back in the mentionChanged event callback
      },
      {
        value: 'Jane Doe',
        email: 'janedoe@gmail.com'
      },
    ];

    instance.mentions.setUserData(userData);
  });
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Provide a callback function to lookup users

Instead of providing a hardcoded list and setting user data, you can provide a callback function that will look up the users based on the user entry.

{% tabs %}
{% tab title="JavaScript" %}
{% code lineNumbers="true" %}

```js
WebViewer(...)
  .then(function(instance) {
    instance.mentions.setMentionLookupCallback(async (userData, searchTerm) => {
      const matches = [];
      userData.forEach((user) => {
        if (user.name === 'John Doe') {
          matches.push(user);
        }
      });
      return matches;
    });
  });
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Listen to the mentionChanged event to capture mentions in a comment

The `instance.UI.mentions` instance exposes a [mentionChanged](https://sdk.apryse.com/api/web/UI.MentionsManager.html#event:mentionChanged__anchor) event that works in a very similar way as [annotationChanged](https://sdk.apryse.com/api/web/Core.AnnotationManager.html#event:annotationChanged__anchor). This event will be triggered whenever a mention is added, modified, or deleted from the notes panel.

{% tabs %}
{% tab title="JavaScript (SDK v8.0+)" %}
{% code lineNumbers="true" %}

```js
WebViewer(...)
  .then(instance => {
    instance.UI.mentions.on('mentionChanged', (mentions, action) => {
      if (action === 'add') {
        // a new mention was just added to a comment
      }

      if (action === 'modify') {
        // the mentioned names in a comment didn't change, but the surrounding text was changed
      }

      if (action === 'delete') {
        // a mention was just deleted from a comment
      }

      console.log(mentions);
      // [
      //   {
      //     value: 'John Doe',
      //     email: 'johndoe@gmail.com',
      //     annotId: '...', // the annotation to which the mention belongs to
      //   },
      //   {
      //     value: 'Jane Doe',
      //     email: 'janedoe@gmail.com'
      //     annotId: '...',
      //   },
      // ]
    })
  });
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript (SDK v7.0+)" %}
{% code lineNumbers="true" %}

```js
WebViewer(...)
  .then(instance => {
    instance.mentions.on('mentionChanged', (mentions, action) => {
      if (action === 'add') {
        // a new mention was just added to a comment
      }

      if (action === 'modify') {
        // the mentioned names in a comment didn't change, but the surrounding text was changed
      }

      if (action === 'delete') {
        // a mention was just deleted from a comment
      }

      console.log(mentions);
      // [
      //   {
      //     value: 'John Doe',
      //     email: 'johndoe@gmail.com',
      //     annotId: '...', // the annotation to which the mention belongs to
      //   },
      //   {
      //     value: 'Jane Doe',
      //     email: 'janedoe@gmail.com'
      //     annotId: '...',
      //   },
      // ]
    })
  });
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Set the allowed trailing characters

By default, a user name won't be considered as a mention if it is followed by any characters except a space, but this setting can be changed by using the [setAllowedTrailingCharacters](https://sdk.apryse.com/api/web/UI.MentionsManager.html#setAllowedTrailingCharacters__anchor) API

{% tabs %}
{% tab title="JavaScript (SDK v8.0+)" %}
{% code lineNumbers="true" %}

```js
WebViewer(...)
  .then(instance => {
    instance.UI.mentions.setUserData([
      {
        value: 'John Doe',
      },
    ]);
     // this is considered as a mention, because `@John Doe` is at the end of the string
    'Hello, @John Doe'
     // this is considered as a mention, because `@John Doe` is followed by a space
    'Hello, @John Doe How are you?'
     // this is NOT considered as a mention, because `@John Doe` is followed by a comma
    '@John Doe, Hello!'
     instance.UI.mentions.setAllowedTrailingCharacters([' ', ',']);
     // this is now considered as a mention, because comma is an allowed trailing character
    '@John Doe, Hello!'
  });
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript (SDK v7.0+)" %}
{% code lineNumbers="true" %}

```js
WebViewer(...)
  .then(instance => {
    instance.mentions.setUserData([
      {
        value: 'John Doe',
      },
    ]);
     // this is considered as a mention, because `@John Doe` is at the end of the string
    'Hello, @John Doe'
     // this is considered as a mention, because `@John Doe` is followed by a space
    'Hello, @John Doe How are you?'
     // this is NOT considered as a mention, because `@John Doe` is followed by a comma
    '@John Doe, Hello!'
     instance.mentions.setAllowedTrailingCharacters([' ', ',']);
     // this is now considered as a mention, because comma is an allowed trailing character
    '@John Doe, Hello!'
  });
```

{% endcode %}
{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.apryse.com/web/collaboration/mentions-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.