TalkJS’s Conversation Actions allow users to perform different actions within the context of a conversation, such as leaving the conversation or marking it as unread. However, you can also create new custom actions for users. In this tutorial, we’ll demonstrate how to lock a conversation to read-only using conversation actions.

To follow along, you’ll need:

• A TalkJS account. TalkJS provides a ready-to-use chat client for your application. Your account gives you access to TalkJS's free development environment.
• An existing TalkJS project using the JavaScript Chat SDK. Before starting this guide, follow the Getting Started documentation to create a simple conversation between two users.
  

This guide explains the process step-by-step, using code examples and screenshots along the way. If you would prefer to see the example code in its entirety, see the GitHub repo for this guide.

Create an admin user role

You can configure which actions a user is able to take based on their role. We’ll create a new role called admin and assign it to one of our users.

Create roles from the TalkJS dashboard. Click the Create Role button and type “admin” under Role name:

This admin user will be the person who will lock the conversation to read-only for all participants, including themselves.

Add a custom conversation action to the admin role

Select this newly created admin role to configure the role settings. In the settings page for this role, we can create a new custom conversation action that will allow us to set the conversation to read-only for all users:

Provide the following values:

• Name: setReadOnly
• Label: Set read-only
• Permission: Allow
  

Click the Add action button to confirm the creation of this custom action. The name is used to refer to this action within the JavaScript SDK. The label is displayed in the UI action menu. When the user selects a custom action, an event is triggered within the JavaScript SDK, that you can listen for, and use to run whatever code you want in response.

Click the Save All Roles button to finish associating this new action with our new admin role.

Assign a role to a user

We need to assign a user to have our new admin role. To give a user a role, return to the code where that user was created, and add the role:

var me = new Talk.User({
  id: "123456",
  name: "Alice",
  email: "alice@example.com",
  photoUrl: "https://talkjs.com/images/avatar-1.jpg",
  welcomeMessage: "Hey there! How are you? :-)",
  role: "admin", // New role
});

Now that our user named Alice is assigned to the me variable and has the admin role. For more information on adding roles to users, see Assign a role to a user.

If you run the code, you should see the Set read-only button available in the dropdown menu:

However, at this stage, the Set read-only button has no functionality. In the next section, we’ll set the conversation to be read-only when the button is pressed. If you're using a legacy theme, or customized a theme before the custom conversation actions feature was released, you'll need to add this menu to your theme before it will show up. See our docs for details on how to edit the theme.

Set conversation to read-only using the JavaScript SDK

We have already created the custom action for setting the conversation to read-only, however, we have not defined the required functionality yet. We need to add an event listener that will trigger when the Set read-only button is clicked. Add the following JavaScript code to your project:

inbox.onCustomConversationAction("setReadOnly", (event) => {
    
    // lock to read-only code will go here

});

Here we've used the onCustomConversationAction method on the inbox to listen for the setReadOnly custom action we created in the previous section.

Let’s add the code to lock our conversation to read-only:

inbox.onCustomConversationAction('setReadOnly', (event) => {
  console.log('Locked conversation with id:', event.conversation.id);
  conversation = talkSession.getOrCreateConversation(event.conversation.id);
  conversation.setParticipant(me, { access: 'Read' });
  conversation.setParticipant(other, { access: 'Read' });
  inbox.select(conversation);
});

Let’s break down this example.

The first line prints a message to the console along with the conversation id that’s tied to this event listener and custom action: console.log('Locked conversation with id:', event.conversation.id);

Next, we set each user to have read-only access using the `setParticipant` method. This locks the conversation to read-only for all users:

  conversation = talkSession.getOrCreateConversation(event.conversation.id);
  conversation.setParticipant(me, { access: 'Read' });
  conversation.setParticipant(other, { access: 'Read' });

Finally, we reselect our conversation, which reloads both users and enforces their read-only access:

inbox.select(conversation);

Now if you launch your application, you will see the following warning informing you that you can still read, but not send messages:

This conversation is now locked for all of the users in our conversation.

Conclusion

We now have a working demo of how we can add an action to a conversation that will allow users to lock the conversation to read-only! To achieve this, we completed the following steps:

• Created a new admin user role.
• Assigned a custom action to appear in the dropdown menu for all admin users.
• Assigned our admin role to one of our users.
• Created code for our custom action method that locked the conversation to read-only.
  

For the full example code for this tutorial, see our GitHub repo.

If you want to learn more about TalkJS, here are some good places to start:

• The TalkJS Docs help you get started with TalkJS.
• TalkJS tutorials provide how-to guides for many common TalkJS use cases.
• The talkjs-examples Github repo has larger complete examples that demonstrate how to integrate with other libraries and frameworks.