> 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/chat-api-v2-legacy.md). # Chat API v2 (Legacy) > **Legacy version** > > This page documents the legacy `v2` Chat API endpoint. Existing integrations can continue using this version, but new integrations should use `v3`. > > See the current version: [Chat API v3](/api-docs-chat/standard-package/chat-api-v3.md) \[ Base URL: `api.ggwp.com`] `POST` /chat/v2/message ## **Description** This API endpoint will process an input message, session id, and user id, along with a list of configurable options on toxicity filtering strengths, and return information at 4 levels: * **Message Details** - indicators for the presence and severity of toxic content, as well as different variations of the input message removing toxicity. * **Player Details** - attributes to describe the behavior of that particular user up until that point in the conversation. This includes the prior list of incident types detected, the player mood, reputation score, and current status. * **Conversation Summary** - metrics that explain all prior activity in that particular session. These include session duration, volume of messages and participants, conversation mood and total incidents detected, along with the types and severities. * **Recommendations** - information about the penalties imposed upon that particular user due to a history or recent series of toxic behaviors. This includes the penalty itself, the trigger message and time, and the duration of the penalty. The `recommended_message` field will return an empty string while a penalty is in place. This part of the API output will provide the following penalties: * Session-mute: the user will be muted for the remaining duration of the session/match. * Mute: the user will be muted across all sessions/matches for a specific duration of time. ## **Headers** *Note: this is not necessary if the configuration settings are shared with GGWP separately* The following are a list of configurable options: * **violence**: Flag language that encourages, glorifies, or threatens physical harm or destruction towards individuals or groups. This includes threats, death wishes, and discussions of violent acts. Supported filter strength values are: * off: This filter is turned off * low: Filters out extreme and graphic violent references only * Examples: "I hope you get cancer", "u deserve to die", "i'll kill your parents", "they should be put in a gas chamber" * medium: In addition to the instances captured above, this will censor mentions to other violent acts not suitable for teenage or kid audiences * Examples: "you got raped", "are u a molester?" * high: In addition to the instances captured above, this will also filter out mild violent references * Examples: "let's lynch them", "that team got slaughtered", "homicide party" * **sexual\_content**: Flag language containing explicit sexual comments, innuendos, or references that are inappropriate or offensive. This includes depictions of nudity, mentions to sexual acts, or sexually suggestive language. Supported filter strength values are: * off: This filter is turned off * low: Filters out extreme comments with references to sexual violence * Examples: "I'm going to rape you", "rapist" * medium: In addition to the instances captured above, this will censor other mentions to sexual acts and any moderately graphic sexual language * Examples: "show me your dick", "you are my sex slave", "suck my ass", "love a good blow job" * high: In addition to the instances captured above, this will also filter out mild sexual references seen as inappropriate for children * Examples: "boobs", "cock", "porn", "anal", "virgin" * **verbal\_abuse**: Flag messages that contain hostile, insulting, or demeaning language directed at an individual or group. This includes personal attacks, insults, and derogatory remarks. Supported filter strength values are: * off: This filter is turned off * low: Filters out highly offensive and insulting terms only * Examples: "fuktard get out of here", "you are fucking cancer" * medium: In addition to the instances captured above, this will censor other forms of abusive language or directed insults * Examples: "fuck you", "bastard", "dumbass", "assmonkey" * high: In addition to the instances captured above, this will also filter out mildly offensive terms, and is most appropriate for younger audiences * Examples: "u dummy", "idiot", "incel", "braindead" * **identity\_hate**: Flag messages that use discriminatory language towards a person or group based on their religion, ethnicity, nationality, race, gender, sexual orientation or other identity factors. This includes slurs, hateful comments or terms commonly associated with specific identity groups in a negative or derogatory way. Supported filter strength values are: * off: This filter is turned off * low: Filters out extreme hateful slurs only * Examples: "nigger", "faggot", "cunt", "retard", "chink" * medium: In addition to the instances captured above, this will censor other forms of hateful biases commonly associated to specific identity groups * Examples: "you're such a pussy", "look at those whores", "tranny", "he's white trash" * high: In addition to the instances captured above, this will also filter out identity terms that are frequently associated with more subtle biases towards a specific identity group * Examples: "that's so gay", "no homo", "queer vibes", "all nazis" * **profanity**: Flag messages that use obscene, vulgar or inappropriate language, or swear words. Supported filter strength values are: * off: This filter is turned off * medium: Filters out more obscene forms of profanity and offensive swear words * Examples: "fuck off", "u should go to hell", "assholes", "stfu loser" * high: In addition to the instances captured above, this will also filter out mild profanity * Examples: "oh shit", "god dammit", "piss off", "noobs" * **link\_sharing**: Flag messages that contain external links to prevent players from sharing inappropriate websites, ads, scams, or other potentially harmful content. Supported filter strength values are: * off: This filter is turned off * medium: Filters out URLs known to be associated with common inappropriate or mature content (e.g. sexual content; gambling and other illegal activity; likely phishing attacks) * high: Filters out all URLs * **drugs**: Flag references to illegal substances, drug use, or drug culture that are inappropriate for the gaming environment. This includes discussions, endorsements, or depictions of drug use. Supported filter values are: * off: This filter is turned off * on: This filter is turned on and will block all drug references * Examples: "drugs for all", "u have to try cocaine", "alcoholic", "meth addict" * **spam**: Flag repetitive or excessive messages that disrupt the chat or gaming experience for others. Supported filter strength values are: * off: This filter is turned off * on: This filter is turned on * **self\_harm**: Flag any content that encourages, glorifies, or suggests self-injury, suicide, or other forms of self-destructive behavior. Supported filter values are: * off: This filter is turned off * on: This filter is turned on and will block promoting harmful behaviors * Examples: "go kill yourself", "cut your throat", "shoot urself plz", "uninstall ur life" * **pii**: Flag messages that contain personally identifiable information (PII). This includes bank numbers, credit cards, email addresses, phone numbers, and physical addresses. Supported filter strength values are: * off: This filter is turned off * medium: Default value that filters out content that strongly appears to contain PII based on recognized patterns and context * *Legacy Alias*: The value `on` is supported and functions identically to `medium` * high: Filters out all content that matches common PII formats, regardless of confidence level * **solicitation**: Flag messages that attempt to obtain another player’s low-risk personal information (e.g., name, phone number), lure them off-platform, or extract real-world value (e.g., money, digital assets) through direct or suspicious requests. Supported filter values are: * off: This filter is turned off * on: This filter is turned on and will block the all messages that are flagged as solicitation * **scam**: Flag messages that contain fraudulent schemes aiming to steal accounts, in-game/real-world assets, or high-risk personal information (e.g., social security number, credit card information, physical address) through deceptive, manipulative, or dishonest tactics. Supported filter values are: * off: This filter is turned off * on: This filter is turned on and will block the all messages that are flagged as scam * **minor\_safety**: Flag messages that contain language that may place minors at risk by indicating grooming behavior, predatory intent, sexualization of minors, or attempts to exploit, manipulate, or endanger children. Supported filter values are: * off: This filter is turned off * low: Filters out any sexual content and violent content involving minors * Examples: "fuck your little sister", "touch children", "minor can consent to sex", "pedo is normal", "assault a 10 year old" * medium: In addition to the instances captured above, this will censor any language suggesting grooming behavior and inappropriate emotional trust-building with a presumed minor * Examples: "you are mature for your age", "do not tell your parents about me", "I feel closer to you than people my own age" * high: In addition to the instances captured above, this will censor any language that raises potential minor safety concerns through personal questions, secrecy, or boundary-testing behavior * Examples: "are you below 17?", "How old are you", "are your parents home?", "this stays between us" * **age\_concern**: Flags messages where a user explicitly or implicitly indicates their age. This category is informational and supports age-aware safety controls rather than harmful-intent detection. Supported filter values are: * off: This filter is turned off * low: Filters out any indications that a user is under 13 * Examples: "I'm 10", "I'm 12 years old", "I'm in elementary school", "I'm a kid" * medium: Filters out any indications that a user is under 18, including the examples above * Examples: "I'm 15", "I'm 17", "I'm in high school", "I'm a minor" * high: Filters out any indications that a user is under 21, including the examples above * Examples: "I'm 19", "I'm not 21 yet", "I can't legally drink", "I'm 20" Sample json and base64 encoded variable to pass: {% code overflow="wrap" %} ```bash $ cat config.json { "violence": "off", "sexual_content": "low", "verbal_abuse": "medium", "identity_hate": "medium", "profanity": "high", "link_sharing": "high", "drugs": "off", "spam": "on", "self_harm": "on", "pii": "off", "solicitation": "off", "scam": "off", "minor_safety": "low" } $ base64 config.json ewogCSJ2aW9sZW5jZSI6ICJvZmYiLAoJInNleHVhbF9jb250ZW50IjogImxvdyIsCgkidmVyYmFsX2FidXNlIjogIm1lZGl1bSIsCgkiaWRlbnRpdHlfaGF0ZSI6ICJtZWRpdW0iLAoJInByb2Zhbml0eSI6ICJoaWdoIiwKCSJsaW5rX3NoYXJpbmciOiAiaGlnaCIsCgkiZHJ1Z3MiOiAib2ZmIiwKCSJzcGFtIjogIm9uIiwKCSJzZWxmX2hhcm0iOiAib24iLAoJInBpaSI6ICJvZmYiLCAKCSJzb2xpY2l0YXRpb24iOiAib2ZmIiwKCSJzY2FtIjogIm9mZiIsCgkibWlub3Jfc2FmZXR5IjogImxvdyIKfQ== $curl -H "x-api-config:ewogCSJ2aW9sZW5jZSI6ICJvZmYiLAoJInNleHVhbF9jb250ZW50IjogImxvdyIsCgkidmVyYmFsX2FidXNlIjogIm1lZGl1bSIsCgkiaWRlbnRpdHlfaGF0ZSI6ICJtZWRpdW0iLAoJInByb2Zhbml0eSI6ICJoaWdoIiwKCSJsaW5rX3NoYXJpbmciOiAiaGlnaCIsCgkiZHJ1Z3MiOiAib2ZmIiwKCSJzcGFtIjogIm9uIiwKCSJzZWxmX2hhcm0iOiAib24iLAoJInBpaSI6ICJvZmYiLCAKCSJzb2xpY2l0YXRpb24iOiAib2ZmIiwKCSJzY2FtIjogIm9mZiIsCgkibWlub3Jfc2FmZXR5IjogImxvdyIKfQ==" -H "x-api-key:" -XPOST https://api.ggwp.com/chat/v2/message -d "{"session_id": "match_7765", "message": "fucking retards everywhere", "user_id": "user989", "username": "nlxdz", "timestamp": "2022-06-02 16:49:02"}" ``` {% endcode %} The following are the default configurations if the `x-api-config` headers are NOT passed: ```json { "violence": "high", "sexual_content": "high", "verbal_abuse": "high", "identity_hate": "high", "profanity": "high", "link_sharing": "high", "drugs": "on", "spam": "on", "self_harm": "on", "pii": "medium", "solicitation": "off", "scam": "off", "minor_safety": "low", "age_concern": "off" } ``` ## **Parameters** `body`: Dictionary containing the following fields:\ (*Needs to be in utf-8 encoding)* * **session\_id:** Unique identifier for the conversation channel. For gameplay messages, this could identify a conversation that unfolds over a single match. On forums or message boards, this could represent a distinct thread or discussion. If your platform contains various channel types (eg: lobby, match, direct message, etc.), we recommend that you include this information in the session\_id to enable further analysis by conversation type. This is the suggested format: ```json session_id = "channelType_numericID" ``` * **message:** Message sent by a user during the conversation. Cannot exceed 1,000 characters. * **user\_id:** Unique identifier for a player or user who sent the message. * (OPTIONAL) **username**: String with the friendly display name picked by the user. * (OPTIONAL) **timestamp**: Time the message took place in YYYY-MM-DD HH:MM:SS.SSS or YYYY-MM-DD HH:MM:SS format, in UTC. If not added, then server side UTC timestamp is added in its place. * (OPTIONAL) **language**: Language of the message to be processed. If omitted, the API will attempt to detect the language from the message content and prior user history. Accepts standard English language names (eg: `"english"` or `"spanish"`), and ISO 639-1 two-letter language codes (eg: `"en"` or `"es"`). Full locale tags such as `"en-US"`, `"en-GB"`, `"pt-BR"`, and `"es-MX"` are not currently supported; send `"en"`, `"pt"`, or `"es"` instead. * (OPTIONAL) **message\_index**: String field to track the message sent. Will be included in the output under `message_details` if passed. * (OPTIONAL) **message\_url**: String field to track the url tagged to the message. Only http or https schemes are valid. Will be visible in the dashboard if valid and passed. * (OPTIONAL) **metadata**: Dict field to track any metadata associated with the message. Must be under 5KB. Only permitted keys and corresponding types are valid. Supported keys: * channel (string) - communication space that the message is passed to. E.g. dm, party, guild, local * participants (array\) - the user\_ids participating in the channel * map (string) - identifier or name of the world, level, or environment where the message originates * map\_version (string) - version identifier of the map, used to track changes in layout, etc. * zone (string) - subsection or named region within a map used for finer-grained location context * coordinates (object) - spatial position within the map or zone * x (float) - position along the X-axis * y (float) - position along the Y-axis * z (float) - position along the Z-axis Example: ```json { "metadata": { "channel": "dm", "participants": ["user989", "user990"], "map":"golden_wasteland", "map_version":"2026.03.1", "zone":"cacti_forest", "coordinates":{ "x":123.45, "y":67.89, "z":-10.25 } } } ``` Note: Additional metadata keys can be supported. Please work with your customer representative to define the specific keys that will be applicable to your platform. Example: ```json { "session_id": "match_7765", "message": "fucking retards everywhere", "user_id": "user989", "username": "nlxdz", "timestamp": "2022-06-02 16:49:02" } ``` Sample call: ```bash curl --request POST 'https://api.ggwp.com/chat/v2/message' \ --header 'x-api-key: api_key' \ --header 'Content-Type: application/json' \ --data-raw '{ "session_id": "match_7765", "message": "fucking retards everywhere", "user_id": "user989", "username": "nlxdz", "timestamp": "2022-06-02 16:49:02" }' ``` ## **Output** * 200 response - successful operation Dictionary containing the following fields: * **message\_details**: details pertaining to the message passed in the payload * message\_details.message\_id: Unique identifier assigned to the message. * message\_details.original\_message: The raw message sent by the user. * message\_details.flag: Indicates whether the message was flagged. * message\_details.severity: Severity of the toxicity (none, low, medium, high). * message\_details.filtered\_message: Version of the message with flagged terms filtered. * For space-delimited languages (e.g., English), entire words are filtered. E.g. `You are a shithead` --> `You are a *****` * For languages without explicit word boundaries (e.g., Korean, Japanese, Chinese), only the detected term itself is filtered." E.g. `좆까고 있네`--> `*****고 있네` * message\_details.replaced\_message: Safe or humorous alternative generated to replace the original message. * message\_details.recommended\_message: Suggested version of the message to be passed to the client. For active users, this value defaults to `filtered_message`. For muted users, the `recommended_message` will be an empty string. * message\_details.language: Detected language of the message. * message\_details.violence: true if the message contains violence. * message\_details.verbal\_abuse: true if the message contains verbal abuse. * message\_details.profanity: true if the message contains profanity. * message\_details.sexual\_content: true if the message contains sexual content. * message\_details.identity\_hate: true if the message contains identity hate. * message\_details.drugs: true if the message contains drug references. * message\_details.self\_harm: true if the message contains self harm. * message\_details.custom: true if the message contains custom blocklist terms. * message\_details.spam: true if the message contains spam. * message\_details.link: true if the message contains external links. * message\_details.pii: true if the message contains personally identifiable information. * **player\_details**: Dictionary containing details pertaining to the `user_id` of the payload within the `session_id` * player\_details.user\_id: Unique identifier for the user. * player\_details.username: Display name of the user. * player\_details.num\_messages: Total number of messages sent. * player\_details.num\_incidents: Number of incidents. * player\_details.cumulative\_mood: Overall sentiment for the user's messages. * player\_details.min\_mood: Lowest sentiment observed for the user’s messages. * player\_details.max\_mood: Highest sentiment observed for the user’s messages. * player\_details.incident\_types\_detected: List of incident types associated with the user. * player\_details.incidents\_by\_severity: Breakdown of incidents grouped by severity level. * player\_details.reputation\_score: Overall user reputation score derived from behavior history. * player\_details.languages: Languages detected from the user’s messages. * player\_details.user\_status: Current moderation state of the user (e.g., active, muted). * player\_details.user\_status.status: Specific moderation action applied (muted, etc.). * player\_details.user\_status.expiry\_at: Time when the moderation action expires. * **conversation\_summary**: Dictionary containing details pertaining to the `session_id` of the payload * conversation\_summary.start\_time: Timestamp when the conversation session began. * conversation\_summary.session\_duration: Total duration of the conversation (in seconds). * conversation\_summary.num\_messages: Total number of messages in the conversation. * conversation\_summary.num\_participants: Number of users in the conversation. * conversation\_summary.num\_incidents: Total count of incidents. * conversation\_summary.conversation\_mood: Overall sentiment for the entire conversation. * conversation\_summary.incident\_types\_detected: List of incident types found across the conversation. * conversation\_summary.incidents\_by\_severity: Breakdown of incidents grouped by severity level. * **recommendations**: Dictionary containing the recommended action to perform on the `user_id` * recommendations.\.action: Suggested moderation action (e.g., mute). * recommendations.\.trigger\_message: Offending message that triggered the recommendation. * recommendations.\.trigger\_time: Timestamp of the triggering message. * recommendations.\.duration: Length of time (in seconds) the action should remain in effect. Sample Output: ```json { "message_details": { "message_id": "20220602164902.482311-946bb8a9-0766-4c31-995a-d910da8531e5", "original_message": "fucking retards everywhere", "flag": true, "severity": "medium", "filtered_message": "***** ***** everywhere", "replaced_message": "Wait... you're supposed to be having fun?", "recommended_message": "", "language": "english", "violence": false, "verbal_abuse": true, "profanity": true, "sexual_content": false, "identity_hate": true, "drugs": false, "self_harm": false, "custom": false, "spam": false, "link": false, "pii": false, "solicitation": false, "scam": false, "minor_safety": false, "age_concern": false }, "player_details": { "user_id": "user989", "username": "nlxdz", "num_messages": 11, "num_incidents": 6, "cumulative_mood": 0.748, "min_mood": 0.0, "max_mood": 0.8615, "incident_types_detected": [ "verbally_abusive_language", "profanity", "identity_hate_language" ], "incidents_by_severity": { "high": 2, "medium": 3, "low": 1 }, "reputation_score": 245, "languages": [ "english" ], "user_status": { "status": "muted", "expiry_at": "2022-06-03 16:49:00" } }, "conversation_summary": { "start_time": "2022-05-27 16:53:03", "session_duration": 59, "num_messages": 46, "num_participants": 3, "num_incidents": 16, "conversation_mood": 0.9816, "incident_types_detected": [ "verbally_abusive_language", "profanity", "identity_hate_language", "sexual_harassment" ], "incidents_by_severity": { "high": 4, "medium": 6, "low": 6 } }, "recommendations": { "user989": [ { "action": "mute", "trigger_message": "dumb ass faggot", "trigger_time": "2022-06-02 16:49:00", "duration": 86400 } ] } } ``` * 400 * Invalid or malformed request. Possible causes: * Invalid JSON Input * Invalid headers, including metadata exceeds 5 KB or contains disallowed keys * Invalid `x-api-config`, or one that contains disallowed keys * Missing required fields: `user_id`, `session_id`, `message` * Invalid Input format: Invalid timestamp format, exceeding message character limit, etc. * 403 * Invalid or missing API key * 500 * Internal Server Error