Docs/add anti fraud page

docs.json

@@ -73,7 +73,7 @@
               },
               {
                 "group": "Segurança",
-                "pages": ["security/introduction", "security/ip-block", "security/twofactor", "security/client-token"]
+                "pages": ["security/introduction", "security/ip-block", "security/twofactor", "security/client-token", "security/fraud-protection"]
               },
               {
                 "group": "MCP Server",
@@ -118,7 +118,7 @@
               {
                 "group": "API Reference",
                 "pages": [
-                  { "group": "Instance",          "pages": ["instance/introduction", "instance/update-auto-read-message", "instance/update-auto-read-status", "instance/profile-picture", "instance/profile-name", "instance/profile-description", "instance/update-call-reject-auto", "instance/update-call-reject-message", "instance/qrcode", "instance/qr-code", "instance/qr-code-image", "instance/passkey-prologue", "instance/reset-passkey-challenge", "instance/phone-code", "instance/extension-token", "instance/restart", "instance/disconnect", "instance/status", "instance/device", "instance/rename-instance", "instance/me"] },
+                  { "group": "Instance",          "pages": ["instance/introduction", "instance/update-auto-read-message", "instance/update-auto-read-status", "instance/profile-picture", "instance/profile-name", "instance/profile-description", "instance/update-call-reject-auto", "instance/update-call-reject-message", "instance/qrcode", "instance/qr-code", "instance/qr-code-image", "instance/passkey-prologue", "instance/reset-passkey-challenge", "instance/phone-code", "instance/extension-token", "instance/restart", "instance/disconnect", "instance/status", "instance/device", "instance/rename-instance", "instance/me",  "instance/update-announcement-guard"] },
                   { "group": "Mobile",            "pages": ["mobile/introduction", "mobile/registration-available", "mobile/request-code", "mobile/captcha-confirm", "mobile/confirm-code", "mobile/device-transfer-confirmed", "mobile/request-unbanning", "mobile/confirm-security-code", "mobile/forgot-security-code", "mobile/get-account-email", "mobile/set-account-email", "mobile/verify-account-email", "mobile/get-has-security-code", "mobile/set-security-code", "mobile/remove-account-email", "mobile/remove-security-code"] },
                   { "group": "Messages",          "pages": ["message/introduction", "message/send-text", "message/forward-message", "message/send-message-reaction", "message/send-remove-reaction", "message/send-message-image", "message/send-message-sticker", "message/send-message-gif", "message/send-message-audio", "message/send-message-video", "message/send-message-ptv", "message/send-message-document", "message/send-message-link", "message/send-message-location", "message/send-message-product", "message/send-message-catalog", "message/send-message-contact", "message/send-message-multiple-contacts", "message/send-button-actions", "message/send-button-list", "message/send-button-list-image", "message/send-button-list-video", "message/send-option-list", "message/send-button-otp", "message/send-button-pix", "message/send-carousel", "message/delete-message", "message/read-message", "message/reply-message", "message/send-poll", "message/send-poll-vote", "message/send-message-order", "message/send-order-status-update", "message/send-order-payment-update", "message/send-pin-message", "message/send-newsletter-admin-invite", "message/send-event", "message/send-edit-event", "message/send-event-response", "message/reply-button", "message/reply-template-button"]},
                   { "group": "Privacy",           "pages": ["privacy/introduction", "privacy/get-disallowed-contacts", "privacy/set-last-seen", "privacy/set-photo-visualization", "privacy/set-privacy-description", "privacy/set-group-add-permission", "privacy/set-privacy-online", "privacy/set-read-receipts", "privacy/set-messages-duration"] },
@@ -167,7 +167,7 @@
               },
               {
                 "group": "Security",
-                "pages": ["en/security/introduction", "en/security/ip-block", "en/security/twofactor", "en/security/client-token"]
+                "pages": ["en/security/introduction", "en/security/ip-block", "en/security/twofactor", "en/security/client-token", "en/security/fraud-protection"]
               },
               {
                 "group": "MCP Server",
@@ -212,7 +212,7 @@
               {
                 "group": "API Reference",
                 "pages": [
-                  { "group": "Instance",          "pages": ["en/instance/introduction", "en/instance/update-auto-read-message", "en/instance/update-auto-read-status", "en/instance/profile-picture", "en/instance/profile-name", "en/instance/profile-description", "en/instance/update-call-reject-auto", "en/instance/update-call-reject-message", "en/instance/qrcode", "en/instance/qr-code", "en/instance/qr-code-image", "en/instance/passkey-prologue", "en/instance/reset-passkey-challenge", "en/instance/phone-code", "en/instance/extension-token", "en/instance/restart", "en/instance/disconnect", "en/instance/status", "en/instance/device", "en/instance/rename-instance", "en/instance/me"] },
+                  { "group": "Instance",          "pages": ["en/instance/introduction", "en/instance/update-auto-read-message", "en/instance/update-auto-read-status", "en/instance/profile-picture", "en/instance/profile-name", "en/instance/profile-description", "en/instance/update-call-reject-auto", "en/instance/update-call-reject-message", "en/instance/qrcode", "en/instance/qr-code", "en/instance/qr-code-image", "en/instance/passkey-prologue", "en/instance/reset-passkey-challenge", "en/instance/phone-code", "en/instance/extension-token", "en/instance/restart", "en/instance/disconnect", "en/instance/status", "en/instance/device", "en/instance/rename-instance", "en/instance/me", "en/instance/update-announcement-guard"] },
                   { "group": "Mobile",            "pages": ["en/mobile/introduction", "en/mobile/registration-available", "en/mobile/request-code", "en/mobile/captcha-confirm", "en/mobile/confirm-code", "en/mobile/device-transfer-confirmed", "en/mobile/request-unbanning", "en/mobile/confirm-security-code", "en/mobile/forgot-security-code", "en/mobile/get-account-email", "en/mobile/set-account-email", "en/mobile/verify-account-email", "en/mobile/get-has-security-code", "en/mobile/set-security-code", "en/mobile/remove-account-email", "en/mobile/remove-security-code"] },
                   { "group": "Messages",          "pages": ["en/message/introduction", "en/message/send-text", "en/message/forward-message", "en/message/send-message-reaction", "en/message/send-remove-reaction", "en/message/send-message-image", "en/message/send-message-sticker", "en/message/send-message-gif", "en/message/send-message-audio", "en/message/send-message-video", "en/message/send-message-ptv", "en/message/send-message-document", "en/message/send-message-link", "en/message/send-message-location", "en/message/send-message-product", "en/message/send-message-catalog", "en/message/send-message-contact", "en/message/send-message-multiple-contacts", "en/message/send-button-actions", "en/message/send-button-list", "en/message/send-button-list-image", "en/message/send-button-list-video", "en/message/send-option-list", "en/message/send-button-otp", "en/message/send-button-pix", "en/message/send-carousel", "en/message/delete-message", "en/message/read-message", "en/message/reply-message", "en/message/send-poll", "en/message/send-poll-vote", "en/message/send-message-order", "en/message/send-order-status-update", "en/message/send-order-payment-update", "en/message/send-pin-message", "en/message/send-newsletter-admin-invite", "en/message/send-event", "en/message/send-edit-event", "en/message/send-event-response", "en/message/reply-button", "en/message/reply-template-button"] },
                   { "group": "Privacy",           "pages": ["en/privacy/introduction", "en/privacy/get-disallowed-contacts", "en/privacy/set-last-seen", "en/privacy/set-photo-visualization", "en/privacy/set-privacy-description", "en/privacy/set-group-add-permission", "en/privacy/set-privacy-online", "en/privacy/set-read-receipts", "en/privacy/set-messages-duration"] },

en/instance/me.mdx

@@ -105,6 +105,10 @@ This method returns your instance data and settings.
   Defines whether the instance is using the configured proxy.
 </ResponseField>
 
+<ResponseField name="announcementGuard" type="boolean">
+  Defines whether the instance with the anti-fraud protection feature in warning groups is active.
+</ResponseField>
+
 ```json
 {
   "id": "123456",
@@ -126,7 +130,8 @@ This method returns your instance data and settings.
   "autoReadMessage": false,
   "initialDataCallbackUrl": "",
   "proxyUrl": "socks5://user:senha123@localhost:1080",
-  "useProxy": true
+  "useProxy": true,
+  "announcementGuard": true
 }
 ```
 

en/instance/update-announcement-guard.mdx

@@ -0,0 +1,51 @@
+---
+title: "Enable Announcement Group Protection"
+api: "PUT /instances/{instanceId}/token/{token}/update-announcement-guard"
+description: "Protect your announcement groups from scam messages by automatically removing content sent by participants who are not admins, and receiving the sender's data via webhook."
+---
+import InstanceId from '/snippets/en/params/instance-id.mdx'
+import Token from '/snippets/en/params/token.mdx'
+
+<Warning>
+Notes about this endpoint
+
+- Only works in announcement groups where the instance is an admin.
+- Ignores admins.
+- Each message generates a webhook event.
+- The author is not removed automatically.
+</Warning>
+
+## Overview
+
+The Anti-Scam Protection in Announcement Groups automatically removes, for all participants, messages sent by scammers — that is, participants who are not admins — in community announcement groups, where only admins can send messages. Whenever a message is removed, you receive a webhook event containing the author's data. This way, your application can identify the responsible party and take the necessary action, such as removing them from the group.
+
+## Attributes
+
+<InstanceId />
+<Token />
+
+### Headers
+
+| Header | Value |
+| :--- | :--- |
+| `Client-Token` | Account security token |
+| `Content-Type` | `application/json` |
+
+### Request Body
+
+```json
+{
+    "value": true
+}
+```
+
+<ParamField body="value" type="boolean" required>
+  Value that toggles the protection, TRUE enables and FALSE disables (Default = FALSE)
+</ParamField>
+
+## Response
+
+### 200
+<ParamField body="value" type="boolean">
+  Returned with the status provided in the request (TRUE or FALSE)
+</ParamField>

en/partner/create-instance.mdx

@@ -101,6 +101,9 @@ It is not necessary to send the **Client-Token** in these requests.
   URL for the WhatsApp profile photo
 </ParamField>
 
+<ParamField body="announcementGuard" type="string">
+  Defines whether the instance with the anti-scam protection feature in warning groups is active.
+</ParamField>
 ---
 
 ## Request Body

en/security/fraud-protection.mdx

@@ -0,0 +1,148 @@
+---
+title: "Anti-Scam Protection in Announcement Groups"
+description: "Anti-scam protection in announcement groups automatically deletes, for everyone, messages sent by scammers (participants who are not admins) in your community announcement groups — groups where only admins can send messages. When the protection deletes a message, you receive an alert on your webhook with the sender's data, so you can decide what to do with the sender (for example, removing them from the group)."
+---
+
+- Configurable per instance and comes disabled by default.
+
+- For it to work, the instance needs to be an admin of the group.
+
+## 1. Enable / disable via API (new endpoint)
+
+In Anti-Scam Protection for Announcement Groups, the feature can also be enabled or disabled via API using the dedicated configuration endpoint.
+
+For more details on how to use the endpoint, refer to the documentation below.
+
+🔗 https://developer.z-api.io/instance/update-announcement-guard
+
+## 2. Check the current state (existing /me endpoint)
+
+After configuring the Anti-Scam Protection, you can check the current state of the feature directly via the API. This lookup lets you verify the settings applied to the instance and confirm whether the protection is properly enabled.
+
+```
+GET https://api.z-api.io/instances/{instanceId}/token/{token}/me
+```
+
+
+The response now includes the new field:
+```json
+{
+  "announcementGuard": true
+}
+```
+
+The field returns TRUE when the feature is active and FALSE when it is disabled.
+
+## 3. Enable via dashboard
+
+In the instance dashboard, under the "Announcement group security" section, the "Anti-scam protection in announcement groups" option is available.
+
+Turning this switch on or off has the same effect as using the endpoint described above, letting you manage the feature directly from the dashboard. After making the change, just use the screen's standard save button to apply the new setting.
+
+## 4. What you receive when the protection acts (webhook)
+
+When the Anti-Scam Protection removes a message identified as a scam attempt, an event is sent as usual through the receiving webhook (**ReceivedCallback**), using the existing "message revoked/deleted" event.
+
+To identify that the message was removed specifically by the protection, just check the **notificationParameters** field present in the webhook payload.
+
+How to identify it:
+
+- notificationParameters: **["ANNOUNCEMENT_GUARD"]** → the scammer's message was successfully deleted by the protection.
+
+- notificationParameters: **["ANNOUNCEMENT_GUARD_FAILED", "[REASON]"]** → the protection attempted to delete it but failed (the message may still be visible). Possible reasons:
+
+| Reason | Meaning |
+| :--- | :--- |
+| `TIMEOUT_EXCEEDED` | Time ran out while trying to delete the message. |
+| `MISSING_GROUP_PERMISSION` | The instance is not an admin of the group or lacks permission to delete messages. |
+| `GROUP_SUSPENDED` | The group is suspended. |
+| `SOMETHING_WENT_WRONG` | A generic failure occurred during the removal attempt. |
+
+## Webhook return
+
+### Return attributes
+
+All returns from this webhook have the following attributes:
+
+<ParamField body="notification" type="string">
+  Indicates the type of notification received. For deleted messages, the value will be `"REVOKE"`.
+</ParamField>
+
+<ParamField body="notificationParameters" type="string">
+  Identifies that the message removal was performed by the Anti-Scam Protection.
+</ParamField>
+
+<ParamField body="phone" type="string">
+  Identifies the group where the message removal occurred.
+</ParamField>
+
+<ParamField body="chatName" type="string">
+  Name of the group where the removal occurred.
+</ParamField>
+
+<ParamField body="messageId" type="string">
+  Identifier of the message that was deleted.
+</ParamField>
+
+<ParamField body="participantPhone" type="string">
+  Phone number of the author of the removed message.
+</ParamField>
+
+<ParamField body="participantLid" type="string">
+  LID identifier of the message's author.
+</ParamField>
+
+<ParamField body="senderName" type="string">
+  Name of the message's author, when available.
+</ParamField>
+
+<ParamField body="fromMe" type="boolean">
+  Indicates whether the message belonged to the instance itself. In this case, the value will be <code>false</code>.
+</ParamField>
+
+<ParamField body="fromApi" type="boolean">
+  Indicates that the action was performed by the platform. In this case, the value will be <code>true</code>.
+</ParamField>
+
+Example payload:
+
+```json
+{
+  "isGroup": true,
+  "instanceId": "YOUR_INSTANCE_ID",
+  "messageId": "3EB0...",
+  "phone": "120363XXXXXXXXXXX-group",
+  "connectedPhone": "5544XXXXXXXXX",
+  "fromMe": false,
+  "fromApi": true,
+  "momment": 199999999,
+  "status": "RECEIVED",
+  "chatName": "Announcement Group Name",
+  "senderName": "Author's Name",
+  "participantPhone": "5544XXXXXXXXX",
+  "participantLid": "XXXXXXXXXXXXXXX@lid",
+  "type": "ReceivedCallback",
+  "notification": "REVOKE",
+  "notificationParameters": ["ANNOUNCEMENT_GUARD"]
+}
+```
+
+## 5. What to do with the event
+
+Using the participantPhone (or participantLid) received in the event, you can call the group participant removal endpoint, already available in the API, to remove the message's author.
+
+The Anti-Scam Protection does not remove the participant automatically. The decision to remove the author or not is up to you, allowing you to define your application's behavior according to your needs.
+
+## 6. Notes
+
+- The protection only acts while the instance is connected and has admin privileges in the group.
+
+- The feature applies exclusively to community announcement groups, where only admins can send messages. It does not act in regular groups or individual chats.
+
+- Messages sent by admins are not affected by the protection.
+
+- Each message is processed individually. Therefore, each revocation generates its own webhook event. If the same author sends multiple messages, each message will be revoked and will generate a new event.
+
+- The message's author is not automatically removed from the group. As long as they remain in the group, they can send new messages. Each new attempt identified by the protection will be handled individually, generating a new revocation and a new webhook event.
+
+---

en/webhooks/on-message-received-examples.mdx

@@ -2288,6 +2288,36 @@ In addition to messages, the webhook also receives call, group, and account noti
 ```
 </Accordion>
 
+</AccordionGroup>
+
+### Communities
+
+<AccordionGroup>
+
+<Accordion title="Anti-Scam Protection for Announcement Groups">
+```json
+{
+  "isGroup": true,
+  "instanceId": "YOUR_INSTANCE_ID",
+  "messageId": "3EB0...",
+  "phone": "120363XXXXXXXXXXX-group",
+  "connectedPhone": "5544XXXXXXXXX",
+  "fromMe": false,
+  "fromApi": true,
+  "momment": 199999999,
+  "status": "RECEIVED",
+  "chatName": "Announcement Group Name",
+  "senderName": "Author's Name",
+  "participantPhone": "5544XXXXXXXXX",
+  "participantLid": "XXXXXXXXXXXXXXX@lid",
+  "type": "ReceivedCallback",
+  "notification": "REVOKE",
+  "notificationParameters": ["ANNOUNCEMENT_GUARD"]
+}
+```
+</Accordion>
+
+
 </AccordionGroup>
 
 ### Channels

instance/me.mdx

@@ -105,6 +105,10 @@ Este método retorna os dados e configurações da sua instância.
   Define se a instância está utilizando o proxy configurado
 </ResponseField>
 
+<ResponseField name="announcementGuard" type="boolean">
+  Define se a instância com o recurso de proteção anti-golpe em grupos de avisos ativa.
+</ResponseField>
+
 ```json
 {
   "id": "123456",
@@ -126,7 +130,8 @@ Este método retorna os dados e configurações da sua instância.
   "autoReadMessage": false,
   "initialDataCallbackUrl": "",
   "proxyUrl": "socks5://user:senha123@localhost:1080",
-  "useProxy": true
+  "useProxy": true,
+  "announcementGuard": true
 }
 ```