Handling Notifications

1. Handling Notifications

The CleanSpeak Moderation Notification system is designed to provide feedback to your system when moderators perform specific actions on content or users. All notifications are sent from CleanSpeak to the notification servers (often referred to as Webhooks) you configure via the Management Interface. These notifications are sent via an HTTP POST using application/json data. This is the same style of API that the CleanSpeak WebService uses to accept requests from your application.

There are four types of notifications that CleanSpeak will send:

  • Content Approvals - when a moderator approves or rejects content from the pre-approval queue

  • User Actions - when a moderator takes an action on a user

  • Content Edits - when a moderator edits a piece of persistent content

  • Content Deletes - when a moderator deletes a piece of persistent content

Each of this notification types are covered in detail below:

2. Content Approvals

The Pre-Approval Queue supports the approval and rejection of content. Moderators login to the CleanSpeak Management Interface and from there can approve and reject content. Once moderators have approved or rejected content, CleanSpeak will send notifications back into your system using the JSON format described below.

2.1. Request

Table 1. Request Body

type [String]

This parameter specifies the type of notification and will always be contentApproval for this type of notification.

approvals [Object]

This object contains the approvals performed by a moderator.

The format of the object is 1-N key-value pairs, the key is the UUID of the content item, the value is the action performed ("approved", "rejected").

moderatorEmail [String]

This parameter specifies the email of the moderator that performed the action that resulted in the notification being sent.

moderatorExternalId [String]

This parameter specifies the external id (if one is configured) of the moderator that performed the action that resulted in the notification being sent.

moderatorId [UUID]

This parameter specifies the id of the moderator that performed the action that resulted in the notification being sent.

Example Request JSON
{
  "type": "contentApproval",
  "approvals": {
    "8207bc26-f048-478d-8945-84f236cb5637": "approved",
    "86d9e3e1-5752-41dc-aa55-2a832728ec33": "approved",
    "a1fca416-5573-4662-a31a-a4ff808c34dd": "rejected",
    "af777ea8-1874-463c-a97c-a1f9e494bee1": "approved",
    "73031050-2016-44fc-b8f6-b97184793587": "approved"
  },
  "moderatorId": "b00916ba-f647-4e9f-b2a6-537f69f89b87",
  "moderatorEmail": "catherine@email.com",
  "moderatorExternalId": "foo-bar-baz"
}

2.2. Response

CleanSpeak expects that the notification request handler (the Webhook you write) will return a 200 status code if the notification was successfully handled or any other status code if it wasn’t. If your notification request handler does not return a 200, CleanSpeak will place the content items back into the pre-approval queue so that they can be moderated again.

3. User Actions

The User Action system provides moderators the capability to perform specific actions on users that generate content. Actions such as ban, mute, and kick are a few examples of actions that moderators can take when, for instance, users are generating inappropriate content. When actions are taken, CleanSpeak will send notifications back into your system.

3.1. Request

Table 2. Request Body

type [String]

This parameter specifies the type of notification and will always be userAction for this type of notification.

applicationIds [Array<UUID>]

This parameter specifies the list of applications that the action is being performed in.

action [String]

This parameter specifies the name of the action that’s occurring.

comment [String]

The comment that the moderator added when taking the action. This value will be an empty string if a comment is not added.

expiry [Integer]

The instant that the action will expire, if the action expires.

key [String]

This parameter specifies the name of the key that’s occurring for the given action if the key exists. null will be returned if the action is time-based.

localizedAction [String]

This parameter specifies the localized name of the action that’s occurring, based on the user’s preferred languages.

localizedDuration [String]

The duration of the action in a human readable format that is localized based on the user’s preferred languages.

localizedKey [String]

This parameter specifies the localized key of the action that’s occurring, based on the user’s preferred languages.

localizedReason [String]

This parameter specifies the localized reason of the action that’s occurring, based on the user’s preferred languages.

moderatorEmail [String]

This parameter specifies the email of the moderator that performed the action that resulted in the notification being sent.

moderatorExternalId [String]

This parameter specifies the external id (if one is configured) of the moderator that performed the action that resulted in the notification being sent.

moderatorId [UUID]

This parameter specifies the id of the moderator that performed the action that resulted in the notification being sent.

notifyUser [Boolean]

This parameter specifies whether the user should be notified or not.

phase [Boolean]

This parameter specifies the phase for the action. It is one of the following:

  • start

  • modify

  • cancel

  • end

When the action is started by a moderator, the phase will be "start". If a moderator changes the duration of the action, the phase will be "modify". If a moderator cancels an action it will be "cancel" or the action expires, the phase will be "end". If the action is key-based, the phase will be "start".

reason [String]

The reason the moderator selected. Reasons are configured in the management interface via System → Moderation Configuration → User Action Reasons. This value will be null when no reasons are selected (or configured).

reasonCode [String]

The reason code the moderator selected. Reasons are configured in the management interface via System → Moderation Configuration → User Action Reasons. This value will be null when no reasons are selected (or configured).

userId [UUID]

This parameter specifies the unique identifier of the user the action is being performed. This ID is equivalent to the ‘contentItem.senderId’ you provide when moderating and storing content.

email [Object]

Email object. See Example POST body below for fields.

Example Request JSON
{
  "type": "userAction",
  "applicationIds": [
    "2a6972a9-d332-458f-9c11-aa0eb74cfefc",
    "a1d7c8d2-be38-4530-8c61-b32245f94f0c",
    "def77957-1818-4fd5-b052-004777acb6fa",
    "96ebce2f-f9c0-44f6-a92f-6f476e08b678",
    "563215b9-b819-4ec5-b983-88174f26e390"
  ],
  "moderatorId": "1219c8e2-c0c2-4efc-9323-6ee9062e9c1f",
  "moderatorExternalId": null,
  "moderatorEmail": "moderator@inversoft.com",
  "action": "Mute",
  "comment": "a comment",
  "expiry": 1408554564119,
  "key": null,
  "localizedAction": "Mute",
  "localizedDuration": "2 days",
  "localizedKey": null,
  "localizedReason": "Misconduct",
  "notifyUser": true,
  "phase": "start",
  "reason": "Misconduct",
  "reasonCode": "123",
  "userId": "32ac49fe-1f7f-40b6-a3a1-02611a10945a",
  "email": {
    "attachments": [],
    "bcc": [],
    "cc": [],
    "from": {
      "address": "no-reply@yourorganization.com",
      "display": "no-reply@yourorganization.com"
    },
    "html": "no-reply@yourorganization.com",
    "replyTo": null,
    "subject": "You've received a Misconduct action",
    "text": ".... insert text here ....",
    "to": [
      {
        "address": "Allan249@example.com",
        "display": null
      }
    ]
  }
}

3.2. Response

CleanSpeak expects that the notification request handler will return a 200 status code if the notification was successfully handled or any other status code if it wasn’t. If your notification request handler does not return a 200, CleanSpeak will assume that the action was not successful and display an error to the moderator.

4. Content Edits

Depending on your Application configuration, persistent content within CleanSpeak can be edited by moderators. When content is edited, CleanSpeak will notify your system so that your system can process the edit appropriately.

4.1. Request

Table 3. Request Body

type [String]

This parameter specifies the type of notification and will always be contentEdit for this type of notification.

applicationId [UUID]

The UUID of the application that owns the content item.

id [UUID]

The UUID of the content item that was edited.

moderatorEmail [String]

This parameter specifies the email of the moderator that performed the edit that resulted in the notification being sent.

moderatorExternalId [String]

This parameter specifies the external id (if one is configured) of the moderator that performed the edit that resulted in the notification being sent.

moderatorId [UUID]

This parameter specifies the id of the moderator that performed the edit that resulted in the notification being sent.

newParts [Array<String>]

The new versions of each content part.

Example Request JSON
{
  "type": "contentEdit",
  "applicationId": "4f0a7e99-f533-4b89-bb4c-eb9ab36c4841",
  "id": "e8e93ee8-fedb-4238-8604-bd631967013c",
  "newParts": [
    "Multiple versions #3 changed"
  ],
  "moderatorId": "b00916ba-f647-4e9f-b2a6-537f69f89b87",
  "moderatorEmail": "catherine@email.com",
  "moderatorExternalId": "foo-bar-baz"
}

4.2. Response

CleanSpeak expects that the notification request handler will return a 200 status code if the notification was successfully handled or any other status code if it wasn’t. If your notification request handler does not return a 200, CleanSpeak will assume that the edit was not successful and display an error to the moderator.

5. Content Deletes

Depending on your Application configuration, persistent content within CleanSpeak can be deleted by moderators. When content is deleted, CleanSpeak will notify your system so that your system can process the delete appropriately.

5.1. Request

Table 4. Request Body

type [String]

This parameter specifies the type of notification and will always be contentDelete for this type of notification.

applicationId [UUID]

The UUID of the application that owns the content item.

id [UUID]

The UUID of the content item that was deleted.

moderatorEmail [String]

This parameter specifies the email of the moderator that performed the delete that resulted in the notification being sent.

moderatorExternalId [String]

This parameter specifies the external id (if one is configured) of the moderator that performed the delete that resulted in the notification being sent.

moderatorId [UUID]

This parameter specifies the id of the moderator that performed the delete that resulted in the notification being sent.

newParts [Array<String>]

The new versions of each content part.

Example Request JSON
{
  "type": "contentDelete",
  "applicationId": "63d797d4-0603-48f7-8fef-5008edc670dd",
  "id": "3f8f66cb-d933-4e5e-a76d-5b3a4d9209cd",
  "moderatorId": "b00916ba-f647-4e9f-b2a6-537f69f89b87",
  "moderatorEmail": "catherine@email.com",
  "moderatorExternalId": "foo-bar-baz"
}

5.2. Response

CleanSpeak expects that the notification request handler will return a 200 status code if the notification was successfully handled or any other status code if it wasn’t. If your notification request handler does not return a 200, CleanSpeak will assume that the edit was not successful and display an error to the moderator.

6. Notification Handler

In order to appropriately handle requests from the CleanSpeak notification system, you must build a simple HTTP request handler that listens for requests from the CleanSpeak Moderation Notification system. Your request handler must be designed to respond to simple HTTP POST requests with a request body containing application/json data as described above.

6.1. Responses

Your notification handler must handle the RESTful request described above and send back an appropriate response. Your notification WebService must send back to CleanSpeak an HTTP response code that indicates whether or not the notification was successfully handled or not. If your WebService handled the notification properly, it must send back an HTTP response status code of 200. If there was any type of error or failure, your WebService must send back an HTTP response status code of 500.

6.2. Configuration

Once your notification handler is complete and listening for notification requests, you must configure your notification handler URL. CleanSpeak refers to notification handlers as Notification Servers and they are configured via the Management Interface under System → Notification Servers menu option. If you have multiple notification servers configured for a single Application, they must all correctly handle the notification for the transaction to succeed.