Moderate message content
Check messages with your own rules or an AI service and remove unwanted content.
Content suppression lets you mask unwanted words and contact details in the chat UI using the TalkJS dashboard. However, this can be insufficient if you have technical users willing to work around the masking. Using webhooks for moderation lets you fully delete offending messages, and means your moderation rules can be much more complex. This includes the ability to use an external service such as AI moderation tools.
You'll first write a function on your server that checks a message and deletes it if it breaks your rules. Then you'll add a webhook endpoint that calls the function and register its URL in the TalkJS dashboard. The example uses NodeJS and works with any TalkJS SDK.
Once the webhook is connected, TalkJS will send your endpoint a message.sent event when someone sends a message and a message.updated event when they edit one. Add this function to your backend to handle both events.
async function moderateMessage(event) {
if (event.type !== 'message.sent' && event.type !== 'message.updated') {
return;
}
const message = event.data.message;
const text = message.text;
if (text && await shouldRemoveMessage(text)) {
await deleteMessage(message.conversationId, message.id);
}
}shouldRemoveMessage is where you put your moderation rules. This example deletes messages containing email addresses, so users can't share contact details and move off-platform. Since the message is deleted entirely, there's no way for technical users to fetch the original message using the TalkJS API and bypass your moderation.
function shouldRemoveMessage(text) {
return /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i.test(text);
}You can replace this function with a call to an external service, as shown in Use AI moderation below.
Use the REST API to delete messages that fail your check. Deleting a message removes it from TalkJS and from connected chat UIs.
// Your app ID from the TalkJS dashboard.
const appId = '<APP_ID>';
async function deleteMessage(conversationId, messageId) {
// Reuse your existing Admin JWT generation code
// Example: https://talkjs.com/docs/REST_API/#authentication
const token = generateAdminJwt();
const response = await fetch(
`https://api.talkjs.com/v1/${appId}/conversations/${encodeURIComponent(conversationId)}/messages/${encodeURIComponent(messageId)}`,
{
method: 'DELETE',
headers: { Authorization: `Bearer ${token}` },
}
);
await response.text();
if (response.status === 200) {
return;
}
// A repeated webhook may refer to a message you've already deleted.
if (response.status === 404) {
return;
}
throw new Error(`Message deletion failed: ${response.status}`);
}You can also record the sender's user ID when you remove a message, so you can identify repeated attempts and ban the user from your platform.
Add a POST endpoint to your server. For each request, verify the webhook signature, then pass the event to moderateMessage. Here’s how that looks in Express.
import express from 'express';
const app = express();
// Register this route before any express.json() middleware.
app.post('/webhooks/talkjs', express.raw({ type: 'application/json' }), async (req, res) => {
// Use your webhook signature verification function here.
if (!verifyTalkJSSignature(req)) {
res.sendStatus(401);
return;
}
try {
const event = JSON.parse(req.body.toString('utf8'));
await moderateMessage(event);
res.sendStatus(200);
} catch {
res.sendStatus(500);
}
});
app.listen(process.env.PORT || 3000);In the TalkJS dashboard:
- Open your app's Settings, scroll to Webhooks and click Add new webhook.
- Enter your endpoint's public HTTPS URL, such as
https://example.com/webhooks/talkjs. - Under Select Events to Subscribe, select message.sent and message.updated, then click Save.
The handler returns 200 OK after the check and any deletion succeed. If the moderation service or REST request fails, it returns 500 so TalkJS can retry the event.
TalkJS waits five seconds for your endpoint to respond. If reviews take longer, save the event before returning 200 OK and have a worker run the check and retry failures. See Setting up a webhook relay for receiving and storing events independently of your backend.
With the email-address rule enabled, send “Please email me at hello@example.com”. The message will disappear after your webhook processes it. Send an ordinary message, then edit it to include an email address to check that edits are reviewed too.
For checks such as abusive language, replace shouldRemoveMessage with a call to a moderation service. For example, the OpenAI moderation API classifies harmful content and returns a flagged result. Set OPENAI_API_KEY on your server, then use:
async function shouldRemoveMessage(text) {
const response = await fetch('https://api.openai.com/v1/moderations', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ model: 'omni-moderation-latest', input: text }),
});
if (!response.ok) {
throw new Error(`Moderation failed: ${response.status}`);
}
const result = await response.json();
return result.results[0].flagged;
}With this version, the webhook handler deletes messages flagged by OpenAI. To use another service, replace this function with its moderation check.
If you're using AI moderation, try messages that your chosen policy should accept and reject, and check the service's results alongside what stays in the chat.