Data deletion options
PubNub stores nine kinds of data across Message Persistence, App Context, File Sharing, Functions, and Access Manager. Each has its own removal method:
- an SDK call
- an Admin Portal or BizOps Workspace action
- a time-based expiry with no manual trigger
Every SDK deletion call on this page is permanent once PubNub acknowledges it. There's no recovery path for a completed delete. For where each data type lives and how long it stays before you delete it, see Data persistence and privacy.
Deletion methods by data type
| Data type | Method | Where |
|---|---|---|
| Messages | deleteMessages() (name varies by SDK) | SDK, server-side with the secret key |
| Message actions | removeMessageAction() (name varies by SDK) | SDK |
| Files | deleteFile() (name varies by SDK) | SDK |
| User metadata | removeUUIDMetadata() (name varies by SDK) | SDK, Admin Portal, or BizOps Workspace |
| Channel metadata | removeChannelMetadata() (name varies by SDK) | SDK, Admin Portal, or BizOps Workspace |
| Memberships | removeMemberships() or removeChannelMembers() (names vary by SDK) | SDK, Admin Portal, or BizOps Workspace |
| Channel groups | deleteGroup() (name varies by SDK) | SDK |
| Mobile push registrations | push.removeChannels() or push.deleteDevice() (names vary by SDK) | SDK |
| Revoked Access Manager tokens | revokeToken() (name varies by SDK). The deny-list entry expires with the token's TTL | SDK, once enabled in the Admin Portal |
| Functions KV store data | kvstore.removeItem(), or a TTL you set on write | Functions code |
Messages
Message Persistence deletion removes messages between two timetokens, or a channel's entire history. Prerequisites:
| Prerequisite | Description |
|---|---|
| Message Persistence | Enabled for the keyset in the Admin Portal. |
| Enable Delete-From-History | Turned on for the keyset in the Admin Portal. |
| Secret key | SDK instance initialized with the secret key. |
delete permission | Required on the channel if Access Manager is enabled. |
The method is deleteMessages() (name varies by SDK). Set start and end one timetoken apart to delete a single message, provide a wider range to delete several, or omit both to delete everything on the channel.
For full examples in every supported SDK, prerequisites in detail, and how the deletion affects usage metrics, see Delete messages.
Message actions
Removing a message action (a reaction, a read receipt, or another annotation) deletes the action record without touching the message it's attached to. Prerequisites:
| Prerequisite | Description |
|---|---|
| Message Persistence | Enabled for the keyset in the Admin Portal. PubNub stores each action the way it stores the message it's attached to. |
| Enable Delete-From-History | Turned on for the keyset in the Admin Portal. |
delete permission | Required on the channel if Access Manager is enabled. A trusted server can sign the request with the secret key instead of using a granted token. |
The method is removeMessageAction() (name varies by SDK). A successful call returns an empty response. A 207 status means the action was deleted but PubNub couldn't publish the deletion event to subscribers. Treat the action as removed either way.
For full examples in every supported SDK, see Remove message actions.
Files
Deleting a file removes it from File Sharing storage. It doesn't remove the file event from Message Persistence history, so if Message Persistence is enabled, the file event record remains in history after the file itself is gone. Prerequisites:
| Prerequisite | Description |
|---|---|
| File ID and name | Returned by listFiles() (name varies by SDK) or the original upload response. |
delete permission | Required on the channel if Access Manager is enabled. |
Unlike message deletion, this call doesn't require the secret key.
For full examples in every supported SDK, see List and manage stored files.
User and channel metadata
Removing an App Context record deletes all custom fields for that user or channel. Prerequisites:
| Prerequisite | Description |
|---|---|
| App Context | Enabled for the keyset in the Admin Portal. |
delete permission | Required on the User ID or channel if Access Manager is enabled. A trusted server can sign the request with the secret key instead of using a granted token. |
Deleting a user's or channel's metadata doesn't require a special setting. It always deletes the metadata record. What it does to that user's or channel's memberships depends on a separate cascade choice: turning on Enforce referential integrity for memberships in the Admin Portal makes the delete cascade, removing every membership that points at the record you just deleted. With that setting off, those memberships stay in place, pointing at a User ID or channel with no metadata record. See Membership connects users and channels for the full referential-integrity behavior.
You can also delete a user or channel record without code, from BizOps Workspace's User Management or Channel Management modules. A record you delete there is the same record your SDK calls read and write.
For full examples in every supported SDK, see Set, get, and remove user metadata, Set, get, and remove channel metadata, Delete users, and Delete channels.
Memberships
A membership connects one user to one channel. You remove it from either side of that relationship:
- From the user's side, to take a user out of one or more channels:
removeMemberships()(name varies by SDK). - From the channel's side, to take one or more users out of a single channel:
removeChannelMembers()(name varies by SDK).
Both calls delete the same underlying membership record. They only differ in which entity, user or channel, you call the operation on.
Deleting a user's or channel's own metadata can also delete its memberships as a side effect. See User and channel metadata for the referential-integrity setting that controls this.
You can also remove a membership without code, from BizOps Workspace's Delete membership action, including in bulk.
For full examples in every supported SDK, see Remove a user from channels and Remove members from a channel.
Channel groups
A channel group is a server-managed list of channels. Deleting it removes the group itself. The member channels aren't affected. Prerequisites:
| Prerequisite | Description |
|---|---|
| Stream Controller | Enabled for the keyset in the Admin Portal. |
manage permission | Required on the group if Access Manager is enabled. |
Example in JavaScript:
1
To remove specific channels from a group instead of deleting the whole group, use the group's remove-channels operation. For the full method signature, every supported SDK, and the group's other operations, see the Channel Groups API reference for your language, listed on Available SDKs.
Mobile push registrations
A push registration links a device token to the channels that can wake it. You remove it from either side:
- For specific channels on one device, remove those channels from the registration:
push.removeChannels()(name varies by SDK). - For a device entirely, remove all of its channels at once:
push.deleteDevice()(name varies by SDK).
Prerequisites:
| Prerequisite | Description |
|---|---|
| Mobile Push Notifications | Enabled for the keyset. |
read permission | Required on the affected channels if Access Manager is enabled. |
Example in JavaScript, removing specific channels from one device:
1
For the full method signature and every supported SDK, see the Mobile Push API reference for your language, listed on Available SDKs.
Revoked Access Manager tokens
Revoking an Access Manager token doesn't delete a stored record. Tokens aren't stored anywhere until you revoke one. Revoking adds it to a deny list so PubNub can reject future calls that use it. A request that uses a revoked token fails with 403 Revoked Token.
A revoked token's deny-list entry persists until the token's original TTL would have expired. There's no call that removes a deny-list entry early. A revoked token can't be re-enabled. Token revocation can take up to one minute to take effect, because PubNub caches a token's non-revoked state for that long. Prerequisites:
| Prerequisite | Description |
|---|---|
| Revoke v3 Token | Enabled for the keyset. See Configure access control. |
For full examples in every supported SDK, see Revoke a token.
Functions KV store data
Functions code can delete its own KV store entries in two ways:
-
Immediately with
kvstore.removeItem(key), called from within a Function.const db = require("kvstore");
db.removeItem("key"); -
Automatically by setting a TTL when you write the value.
db.set(key, value, ttlInMinutes)anddb.setItem(key, value, ttlInMinutes)both accept a TTL in minutes. A KV store entry lives for 1 day by default, and a per-entry TTL can range from 1 minute up to 1 year. A counter isn't subject to TTL and only goes away when you delete it directly.
There's no SDK method for this from your client app. It only runs from inside Functions code. For every KV store operation, see the KV Store module reference.
Related resources
- Data persistence and privacy. Where each data type lives, how long it stays before you delete it, and PubNub's compliance program.
- Data storage. The four storage systems this page's deletion methods act on.
- Operations to permissions mapping. The exact permission each deletion call needs when Access Manager is enabled.
- API limits. Batch sizes and other limits that apply to some of these calls.