2026

Pre-send compliance checks on POST /messages

Released: June 4, 2026

`POST /v1/{phone_number_id}/messages` Changed

The messages endpoint now runs three pre-send checks before enqueuing the WhatsApp send. Each check has a stable error code surfaced via the standard 422 error envelope, so you can branch on it without parsing the human-readable message.

New error codes

`error.code`	When it fires	Recoverable?
`marketing_opted_out`	The recipient stopped receiving marketing messages from your WhatsApp business (via the WhatsApp app menu). Only applies to template sends with category `MARKETING`.	No — wait for the customer to opt back in. The `user_preferences` webhook delivers a `resume` event when they do.
`account_restricted`	Meta has restricted your WhatsApp account (policy violation, business-initiated messaging temporarily blocked, etc.). Check your account status in WhatsApp Manager.	Sometimes — depends on the restriction type and expiration. The dashboard banner surfaces the active restriction.
`consent_required`	The recipient has not opted in to receive messages from your business.	No — collect opt-in via your own channel first. See Get opt-in for WhatsApp on Meta’s developer docs.
`upstream_error`	The WhatsApp account is disconnected.	Yes — reconnect the account via the dashboard.

Example 422 response

{
  "error": {
    "type": "invalid_request_error",
    "code": "marketing_opted_out",
    "message": "Customer has opted out of marketing messages.",
    "request_id": "req_01HXYZABCDEFGHJKMNPQRSTVWX"
  }
}

Why this matters

Previously, these conditions surfaced only after Meta rejected the send — usually as a failed status on the message resource a few seconds later. Catching them at request time has three benefits:

No wasted quota — your Meta-side rate budget is preserved.
No quality-rating impact — sends that Meta would have rejected for opt-out reasons would lower your phone number’s quality rating; we no longer expose your account to that risk.
Synchronous feedback — the calling code can show the right error UI immediately instead of polling for terminal status.

Webhook events Added

The platform now subscribes to two more Meta webhook fields:

user_preferences — recipient opted out of (or back into) marketing messages on a per-business basis. Drives the marketing_opted_out check above.
account_alerts — Meta-side alerts on messaging limits, Official Business Account decisions, and profile-photo loss.

Both feed into the dashboard notification bell and the WhatsApp account compliance banner. Make sure both fields are toggled ON in your Meta App Dashboard under WhatsApp → Configuration → Webhooks.

SDK Changed

The TypeScript SDK has been re-synced against the latest OpenAPI spec. The Message.error.code field is now documented with the full known-code list.