# Message classification (AI) API

Open Text Shield, the TelecomsXchange SMS classifiers, served from their own host. The threat classifier labels a message as ham, spam or phishing; the category classifier labels what kind of message it is.

## Check message safety

`POST https://ots.telecomsxchange.com/predict`

Reference: https://help.telecomsxchange.com/reference/ai/#check-message-safety

Classifies one SMS text as `ham`, `spam` or `phishing`. The text is normalised first, so full-width, look-alike and leetspeak disguises (for example `paypa1`) are classified as the text they imitate. Returns the label, `probability` (the model's confidence in that label, 0 to 1), `processing_time` (server-side seconds) and `model_info`. Free, and needs no credentials.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `text` | string | json | yes | The message to classify, 1 to 512 characters. Example `Your account has been suspended. Verify now at http://secure-login-check.example`. |
| `model` | string | json | yes | Model to run. Use `ots-mbert`. One of `ots-mbert`. Example `ots-mbert`. |

### Errors

| Message | When |
|---|---|
| `String should have at least 1 character` | `text` is empty (HTTP 422, in `detail[].msg`). |

### Request

```bash
curl -X POST \
  "https://ots.telecomsxchange.com/predict" \
  -H 'Content-Type: application/json' \
  -d '{"text": "Your account has been suspended. Verify now at http://secure-login-check.example", "model": "ots-mbert"}'
```

### Response: Phishing

```json
{
  "label": "phishing",
  "probability": 0.9997455477714539,
  "processing_time": 0.1476691383868456,
  "model_info": {
    "name": "OTS_mBERT",
    "version": "2.9",
    "architecture": "bert-base-multilingual-cased",
    "author": "TelecomsXChange (TCXC)",
    "last_training": "2024-03-20"
  }
}
```

### Response: Ham

```json
{
  "label": "ham",
  "probability": 0.9994045495986938,
  "processing_time": 0.155810184776783,
  "model_info": {
    "name": "OTS_mBERT",
    "version": "2.9",
    "architecture": "bert-base-multilingual-cased",
    "author": "TelecomsXChange (TCXC)",
    "last_training": "2024-03-20"
  }
}
```

## Threat classifier health

`GET https://ots.telecomsxchange.com/health`

Reference: https://help.telecomsxchange.com/reference/ai/#threat-classifier-health

Returns the threat classifier's status, API version and loaded model version. Suitable as a load-balancer health check. Free, and needs no credentials.

### Request

```bash
curl -X GET \
  "https://ots.telecomsxchange.com/health"
```

### Response: Healthy

```json
{
  "status": "healthy",
  "api_version": "2.11.0",
  "version": "2.11.0",
  "model": {
    "name": "OTS_mBERT",
    "version": "2.9",
    "architecture": "bert-base-multilingual-cased"
  },
  "models_loaded": {
    "mbert_multilingual": true
  },
  "timestamp": "2026-10-15T20:22:02.957002+00:00"
}
```

## Classify message category

`POST https://ots.telecomsxchange.com/cc/v1/classify`

Reference: https://help.telecomsxchange.com/reference/ai/#classify-message-category

Sorts one SMS text into a category: `verification` (one-time codes, 2FA and login codes, verification links, "confirm it's you" prompts), `marketing` (promotions, sales, loyalty pushes, launches, re-engagement, referral offers) or `transactional` (order, delivery, payment, booking, balance, reminder and account-event notifications). Returns the `label`, its `confidence`, all three `scores` (they sum to 1) and `ms`, the server-side model time in milliseconds. Free, and needs no credentials.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `text` | string | json | yes | The message to classify, 1 to 2,000 characters. Example `Your verification code is 482913. It expires in 10 minutes.`. |

### Errors

| Message | When |
|---|---|
| `String should have at least 1 character` | `text` is empty (HTTP 422, in `detail[].msg`). |

### Request

```bash
curl -X POST \
  "https://ots.telecomsxchange.com/cc/v1/classify" \
  -H 'Content-Type: application/json' \
  -d '{"text": "Your verification code is 482913. It expires in 10 minutes."}'
```

### Response: Verification

```json
{
  "label": "verification",
  "confidence": 0.9662,
  "scores": {
    "verification": 0.9662,
    "marketing": 0.0162,
    "transactional": 0.0176
  },
  "ms": 16.82
}
```

### Response: Verification (Indonesian)

```json
{
  "label": "verification",
  "confidence": 0.9649,
  "scores": {
    "verification": 0.9649,
    "marketing": 0.0162,
    "transactional": 0.0189
  },
  "ms": 20.97
}
```

## Classify message categories in bulk

`POST https://ots.telecomsxchange.com/cc/v1/classify/batch`

Reference: https://help.telecomsxchange.com/reference/ai/#classify-message-categories-in-bulk

Classifies up to 256 SMS texts in one request. `results` is in the same order as `texts`; each result has the same fields as the single-message call except that its `ms` is null, and the top-level `ms` is the model time for the whole batch. `count` is the number of messages classified. Free, and needs no credentials.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `texts` | array | json | yes | Messages to classify: up to 256 strings, each 1 to 2,000 characters. Example `['50% off everything this weekend', 'Your parcel has been delivered']`. |

### Request

```bash
curl -X POST \
  "https://ots.telecomsxchange.com/cc/v1/classify/batch" \
  -H 'Content-Type: application/json' \
  -d '{"texts": ["50% off everything this weekend", "Your parcel has been delivered"]}'
```

### Response: Two messages

```json
{
  "results": [
    {
      "label": "marketing",
      "confidence": 0.9383,
      "scores": {
        "verification": 0.0276,
        "marketing": 0.9383,
        "transactional": 0.0341
      },
      "ms": null
    },
    {
      "label": "transactional",
      "confidence": 0.9722,
      "scores": {
        "verification": 0.0146,
        "marketing": 0.0132,
        "transactional": 0.9722
      },
      "ms": null
    }
  ],
  "count": 2,
  "ms": 19.15
}
```

## List categories

`GET https://ots.telecomsxchange.com/cc/v1/labels`

Reference: https://help.telecomsxchange.com/reference/ai/#list-categories

Returns the three labels the category classifier can return and the definition of each. Free, and needs no credentials.

### Request

```bash
curl -X GET \
  "https://ots.telecomsxchange.com/cc/v1/labels"
```

### Response: Labels

```json
{
  "labels": [
    "verification",
    "marketing",
    "transactional"
  ],
  "definitions": {
    "verification": "One-time codes, 2FA/login codes, verification links, 'confirm it's you' prompts.",
    "marketing": "Promotions, offers, sales, loyalty pushes, product launches, re-engagement, surveys-for-rewards.",
    "transactional": "Order, delivery, payment, booking, balance, reminder and account-event notifications triggered by something the user did or holds."
  }
}
```

## Category classifier health

`GET https://ots.telecomsxchange.com/cc/health`

Reference: https://help.telecomsxchange.com/reference/ai/#category-classifier-health

Returns the category classifier's status, service and model versions, supported languages and labels, uptime, and whether an API key is required. Suitable as a load-balancer health check. Free, and needs no credentials.

### Request

```bash
curl -X GET \
  "https://ots.telecomsxchange.com/cc/health"
```

### Response: Healthy

```json
{
  "status": "ok",
  "service": "ots-cc",
  "name": "Open Text Shield Category Classifier",
  "version": "0.2.2",
  "model_name": "OTS Category Classifier",
  "model_version": "v8",
  "model_base": "mmBERT small",
  "languages": [
    "en",
    "es",
    "id",
    "… 6 more items"
  ],
  "model": "model_int8.onnx",
  "base": "jhu-clsp/mmBERT-small",
  "labels": [
    "verification",
    "marketing",
    "transactional"
  ],
  "api_key_required": false,
  "uptime_s": 221088.3
}
```