> For the complete documentation index, see [llms.txt](https://docs.ggwp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ggwp.com/api-docs-chat/standard-package/migrating-from-chat-api-v2-to-v3.md).

# Migrating from Chat API v2 to v3

Chat API v3 is the current recommended version for new integrations. Existing integrations using v2 can continue using the legacy endpoint, but we recommend migrating to v3 to use the latest category taxonomy, severity model, and response structure.

### Endpoint change

Update your request URL from the v2 endpoint to the v3 endpoint.

| Version    | Endpoint                |
| ---------- | ----------------------- |
| v2 Legacy  | `POST /chat/v2/message` |
| v3 Current | `POST /chat/v3/message` |

The base URL remains the same:

```
https://api.ggwp.com
```

### Request body compatibility

The core request body is unchanged. You can continue sending the same required fields:

```json
{
  "session_id": "match_7765",
  "message": "fucking retards everywhere",
  "user_id": "user989"
}
```

The following optional fields are also still supported:

* `username`
* `timestamp`
* `language`
* `message_index`
* `message_url`
* `metadata`

### Configuration changes

If you pass per-request configuration using the `x-api-config` header, update your configuration keys to the v3 category names.

| v2 config key   | v3 config key          |
| --------------- | ---------------------- |
| `identity_hate` | `identity_harm`        |
| `profanity`     | `offensive_language`   |
| `link_sharing`  | `links`                |
| `self_harm`     | `self_harm_incitement` |
| `age_concern`   | `age_disclosure`       |

v3 also introduces additional categories, including:

* `extremism`
* `gameplay_criticism`
* `real_threat`
* `sexual_harassment`
* `sexual_violence`

In v3, most categories support the same sensitivity scale:

```
off, low, medium, high
```

Sensitivity controls which severity levels are blocked:

<table><thead><tr><th width="202.21875">Sensitivity</th><th>Behavior</th></tr></thead><tbody><tr><td><code>off</code></td><td>Do not filter the category</td></tr><tr><td><code>low</code></td><td>Filter high-severity content only</td></tr><tr><td><code>medium</code></td><td>Filter medium- and high-severity content</td></tr><tr><td><code>high</code></td><td>Filter low-, medium-, and high-severity content</td></tr></tbody></table>

> Note: v3 uses severity-based sensitivity more consistently across categories. Some v2 categories that previously used `on` / `off`, such as `drugs`, `spam`, `scam`, and `solicitation`, now use `off`, `low`, `medium`, or `high`.

### Default configuration changes

If you do not pass the `x-api-config` header, or if your account does not have custom onboarding-time settings configured, v3 may apply different default filtering behavior than v2.

In v2, some categories were disabled or set to lower sensitivity by default, including:

```json
{
  "solicitation": "off",
  "scam": "off",
  "age_concern": "off",
  "minor_safety": "low",
  "pii": "medium"
}
```

In v3, the default configuration shown in these docs sets all supported categories to `high` sensitivity:

```json
{
  "age_disclosure": "high",
  "drugs": "high",
  "extremism": "high",
  "gameplay_criticism": "high",
  "identity_harm": "high",
  "links": "high",
  "minor_safety": "high",
  "offensive_language": "high",
  "pii": "high",
  "real_threat": "high",
  "scam": "high",
  "self_harm_incitement": "high",
  "sexual_content": "high",
  "sexual_harassment": "high",
  "sexual_violence": "high",
  "solicitation": "high",
  "spam": "high",
  "verbal_abuse": "high",
  "violence": "high"
}
```

This means that migrating from v2 to v3 without reviewing your configuration may result in stricter filtering behavior.

Before switching production traffic to v3, review your current v2 configuration and either:

1. Configure equivalent settings in your GGWP account, or
2. Pass an explicit `x-api-config` header with your desired v3 sensitivity settings.

If you currently rely on v2 defaults, we recommend testing v3 with representative production-like traffic before rollout.

### Response changes

The largest migration change is in `message_details`.

In v2, category detections were returned as individual boolean fields:

```json
{
  "violence": false,
  "verbal_abuse": true,
  "profanity": true,
  "identity_hate": true
}
```

In v3, category detections are returned in a structured `flagged_categories` array:

```json
{
  "flagged_categories": [
    {
      "category": "identity_harm",
      "category_severity": "medium"
    },
    {
      "category": "offensive_language",
      "category_severity": "high"
    }
  ]
}
```

If your integration currently checks v2 boolean fields, update it to read from `message_details.flagged_categories`.

### Field mapping

| v2 field                                        | v3 field                                                                  | Notes                                        |
| ----------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------- |
| `message_details.identity_hate`                 | `message_details.flagged_categories[].category == "identity_harm"`        | Category renamed                             |
| `message_details.profanity`                     | `message_details.flagged_categories[].category == "offensive_language"`   | Category renamed                             |
| `message_details.link`                          | `message_details.flagged_categories[].category == "links"`                | Category renamed                             |
| `message_details.self_harm`                     | `message_details.flagged_categories[].category == "self_harm_incitement"` | Category renamed                             |
| `message_details.age_concern`                   | `message_details.flagged_categories[].category == "age_disclosure"`       | Category renamed                             |
| `message_details.custom`                        | `message_details.custom_flag`                                             | Field renamed                                |
| `message_details.replaced_message`              | Not returned in v3                                                        | Remove dependency if used                    |
| Individual category booleans                    | `flagged_categories`                                                      | v3 returns a list of category detections     |
| Category-level severity unavailable per boolean | `flagged_categories[].category_severity`                                  | v3 includes category-specific severity       |
| No top-level confidence field                   | `message_details.confidence`                                              | v3 adds confidence for the overall detection |

### Severity changes

v2 message severity used:

```
none, low, medium, high
```

v3 supports a broader message-level severity scale:

```
none, very_low, low, medium, high, very_high, custom
```

If your application maps severity values to internal actions, update your parsing logic to handle the new values.

### Player and conversation summary changes

The main structure remains the same:

* `player_details`
* `conversation_summary`
* `recommendations`

However, v3 simplifies some aggregate fields. If your integration depends on the following v2 fields, verify whether they are still needed in your workflow:

* `player_details.incident_types_detected`
* `player_details.incidents_by_severity`
* `conversation_summary.incident_types_detected`
* `conversation_summary.incidents_by_severity`

### Recommended migration steps

1. **Update the endpoint**\
   Change requests from `/chat/v2/message` to `/chat/v3/message`.
2. **Review default configuration behavior**\
   v3 defaults may be stricter than v2 defaults. If you currently rely on v2 default settings, configure equivalent v3 settings before rollout.
3. **Update configuration keys**\
   Rename v2 category keys to their v3 equivalents and add any new v3 categories you want to configure.
4. **Update response parsing**\
   Replace checks against individual category booleans with checks against `message_details.flagged_categories`.
5. **Update severity handling**\
   Make sure your application supports the expanded v3 severity values.
6. **Test with representative traffic**\
   Compare v2 and v3 outputs on safe, borderline, and violating messages before switching production traffic.
7. **Roll out gradually**\
   Start with staging or limited production traffic, then fully migrate once downstream parsing and moderation behavior are validated.

```
```