Product update · · 2 min read

Set content masking per conversation

Apply another role's masking rules to one user in one conversation, without changing their role.

Per-conversation content masking in TalkJS chat

Some marketplaces mask phone numbers and email addresses in chat so buyers and sellers don't take the deal off the platform. Once a booking is confirmed, that masking can get in the way. For example, a traveler and a guide need to swap numbers to meet up, but their roles still hide contact details in every conversation.

TalkJS now lets you set content masking per conversation. The takeSettingsFromRole participant field applies the content masking rules of another role to one user in one conversation, while the user keeps their own role everywhere else. You can set it with the REST API or the JavaScript Data API, and the Components SDK chat UI applies it from version 0.3.10 with @talkjs/core 1.12.1.

How per-conversation content masking works in TalkJS

Per-conversation content masking starts with a role whose masking rules allow what you need. For example, create a role named booking-confirmed: in the dashboard, go to Chat UI → Edit roles → Create role. In the new role's settings, under Mask unwanted content, set Mode to No suppression. If you're using your live app ID, publish the role to live as well.

When the booking is confirmed, call the REST API from your backend to point a participant in that booking's conversation at the role:

curl https://api.talkjs.com/v1/<APP_ID>/conversations/booking_8812/participants/traveler_alice \
  -H "Authorization: Bearer <SECRET_KEY>" \
  -H "Content-Type: application/json" \
  -X PATCH \
  -d '{ "takeSettingsFromRole": { "contentMasking": "booking-confirmed" } }'

TalkJS masks messages for each reader using that reader's own settings, so repeat the call for every participant who should see unmasked content. The new rules also apply to messages already in the conversation. To return a user to their own role's masking rules, set takeSettingsFromRole to null.

Keep the content masking override out of users' hands

Content masking is a moderation control, so you'll usually want to change it from a place your users can't reach. The JavaScript Data API can also set takeSettingsFromRole with ParticipantRef.set, but in the browser that call only works while conversation synchronization is on, and then users can change their own override too.

If you rely on masking, go to the dashboard's Settings page and, under Security, select Disallow conversation synchronization via the browser. Then set the override with the REST API. The docs on browser synchronization explain what else this setting changes.

What per-conversation content masking covers

Three things set the scope of the takeSettingsFromRole override: what it replaces, where TalkJS applies it, and which roles it can point at.

Get started with per-conversation content masking

Setting the field with the REST API needs no upgrade. The JavaScript Data API needs @talkjs/core 1.12.1 or later, and the Components SDK chat UI (@talkjs/react-components or @talkjs/web-components) needs version 0.3.10 or later alongside that core version. For a full example, see the guide to controlling content masking.