CleanSpeak Documentation

Filtering Content

1. Filtering Content

After you complete the Setup Wizard steps, you should have an API key and Application Id that you will use to call the CleanSpeak WebService APIs.

This API key will be sent in via the Authorization header, see API Authentication.

CleanSpeak provides two filter APIs, Moderate Content and Filter Content. Both APIs use the same CleanSpeak filter, they are different only by their intended use cases.

The Moderate Content API allows you to configure rules to indicate if the filter should allow or reject the content. This is helpful when you have more than one content source, such as chat, forum, and usernames. This configuration will enable you to tune the filter results based on the content source.

The Filter Content API allows for some configuration but is provided on each HTTP request. The API response is intended to be consumed and parsed based upon your business logic to decide if the content should be allowed or rejected based upon match severity, locale, etc.

It is recommended to begin integration using the Moderate Content API. Review the sections below for examples of sending the same content to each API.

1.1. Using the Moderate Content API

You will need to authenticate this API request using an API Key, see API Authentication.

In the following example, we are sending a single message called a content part of type text to be filtered based upon the rules defined by the CleanSpeak Application with Id f81d4fae-7dec-11d0-a765-00a0c91e6bf6. See the Moderate Content API for additional details.

URI

POST /content/item/moderate

Example Moderate Request
{
  "content": {
    "applicationId": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
    "createInstant": 1625691361999,
    "parts": [
      {
        "content": "We like Colorado Beer.",
        "type": "text"
      }
    ],
    "senderId": "f6d3df91-ed4b-48ad-810f-05a367d328c2"
  }
}

The API will respond with a status code of 200 and a JSON response body.

Beer is an alcohol reference, and in our example we have configured our filter rules to reject matches with the Alcohol-Drug tag. This contentAction value of reject will indicate to the caller the content should be rejected.

Example Moderate Response
{
  "content": {
    "id": "02709cf1-8edc-42f0-a5a4-aec2c97b5099"
  },
  "contentAction": "reject",
  "stored": true
}

You can consult the API documentation for this endpoint for more information on the request and response JSON formats.

1.2. Using the Filter Content API

CleanSpeak also has another API for filtering content. This API only takes input via the API and will returns all of the matches in the JSON response body.

This API may requires a more complex integration because your application code must parse the response and determine what action to take based up the filter matches. Unless you have a particular requirement for this API, the Moderate Content Endpoint should be preferred.

The following is an example cURL request to the Filter endpoint. However, your API Key will be different. Your URL might also be different if you are running CleanSpeak on an external server. See the API documentation for Filter Content for additional details.

URI

POST /content/item/filter

Example Filter Request
{
  "content": "We like Colorado Beer."
}

The API will respond with a status code of 200 and a JSON response body.

Beer is an alcohol reference, and you will see this match returned with the tag Alcohol-Drug tag. When using this API it is up to your application code to parse this response and decide if a medium severity alcohol reference should be allowed or reject.

Example Filter Response
{
  "matches": [
    {
      "length": 4,
      "locale": "en",
      "matched": "beer",
      "quality": 1.0,
      "root": "beer",
      "severity": "medium",
      "start": 17,
      "tags": [
        "Alcohol-Drug"
      ],
      "type": "blacklist"
    }
  ],
  "replacement": "We like Colorado ****."
}