Delete messages from history

Showing JavaScript examples.

This guide shows you how to delete messages from Message Persistence storage. You can remove all messages between two timetokens or target a single message by its publish timetoken.

Three things must be in place before you call the delete API:

• Delete-From-History enabled. Open the Admin Portal, go to your keyset settings, and turn on Enable Delete-From-History. The delete API returns an error if this toggle is off.
• Secret key. The PubNub client making the delete call must be initialized with your secret key. Use it only in server-side code. Never expose the secret key to client devices. For initialization steps, see Application setup.
• delete permission (if Access Manager is on). If Access Manager is enabled on your keyset, the token used for the request must grant delete on the target channel. See Access control.

No undo

Deletion is permanent. There is no recovery path after a successful call, so verify the timetoken range before you send the request.

Delete a range of messages

Pass start and end timetokens to remove all messages between two points in time. The call deletes the message at end but not the message at start, whichever of the two values is larger. For example, if a channel has messages at timetokens T - 1, T, and T + 1:

start	end	Deleted	Kept
T - 1	T + 1	T, T + 1	T - 1
T + 1	T - 1	T - 1, T	T + 1

• JavaScript
• Python
• Swift
• Objective-C
• Java
• C#
• Kotlin
• Dart

1

Delete a specific message

To target a single message, set end to its publish timetoken and start to that timetoken minus 1. PubNub returns the publish timetoken in the publish response. With messages at T - 1, T, and T + 1, this deletes only T. Setting start to the timetoken plus 1 deletes the same message.

For example, if the publish timetoken is 15526611838554310, pass 15526611838554309 as start and 15526611838554310 as end.

• JavaScript
• Python
• Swift
• Objective-C
• Java
• C#
• Kotlin

1

A PubNub timetoken exceeds the largest integer a JavaScript Number represents exactly, so increment or compare timetokens with an arbitrary-precision integer type such as BigInt rather than with plain numeric arithmetic.

Effect on usage metrics

Deleting messages doesn't update usage metrics for past dates.Changes to your stored data volume appear in the Admin Portal within 24 hours.

Related tasks

• Retrieve message history. Check what messages exist in a channel before targeting a deletion range.
• Message Persistence. How storage, retention, and the timetoken model work.