Roles

A role is a collection of settings that determines both the look and the behavior of TalkJS for a user, as well as what actions a user can perform.

For example, you may want some users to be able to share files, or suppress certain types of content for another group of users. Roles allow you to adjust all these settings for specific groups of users.

Within a chat, different users can have different roles. A user can have only a single role at any time. You control which user gets which role.

Role settings

A role allows you to define the following settings for a user.

General

Select general chat features and actions that are available to a user:

  • Show typing indicators
  • Allow file sharing
  • Allow location sharing
  • Allow mentions
  • Display online status indicators
  • Allow recording voice messages

UI theme

Select a theme to change the look-and-feel of the user interface.

Actions and permissions

Select the actions that users are able to perform on individual messages and on conversations:

  • Built-in message actions: delete, edit, reply to, or give an emoji reaction to a message.
  • Built-in conversation actions: leave a conversation, or mark a conversation as unread.
  • Custom message actions
  • Custom conversation actions

General notifications

Set the timeout of the period of inactivity after which a notification should be sent to a user. For more on notifications, see: Notifications.

Email settings

Customize the email notification that TalkJS sends to an inactive user.

SMS settings

Customize the SMS notification that TalkJS sends to an inactive user.

Mask unwanted content

Specify where and what type of content should be suppressed in messages, if any. You have the option to:

  • Suppress links
  • Suppress email addresses
  • Suppress phone numbers
  • Specify allowed hostnames or email addresses
  • Specify allowed phone numbers
  • Set custom content suppression patterns
  • Specify exceptions to suppression patterns

Link opening settings

Set how links should be opened. By default, links posted in the chat window open in a new tab.

How to create and use a role

You can create and update roles from the Roles page of your TalkJS dashboard.

If you signed up after 2024-04-17, then any user you create without assigning them a role, automatically gets assigned the "default" role. If you signed up before that date, then users created without a role have no role automatically assigned.

Create a role

  1. Go to the Roles page on your dashboard. You can navigate to the roles page by selecting Edit roles at the top of either the Chat UI page or the Notification settings page.
  2. At the bottom of the roles overview, click Create role.
  3. Fill out a name for your new role.
  4. Click Create to create your role.

Assign a role to a user

You assign a role to a user when you create or update the user. For example, if the name of the role you created on the dashboard is buyer, you can assign the buyer role to the user "Alice" in your code like this:

1const me = new Talk.User({
2    id: "123456",
3    name: "Alice",
4    email: "[email protected]",
5    photoUrl: "https://talkjs.com/images/avatar-1.jpg",
6    welcomeMessage: "Hey there! How are you? :-)"
7    role: "buyer" // <-- that's the one!
8});

Make sure the name of the role corresponds precisely to the name that you gave your role in the dashboard when creating the role.

If you don't explicitly assign a user a role, the user automatically gets the role "default".