Moderate a Customer

One endpoint for a customer's moderation state: you declare how you want them to end up and the API works out the effects.

PATCH https://api.platica.mx/v1/clients/{id}/moderation

URL parameters

Parameter	Type	Description	Required
`id`	string	Either the customer ID or their phone number in E.164 format without `+`	✓

Request body

You must send at least one of status, resetStrikes, or clearHistory.

Field	Type	Description
`status`	enum	`blocked` to block, `active` to unblock
`reason`	string	Reason recorded on the customer. Up to 120 characters. Only applies with `status: "blocked"`. Defaults to `api_request`
`resetStrikes`	boolean	Zeroes the strike counter. Implied by `status: "active"`
`clearHistory`	boolean	Also wipes the record of the last offence

How to do each operation

Block

{ "status": "blocked", "reason": "abuse_reported" }

Unblock

{ "status": "active" }

Reset strikes without unblocking

{ "resetStrikes": true }

Unblock and wipe the whole moderation record

{ "status": "active", "clearHistory": true }

What each field does

`status: "blocked"`

Sets the customer to status: "blocked", so their future conversations start out marked as spam and agents skip them.
Records moderation.blockedAt, moderation.blockedBy, and moderation.blockedReason.
Marks the conversations the customer already had open as spam, so the block applies right away. Threads already in spam, finished, or expired are left alone.

Nota

Without step 3 the agent would keep answering threads that were already running, because the customer's status is only evaluated when a new conversation opens. That is why this call can emit several conversation.status.updated events alongside the client.updated one.

`status: "active"`

Sets the customer to status: "active" and clears the moderation.blocked* fields.
Zeroes the strikes, even if you did not ask for it. If the counter stayed where it was, the next offence would cross the threshold again and the customer would be blocked immediately.
Moves the conversations sitting in spam back to finished.

`resetStrikes` and `clearHistory`

resetStrikes sets moderation.totalStrikes to zero and removes moderation.lastAction. clearHistory also removes moderation.lastFlaggedAt, lastSource, lastCategories, lastMatchedTerms, and lastSeverity.

Neither one changes the status: a blocked customer stays blocked after their strikes are reset. Use them to forgive a customer who piled up offences but was never blocked.

Response

{
  "status": "success",
  "message": "Client moderation updated successfully",
  "data": {
    "id": "274fc73cb7d84a17955914fdc1a1f9d0",
    "status": "active",
    "strikesReset": true,
    "clearedHistory": false,
    "previousStrikes": 3,
    "conversationsUpdated": 2
  }
}

Field	Description
`id`	Internal ID of the customer
`status`	The status the customer ended up in
`strikesReset`	Whether the strikes were zeroed
`clearedHistory`	Whether the record of the last offence was wiped
`previousStrikes`	Strikes the customer had before the call
`conversationsUpdated`	How many conversations were synced. Always `0` when you do not send `status`

Webhooks

What you sent	`source` on the `client.updated`
`status: "blocked"`	`api.client.blocked`
`status: "active"`	`api.client.unblocked`
Only `resetStrikes` / `clearHistory`	`api.client.strikes_reset`

When you send status you also get one conversation.status.updated per synced conversation.

Errors

Code	Reason
`400`	The body asks for nothing, carries unknown fields, or `workspace` is missing when the API key has access to several
`404`	No customer matches that identifier

Consejo

PATCH /v1/clients/{id} with {"status": "blocked"} runs this same path. The difference is that it only accepts the phone number, while this endpoint also accepts the customer ID — which you need for webchat, Instagram, or Telegram contacts, since those have no phone.

Previous Client Conversations Next Introduction