[feature request] handle timelock events as first class citizen event to allow clients to handle it better

[nagi1]

Is your feature request related to a problem? Please describe.

Whatsapp introduced a new thing called Timelock when you send messages to new contacts your account gets shadow banned for number of hours/days and so...

Describe the solution you'd like

we need a way that waha reports this as first class event instead of listening to engine.event events
also we can follow up with whatsmeow issue for more info.

this is the main issue for "server returned error 463" error

Additional context

• Error 463 when sending messages to specific contacts tulir/whatsmeow#1074
• [INVESTIGATION] 463 error investigation WhiskeySockets/Baileys#2441
• [GOWS] Error 463 on send to cold contacts — tctoken/cstoken not included in outgoing messages #1992
• antiban [https://github.com/kobie3717/baileys-antiban]
• [INVESTIGATION] 463 error investigation WhiskeySockets/Baileys#2441 (comment)
• Unable to send message to a new contact after July 2nd update tulir/whatsmeow#1197

{
	"entity.name": "app",
	"env": "production",
	"hostname": "app",
	"instance_uuid": "<uuid>",
	"ip_request": "127.0.0.1",
	"level": "INFO",
	"message": "engine.event",
	"newrelic.logPattern": "nr.DID_NOT_MATCH",
	"newrelic.source": "api.logs",
	"reference": "01KXBP670BWNT5HM3NRQAMG15Z",
	"request.environment.engine": "GOWS",
	"request.environment.platform": "linux/x64",
	"request.environment.tier": "CORE",
	"request.environment.version": "2026.6.2",
	"request.environment.worker.id": "server",
	"request.event": "engine.event",
	"request.id": "evt_01kxbp660909x2f6wjqqhq5zhf",
	"request.me.id": "201223242242@c.us",
	"request.me.jid": "2442242424:79@s.whatsapp.net",
	"request.me.lid": "242424535@lid",
	"request.payload.data.enforcement_type": "RESTRICT_ALL_COMPANIONS",
        "request.payload.event": "events.NotifyAccountReachoutTimelock",
	"request.payload.data.is_active": true,
	"request.payload.data.time_enforcement_ends": "1784477333",
	"request.payload.session": "1315-instance-1557",
	"request.session": "1315-instance-1557",
	"request.timestamp": 1783877539850,
	"timestamp": 1783877542000,
	"url": "https://app.example.com"
}

The important keys here is

	"request.payload.data.enforcement_type": "RESTRICT_ALL_COMPANIONS",
        "request.payload.event": "events.NotifyAccountReachoutTimelock",

@devlikepro This is very important to handle because it the most logged and complained error on my logs.

[manutheblacker]

Have you heard about Beeper implementation of whatsmeow ?
I'm curious about they manage to support E2EE communications and never seen complaint about 463 while using it.

[nagi1]

Have you heard about Beeper implementation of whatsmeow ?
I'm curious about they manage to support E2EE communications and never seen complaint about 463 while using it.

https://github.com/mautrix/whatsapp

[nagi1]

How Beeper handles the "reachout timelock" mechanism (and why you don't see 463 complaints)

I dug through the Beeper bridge and the whatsmeow library to understand how they handle the account enforcement path. Sharing here since WAHA uses the same underlying libs.

What the timelock/reachout event actually is

WhatsApp sends a NotifyAccountReachoutTimelock notification via the MEX notification system (the same pipe that carries newsletter join/leave events). It's not a connection failure or a stream error. It arrives as a JSON payload over the XMPP stream while the session is still connected:

// types/events/events.go in whatsmeow
type NotifyAccountReachoutTimelock struct {
    Mex                 MexNotificationData
    EnforcementType     string              // e.g. "reachout_timelock"
    IsActive            bool
    TimeEnforcementEnds jsontime.UnixString // when the restriction expires
}

The wire JSON key is "xwa2_notify_account_reachout_timelock". whatsmeow parses it in notification.go inside handleMexNotification() and dispatches it as a typed event.

How Beeper handles it (pkg/connector/handlewhatsapp.go:129-142)

Beeper treats this as purely informational. It does NOT disconnect the session:

case *events.NotifyAccountReachoutTimelock:
    // Log analytics for internal monitoring
    wa.UserLogin.TrackAnalytics("WhatsApp Account Reachout Timelock", map[string]any{
        "enforcement_type":      evt.EnforcementType,
        "is_active":             evt.IsActive,
        "time_enforcement_ends": evt.TimeEnforcementEnds.Time,
    })
    // Save the enforcement end time to persistent metadata
    wa.UserLogin.Metadata.(*waid.UserLoginMetadata).ReachoutTimelockUntil = evt.TimeEnforcementEnds.Time
    // Re-send bridge state so the UI picks up the new reachout_timelock_until field
    if wa.UserLogin.BridgeState.GetPrevUnsent().StateEvent == status.StateConnected {
        wa.UserLogin.BridgeState.Send(status.BridgeState{StateEvent: status.StateConnected})
    }
    wa.UserLogin.Save(ctx)

The enforcement info then surfaces in the bridge state via FillBridgeState() in phoneping.go:

rtu := wa.UserLogin.Metadata.(*waid.UserLoginMetadata).ReachoutTimelockUntil
if !rtu.IsZero() {
    state.Info["reachout_timelock_until"] = rtu
}

And it's persisted in the user login metadata struct (waid/dbmeta.go):

ReachoutTimelockUntil time.Time `json:"reachout_timelock_until,omitempty"`

What "463" means in this context

The "463" terminology comes from the pre-multidevice WhatsApp Web API, where HTTP 463 was a catch-all for "your session is stale, locked, or needs re-pairing." In the multi-device protocol, WhatsApp split that single code into distinct ConnectFailureReason values that whatsmeow handles separately:

Legacy	Multi-device code	whatsmeow event	What it means
463 (session conflict)	401	ConnectFailureLoggedOut	Logged out from another device
463 (device gone)	403	ConnectFailureMainDeviceGone	Primary phone unlinked (WA web code calls this "LOCKED")
463 (account banned)	406	ConnectFailureUnknownLogout	WA web code calls this "BANNED"
(new)	402	ConnectFailureTempBanned	Temporary ban with expiry duration
(new)	--	StreamReplaced	Another process connected with same keys

And the timelock mechanism is a separate, newer layer on top of all of these. It doesn't disconnect the session. WhatsApp uses it for graduated enforcement: rate limiting, reduced reach to new contacts, TOS review flags, etc. The EnforcementType field tells you which one.

Why this avoids "463" complaints

Three things working together:

1. whatsmeow's IsLoggedOut() check covers 401, 403, and 406. When any of these hit, the Beeper bridge clears the device state completely (wa.Client = nil, wa.JID = types.EmptyJID, WADeviceID = 0) and transitions to StateBadCredentials. The user must re-pair. No stale session retry loops.

2. The timelock is separate from logout. Beeper doesn't disconnect on timelock because WhatsApp doesn't disconnect on timelock. The session stays alive. The user sees the restriction in their bridge state but can still receive messages. This is the correct behavior: if you disconnect on a timelock, you'd trigger an unnecessary re-pair flow that would just land you back in the same timelocked state.

3. whatsmeow defaults to AutoTrustIdentity: true, which means identity key changes (one of the scenarios that used to trigger "463" in the old days) are handled automatically: old identity is dropped, Signal sessions are recreated, and the new key is trusted. This happens transparently without user intervention.

The practical takeaway

If you're implementing timelock handling in a whatsmeow-based server, the Beeper approach is: receive the event, persist the expiry time, expose it in your status/health endpoint, but do NOT disconnect. Let WhatsApp enforce the restriction on their side. The session stays connected, and the restriction self-clears when TimeEnforcementEnds passes.

[devlikepro]

We'll use session.status even with WORKING state with additional data

{
    "event": "session.status",
    "session": "default",
    "payload": {
        "status": "WORKING",
        "statuses": [ /* ... */ ],
        // WhatsApp restricts messaging NEW contacts until "timeEnforcementEnds"
        // WAHA re-issues WORKING with "isActive": false when the lock lifts
        "data": {
            "reachoutTimelock": {
                "enforcementType": "RESTRICT_ALL_COMPANIONS",
                "isActive": true,
                "timeEnforcementEnds": 1784477333
            }
        },
    },
    "engine": "GOWS",
}

You can also get this info in GET /me if you missed the event

{
  "id": "11111111111@c.us",
  "pushName": "string",
  // "null" if no enforcement has been seen
  "reachoutTimelock": {
    "enforcementType": "RESTRICT_ALL_COMPANIONS",
    "isActive": true,
    "timeEnforcementEnds": 1784477333
  }
}

[devlikepro]

Let's try dev image 🤞🏻

Make sure to select the engine via the environment variable - WHATSAPP_DEFAULT_ENGINE=WEBJS|GOWS|NOWEB:

• devlikeapro/waha:dev
• devlikeapro/waha:dev-chrome
• devlikeapro/waha:dev-arm

🚀 Will be included in the next release!