WhatsApp Clear vs Delete Chat: Sync the Right Webhook State

Clearing a WhatsApp chat removes its local history but keeps the chat; deleting a chat is a different chat-list action. In UnifyPort, conversation.cleared and conversation.deleted report these changes for the connected account. Neither event means a message was removed for everyone. A shared inbox should distinguish history visibility from conversation visibility, then apply an explicit policy to its own stored copies.

Key takeaways

• These are account-local observations, not commands to delete a customer’s messages.
• data.conversation.id identifies the affected chat; the event’s top-level id does not.
• delete_media describes local media removal, not deletion from your object store or CRM.
• Keep old-history suppression separate from permission to display genuinely new messages.

Clear chat, delete chat, or recall a message?

WhatsApp’s clear-chat guidance says clearing does not remove the chat from the Chats tab or remove you from a group. Its delete-chat guidance treats deleting a chat separately and says a group must first be exited before its chat is deleted. Do not turn either UI action into a universal erase command in your integration.

Observation	Documented scope	Suggested inbox behavior
conversation.cleared	Connected account cleared local history; remote conversation and group membership unchanged	Retain the conversation shell; suppress the affected local history view according to policy
conversation.deleted	Connected account deleted the conversation locally	Remove it from the normal mirrored chat list; retain only permitted reconciliation metadata
message.deleted	One message was deleted or recalled	Resolve the specific message, not the whole chat
conversation.updated	A local chat setting changed	Update the supplied setting; do not infer history deletion

The rightmost column is application design, not automatic UnifyPort behavior. If the intended task is withdrawing a sent message, use the separate edit, revoke, or local hiding guide. A conversation deletion event is not a receipt for a revoke request.

Read the conversation event, not a message payload

The cleared-event reference and deleted-event reference expose a conversation target and delete_media. They do not supply a list of affected message IDs or a documented message-history cutoff.

This illustrative payload uses documented fields and fictional identifiers; it is not captured traffic:

{
  "id": "evt_c4d0b7a2e5",
  "type": "conversation.cleared",
  "provider": "whatsapp",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-10-29T08:15:00Z",
  "data": {
    "conversation": {
      "id": "8600000000000@s.whatsapp.net",
      "type": "user"
    },
    "delete_media": true,
    "event": { "kind": "conversation_cleared" }
  }
}

Use workspace, provider, account_id, and data.conversation.id together for local lookup. Preserve the received identifier; do not reconstruct it from a phone number or merge chats because their titles match. Do not require data.message.id for this branch: it is a conversation event.

The provider event matrix currently maps these two events to whatsapp, not the separate whatsapp-protocol provider or every other channel. The matrix describes parser support, not guaranteed emission by every upstream account or deployment.

Separate three pieces of application state

Before implementing cleanup, decide what your product promises. A mirrored inbox may hide account-local history; a separately governed case record may have different retention requirements. Explain that distinction to operators rather than silently treating a native clear as either “nothing happened” or “erase every business record.”

Maintain these concepts separately in your own storage:

1. Chat-list visibility: whether the conversation appears in the mirrored list.
2. History visibility and cleanup: which previously stored content is suppressed and which owned copies still need cleanup.
3. Future-message admission: when a new observation may reopen the conversation without restoring old content.

These are suggested local concepts, not new webhook fields. Store a minimal scoped marker and the cleanup decision instead of deleting every trace of the conversation identity. Otherwise a delayed history batch can recreate the same visible records.

For both event types, authenticate the delivery using the webhook delivery contract: configure signing_secret, verify HMAC-SHA256 over X-Device-Timestamp, a dot, and the raw body, and check timestamp freshness. In one local transaction, deduplicate the ordinary event, record the visibility change, and enqueue cleanup. Acknowledge with 2xx after durable acceptance, not after waiting for every external system.

Do not let history reload undo the decision

Delivery order is not guaranteed. The event’s occurred_at records the observation’s time, but the clear/delete contract does not define it as a precise cutoff for every affected message. Nor is HTTP arrival time proof that message content is new.

A conservative application policy is:

Later input	Recommended handling while suppression applies
Retry of the same clear/delete event	Keep the decision; continue unfinished cleanup
History batch containing suppressed content	Do not silently republish it
Live event for an already suppressed message ID	Preserve suppression
Apparently new message with uncertain relation to the clear	Hold from automated replies and review the scope
Confirmed new conversation activity	Reopen according to your documented policy, without restoring old history

Known message IDs help protect already stored content. They do not identify old messages that were never received. Without a trustworthy boundary, choose explicit review or conservative suppression rather than claiming perfect chronological reconstruction. A fresh event ID alone does not establish fresh message content.

If your inbox offers history loading, apply this policy inside the merge path described in on-demand WhatsApp history loading. History batches need child-message merging; top-level event-ID deduplication alone can discard legitimate chunks. Loading history must not implicitly reset a local clear decision.

Media cleanup and acceptance checks

delete_media=true means local media was also cleared or removed. It does not confirm deletion of attachments you downloaded, search entries, AI context, or forwarded copies. Conversely, false does not grant permission to retain everything indefinitely. Apply your own disclosed retention and access policy, tracking cleanup separately from webhook acknowledgement.

Test these scenarios with accounts you control:

• Clear history: the conversation shell stays, but suppressed content is not searchable.
• Delete the conversation: the mirrored list hides it without blocking the contact or requesting group exit.
• Receive an old history batch or duplicate event: content is not silently restored.
• Receive genuinely new activity: the reopening rule does not resurrect previous history.
• Fail media cleanup: the inbox reports pending cleanup rather than completed erasure.

These are proposed tests, not reported results. UnifyPort is an unofficial interface with no guaranteed replay or REST message-history read API. No event received is not proof that no local change occurred.

FAQ

Does conversation.deleted delete messages for the other participant?

No. The reference defines an account-local conversation deletion, not deletion for everyone.

Does conversation.cleared mean the account left a group?

No. The event documentation explicitly leaves group membership unchanged.

Can these events drive a Clear chat API button?

They document observations, not outbound clear/delete operations. Do not derive an endpoint from an event name.

Next step and sources

Start with the conversation.cleared reference and define your visibility, retention, and reopening rules before connecting the event to destructive cleanup.

References checked on 2026-10-29:

• WhatsApp: How to clear chats
• WhatsApp: How to delete chats
• UnifyPort: conversation.deleted
• UnifyPort: Webhook delivery