Skip to main content

Moderation Integration

To maintain a safe, respectful, and engaging environment for your users, our platform offers a powerful Moderation Integration system. This system allows you to automatically review, filter, and take action on user-generated messages, images, and videos before they are delivered.

With Moderation Integration, you can define flexible rules, receive real-time updates, and ensure your app meets community guidelines, legal standards, and brand values without manual intervention.

note

If you're using CometChat UI Kits or SDKs, you can skip steps 2 & 3.

Key Components of Moderation Integration​

Step 1: Set Up Moderation Rules

Step 2: Configure a Moderation Webhook

Step 3: Integrate and Test the Moderation API

Setting Up Moderation Rules​

Moderation rules act as filters to ensure that the messages exchanged within your app meet your safety and content guidelines.

How It Works​

  • When a message, image, or video is submitted, it is automatically checked against the moderation rules you’ve configured.
  • These rules can detect offensive language, sensitive content, spam, scams, and more.
  • Based on your settings, content can be:
    • Approved: Delivered to the recipient.
    • Disapproved: Blocked and not delivered.

Benefits​

  • Safety First: Protect your users and brand from harmful or unwanted content.
  • Customizable: Fine-tune moderation rules to suit your app’s unique needs.
  • Seamless User Experience: Moderation happens in real time, keeping communication flowing smoothly.

Creating Moderation Rules​

CometChat provides a set of default moderation rules designed to cover common use cases such as offensive language, spam, and inappropriate content. You can simply enable these default rules to start moderating messages immediately, without any additional setup.

Image

If you have specific requirements, you can also create custom moderation rules tailored to your app’s needs. Rules can be created in two ways:

  1. Using the CometChat Dashboard — A simple, no-code interface for visually creating and managing moderation rules.

    Image

  2. Using the CometChat API — Allows you to programmatically create and manage moderation rules for more advanced or automated workflows. View API Documentation

Configuring a Moderation Webhook​

To automate your moderation flow and receive updates in real time, you can configure a moderation webhook. This allows your system to react instantly when a message or media is moderated.

How It Works​

  • Every time content is moderated, a webhook event is triggered and sent to the URL you specify.
  • Your application can then take action based on the moderation result.

Steps to Configure Your Moderation Webhook​

Setting up your moderation webhook is quick and straightforward. Follow these simple steps to start receiving real-time updates when content is moderated.

Pre-requisites​

  • Your webhook URL must be accessible over HTTPS. This is essential to ensure the security and integrity of data transmission.
  • The URL should be publicly accessible from the internet.
  • Ensure that your endpoint supports the HTTP POST method. Event payloads will be delivered via HTTP POST requests in JSON format.
  • Configure your endpoint to respond immediately to the CometChat server with a 200 OK response.
  • For security, it is recommended to set up Basic Authentication, commonly used for server-to-server communication. This requires configuring a username and password.

Whenever your webhook URL is triggered, the HTTP header will contain:

Authorization: Basic <Base64-encoded-credentials>

Handle Moderation Events​

Ensure your webhook endpoint is ready to process the moderation events. You can find the complete list of events in the Moderation Events section.

The key events your application should handle include:

  • moderation_engine_approved — Triggered when a message is automatically approved.
  • moderation_engine_blocked — Triggered when a message is automatically blocked.
  • moderation_manual_approved — Triggered when a previously blocked message is manually approved by a moderator.

To start receiving these events, make sure to enable these three webhooks from the CometChat Dashboard.

To receive these events, you'll need to enable the relevant webhooks from the CometChat Dashboard. Follow this path:

Application → Webhooks → Create Webhook → Triggers → Moderation

Be sure to select all three moderation triggers to ensure your app receives the necessary event notifications.

Image

Integrating and Testing the Moderation API​

Once your moderation rules and webhook are configured, you can integrate the Moderation API into your application to programmatically submit content and receive moderation results.

Steps to Integrate and Test​

  1. Submit Content: Use the API to send messages, images, or videos for moderation.
  2. Check Responses: Verify moderation status in real time.
  3. Handle Outcomes: Apply business logic based on approved, flagged, or disapproved responses.
  4. End-to-End Testing: Test both the API response and webhook delivery to ensure complete coverage.

Once your integration is complete, you can seamlessly use the following APIs to manage and interact with the moderation system efficiently and reliably.

Send message

This endpoint is used to submit a message for moderation before it is delivered to the recipient. The message is scanned against the moderation rules configured for the app.

URL: https://api-explorer.cometchat.com/reference/chat-api-send-message-moderation

Request Body:

{
  "category": "message",
  "type": "text",
  "data": {
    "text": "Hi new user"
  },
  "sender": "cometchat-uid-2",
  "receiver": "cometchat-uid-1",
  "receiverType": "user",
  "sentAt": 1750335220
}

List messages

This endpoint retrieves a list of messages submitted for moderation, along with the current moderation status of each message as determined by the rules configured for your application.

URL: https://api-explorer.cometchat.com/reference/chat-api-list-message-moderation/

Get message

This endpoint retrieves the details of a message submitted for moderation, including its current moderation status as determined by the rules configured for your app.

URL: https://api-explorer.cometchat.com/reference/chat-api-get-message-moderation/

Update message

This endpoint is used to edit an existing message. The moderation status is re-evaluated based on the rules configured for your application.

URL: https://api-explorer.cometchat.com/reference/chat-api-update-message-moderation/

Delete message

This endpoint deletes a previously submitted message along with its associated moderation data, in accordance with the rules configured for your application.

URL: https://api-explorer.cometchat.com/reference/chat-api-delete-message-moderation/

Approve message

This endpoint is used to approve a previously blocked message, allowing it to be delivered to the recipient.

URL: https://api-explorer.cometchat.com/reference/chat-api-approve-moderation-blocked-messages/

EndpointPurpose
Send Message for Moderation
POST /moderation/messages		Submits a new message for moderation. Triggers the moderation engine, emits a webhook, and makes the message accessible via the Get Message endpoint.
Edit Message for Moderation
PUT /moderation/messages/:id		Re-evaluates an edited message. If approved, the updates are accepted; if blocked, the message is withheld.
Get Message Moderation Status
GET /moderation/messages/:id		Retrieves the moderation status, rule metadata, and action history of a message.
List Messages for Moderation
GET /moderation/messages		Lists all moderated messages with optional filters such as category, type, status, and receiver UID/GUID.
Delete Message from Moderation
DELETE /moderation/messages/:id		Deletes a moderated message.

Summary​

By combining:

  • Well-defined moderation rules
  • Automated webhooks
  • Robust API integration

You can build a safe, scalable, and user-friendly content moderation system tailored to your app’s values and audience expectations.