Cocoa Message Persistence API Reference for Real-time Apps
The PubNub Message Persistence Service provides real-time access to history for all messages published to PubNub. Each published message is timestamped to the nearest 10 nanoseconds, and is stored across multiple availability zones in several geographical data center locations. Stored messages can be encrypted with AES-256 message encryption, ensuring that they are not readable while stored on PubNub's network.
Messages can be stored for a configurable duration or forever, as controlled by the retention policy that is configured on your account. The following options are available: 1, 3, 5, 7, 15, or 30 days, and Forever.
History
Requires Message Persistence add-on Requires that the Message Persistence add-on is enabled for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-
Description
This function fetches historical messages of a channel.
It is possible to control how messages are returned and in what order, for example you can:
- Search for messages starting on the newest end of the timeline (default behavior -
reverse
=NO
) - Search for messages from the oldest end of the timeline by setting
reverse
toYES
. - Page through results by providing a
start
ORend
timetoken. - Retrieve a slice of the time line by providing both a
start
ANDend
timetoken. - Limit the number of messages to a specific quantity using the
limit
parameter.
Start & End parameter usage clarity:
If only the start
parameter is specified (without end
), you will receive messages that are older than and up to that start
timetoken value. If only the end
parameter is specified (without start
) you will receive messages that match that end
timetoken value and newer Specifying values for both start
and end
parameters will return messages between those timetoken values (inclusive on the end
value). Keep in mind that you will still receive a maximum of 100 messages even if there are more messages that meet the timetoken values. Iterative calls to history adjusting the start
timetoken is necessary to page through the full set of results if more than 100 messages meet the timetoken values.
Method(s)
To run History
you can use the following method(s) in the Cocoa SDK:
- (void)historyForChannel:(NSString *)channel withCompletion:(PNHistoryCompletionBlock)block;
Parameter Type Required Description channel
NSString Yes Channel
name to retrieve the History information.block
PNHistoryCompletionBlock Yes History
pull processing completionblock
which pass two arguments: result - in case of successful request processing data field will contain results ofhistory
request operation; status - in case if error occurred during request processing.- (void)historyForChannel:(NSString *)channel withMetadata:(BOOL)shouldIncludeMetadata completion:(PNHistoryCompletionBlock)block
Parameter Type Required Description channel
NSString Yes Channel
name to retrieve the History information.shouldIncludeMetadata
BOOL Yes Whether event metadata should be included in response or not. block
PNHistoryCompletionBlock Yes History pull completion block
.- (void)historyForChannel:(NSString *)channel withMessageActions:(BOOL)shouldIncludeMessageActions completion:(PNHistoryCompletionBlock)block
Parameter Type Required Description channel
NSString Yes Channel
name to retrieve the History information.shouldIncludeMessageActions
BOOL Yes Whether event actions should be included in response or not. block
PNHistoryCompletionBlock Yes History pull completion block
.- (void)historyForChannel:(NSString *)channel withMetadata:(BOOL)shouldIncludeMetadata messageActions:(BOOL)shouldIncludeMessageActions completion:(PNHistoryCompletionBlock)block
Parameter Type Required Description channel
NSString Yes Channel
name to retrieve the History information.shouldIncludeMetadata
BOOL Yes Whether event metadata should be included in response or not. shouldIncludeMessageActions
BOOL Yes Whether event actions should be included in response or not. block
PNHistoryCompletionBlock Yes History pull completion block
.- (void)historyForChannel:(NSString *)channel start:(nullable NSNumber *)startDate end:(nullable NSNumber *)endDate withCompletion:(PNHistoryCompletionBlock)block;
Parameter Type Required Description channel
NSString Yes Channel
name to retrieve the History information.startDate
NSNumber No Reference on timetoken for oldest event starting from which next should be returned events. endDate
NSNumber No Reference on timetoken for latest event till which events should be pulled out. block
PNHistoryCompletionBlock Yes History pull processing completion block
which pass two arguments: result - in case of successful request processing data field will contain results of history request operation; status - in case if error occurred during request processing.- (void)historyForChannel:(NSString *)channel start:(nullable NSNumber *)startDate end:(nullable NSNumber *)endDate includeMetadata:(BOOL)shouldIncludeMetadata withCompletion:(PNHistoryCompletionBlock)block
Parameter Type Required Description channel
NSString Yes Channel
name to retrieve the History information.startDate
NSNumber No Timetoken for oldest event starting from which next should be returned events. Value will be converted to required precision internally. endDate
NSNumber No Timetoken for latest event till which events should be pulled out. Value will be converted to required precision internally. shouldIncludeMetadata
BOOL Yes Whether event metadata should be included in response or not. block
PNHistoryCompletionBlock Yes History pull completion block
.- (void)historyForChannel:(NSString *)channel start:(nullable NSNumber *)startDate end:(nullable NSNumber *)endDate includeMessageActions:(BOOL)shouldIncludeMessageActions withCompletion:(PNHistoryCompletionBlock)block
Parameter Type Required Description channel
NSString Yes Channel
name to retrieve the History information.startDate
NSNumber No Timetoken for oldest event starting from which next should be returned events. Value will be converted to required precision internally. endDate
NSNumber No Timetoken for latest event till which events should be pulled out. Value will be converted to required precision internally. shouldIncludeMessageActions
BOOL Yes Whether event actions should be included in response or not. block
PNHistoryCompletionBlock Yes History pull completion block
.- (void)historyForChannel:(NSString *)channel start:(nullable NSNumber *)startDate end:(nullable NSNumber *)endDate includeMetadata:(BOOL)shouldIncludeMetadata includeMessageActions:(BOOL)shouldIncludeMessageActions withCompletion:(PNHistoryCompletionBlock)block
Parameter Type Required Description channel
NSString Yes Channel
name to retrieve the History information.startDate
NSNumber No Timetoken for oldest event starting from which next should be returned events. Value will be converted to required precision internally. endDate
NSNumber No Timetoken for latest event till which events should be pulled out. Value will be converted to required precision internally. shouldIncludeMetadata
BOOL Yes Whether event metadata should be included in response or not. shouldIncludeMessageActions
BOOL Yes Whether event actions should be included in response or not. Throws an exception in case if API called with more than one channel
.block
PNHistoryCompletionBlock Yes History pull completion block
.- (void)historyForChannel:(NSString *)channel start:(nullable NSNumber *)startDate end:(nullable NSNumber *)endDate limit:(NSUInteger)limit withCompletion:(PNHistoryCompletionBlock)block;
Parameter Type Required Description channel
NSString Yes Channel
name to retrieve the History information.startDate
NSNumber No Reference on timetoken for oldest event starting from which next should be returned events. endDate
NSNumber No Reference on timetoken for latest event till which events should be pulled out. limit
NSUInteger Yes Maximum number of events which should be returned in response (not more then 100). block
PNHistoryCompletionBlock Yes History pull processing completion block
which pass two arguments: result - in case of successful request processing data field will contain results of history request operation; status - in case if error occurred during request processing.- (void)historyForChannel:(NSString *)channel start:(nullable NSNumber *)startDate end:(nullable NSNumber *)endDate includeTimeToken:(BOOL)shouldIncludeTimeToken withCompletion:(PNHistoryCompletionBlock)block;
Parameter Type Required Description channel
NSString Yes Channel
name to retrieve the History information.startDate
NSNumber No Reference on timetoken for oldest event starting from which next should be returned events. endDate
NSNumber No Reference on timetoken for latest event till which events should be pulled out. shouldIncludeTimeToken
Bool Yes Whether event dates (timetokens) should be included in response or not. block
PNHistoryCompletionBlock Yes History pull processing completion block
which pass two arguments:- result - in case of successful request processing data field will contain results of history request operation;
- status - in case if error occurred during request processing.
- (void)historyForChannel:(NSString *)channel start:(nullable NSNumber *)startDate end:(nullable NSNumber *)endDate limit:(NSUInteger)limit includeTimeToken:(BOOL)shouldIncludeTimeToken withCompletion:(PNHistoryCompletionBlock)block;
Parameter Type Required Description channel
NSString Yes Channel
name to retrieve the History information.startDate
NSNumber No Reference on timetoken for oldest event starting from which next should be returned events. endDate
NSNumber No Reference on timetoken for latest event till which events should be pulled out. limit
NSUInteger Yes Maximum number of events which should be returned in response (not more then 100). shouldIncludeTimeToken
Bool Yes Whether event dates (timetokens) should be included in response or not. block
PNHistoryCompletionBlock Yes History pull processing completion block
which pass two arguments: result - in case of successful request processing data field will contain results of history request operation; status - in case if error occurred during request processing.- (void)historyForChannel:(NSString *)channel start:(nullable NSNumber *)startDate end:(nullable NSNumber *)endDate limit:(NSUInteger)limit reverse:(BOOL)shouldReverseOrder withCompletion:(PNHistoryCompletionBlock)block;
Parameter Type Required Description channel
NSString Yes Channel
name to retrieve the History information.startDate
NSNumber No Reference on timetoken for oldest event starting from which next should be returned events. endDate
NSNumber No Reference on timetoken for latest event till which events should be pulled out. limit
NSUInteger Yes Maximum number of events which should be returned in response (not more then 100). shouldReverseOrder
Bool Yes Whether events order in response should be reversed or not. block
PNHistoryCompletionBlock Yes History pull processing completion block
which pass two arguments:- result - in case of successful request processing data field will contain results of history request operation;
- status - in case if error occurred during request processing.
- (void)historyForChannel:(NSString *)channel start:(nullable NSNumber *)startDate end:(nullable NSNumber *)endDate limit:(NSUInteger)limit reverse:(BOOL)shouldReverseOrder includeTimeToken:(BOOL)shouldIncludeTimeToken withCompletion:(PNHistoryCompletionBlock)block;
Parameter Type Required Description channel
NSString Yes Channel
name to retrieve the History information.startDate
NSNumber No Reference on timetoken for oldest event starting from which next should be returned events. endDate
NSNumber No Reference on timetoken for latest event till which events should be pulled out. limit
NSUInteger Yes Maximum number of events which should be returned in response (not more then 100). shouldReverseOrder
Bool Yes Whether events order in response should be reversed or not. shouldIncludeTimeToken
Bool Yes Whether event dates (timetokens) should be included in response or not. block
PNHistoryCompletionBlock Yes History pull processing completion block
which pass two arguments: result - in case of successful request processing data field will contain results of history request operation; status - in case if error occurred during request processing.
Using the reverse
parameter:
Messages are always returned sorted in ascending time direction from history regardless of reverse
. The reverse
direction matters when you have more than 100 (or limit
, if it's set) messages in the time interval, in which case reverse
determines the end of the time interval from which it should start retrieving the messages.
Basic Usage
Retrieve the last 100 messages on a channel:
[self.client historyForChannel: @"my_channel" start:nil end:nil limit:100
withCompletion:^(PNHistoryResult *result, PNErrorStatus *status) {
if (!status) {
/**
Handle downloaded history using:
result.data.start - oldest message time stamp in response
result.data.end - newest message time stamp in response
result.data.messages - list of messages
*/
}
else {
/**
Handle message history download error. Check 'category' property
to find out possible reason because of which request did fail.
Review 'errorData' property (which has PNErrorData data type) of status
object to get additional information about issue.
Request can be resent using: [status retry];
*/
}
}];
Response
The response object which is returned by the client when the history API is used:
@interface PNHistoryData : PNServiceData
// Channel history messages.
@property (nonatomic, readonly, strong) NSArray *messages;
// History time frame start time.
@property (nonatomic, readonly, strong) NSNumber *start;
// History time frame end time.
@property (nonatomic, readonly, strong) NSNumber *end;
@end
@interface PNHistoryResult : PNResult
// Stores reference on channel history request processing information.
@property (nonatomic, readonly, strong) PNHistoryData *data;
@end
Other Examples
Use historyForChannel to retrieve the three oldest messages by retrieving from the time line in reverse:
[self.client historyForChannel:@"my_channel" start:nil end:nil limit:3 reverse:YES withCompletion:^(PNHistoryResult *result, PNErrorStatus *status) { if (!status) { /** Handle downloaded history using: result.data.start - oldest message time stamp in response result.data.end - newest message time stamp in response result.data.messages - list of messages */ } else { /** Handle message history download error. Check 'category' property to find out possible reason because of which request did fail. Review 'errorData' property (which has PNErrorData data type) of status object to get additional information about issue. Request can be resent using: [status retry]; */ } }];
[ ["Pub1","Pub2","Pub3"], 13406746729185766, 13406746780720711 ]
Use historyForChannel to retrieve messages newer than a given timetoken by paging from oldest message to newest message starting at a single point in time (exclusive):
[self.client historyForChannel:@"my_channel" start:@(13406746780720711) end:nil limit:100 reverse:YES withCompletion:^(PNHistoryResult *result, PNErrorStatus *status) { if (!status) { /** Handle downloaded history using: result.data.start - oldest message time stamp in response result.data.end - newest message time stamp in response result.data.messages - list of messages */ } else { /** Handle message history download error. Check 'category' property to find out possible reason because of which request did fail. Review 'errorData' property (which has PNErrorData data type) of status object to get additional information about issue. Request can be resent using: [status retry]; */ } }];
[ ["Pub3","Pub4","Pub5"], 13406746780720711, 13406746845892666 ]
Use historyForChannel to retrieve messages until a given timetoken by paging from newest message to oldest message until a specific end point in time (inclusive):
[self.client historyForChannel:@"my_channel" start:nil end:@(13406746780720711) limit:100 includeTimeToken:NO withCompletion:^(PNHistoryResult *result, PNErrorStatus *status) { if (!status) { /** Handle downloaded history using: result.data.start - oldest message time stamp in response result.data.end - newest message time stamp in response result.data.messages - list of messages */ } else { /** Handle message history download error. Check 'category' property to find out possible reason because of which request did fail. Review 'errorData' property (which has PNErrorData data type) of status object to get additional information about issue. Request can be resent using: [status retry]; */ } }];
[ ["Pub3","Pub4","Pub5"], 13406746780720711, 13406746845892666 ]
-
Usage!
You can call the method by passing 0 or a valid timetoken as the argument.
// Pull out all messages newer than message sent at 14395051270438477. [self historyFromStartDate:@(14395051270438477) onChannel:@"history_channel" withCompletionBlock:^(NSArray *messages) { NSLog(@"Messages from history: %@", messages); }]; - (void)historyNewerThan:(NSNumber *)beginTime onChannel:(NSString *)channelName withCompletionBlock:(void (^)(NSArray *messages))block { NSMutableArray *msgs = [NSMutableArray new]; [self historyFromStartDate:beginTime onChannel:channelName withProgress:^(NSArray *objects) { [msgs addObjectsFromArray:objects]; if (objects.count < 100) { block(msgs); } }]; } - (void)historyFromStartDate:(NSNumber *)beginTime onChannel:(NSString *)channelName withProgress:(void (^)(NSArray *objects))block { __weak __typeof(self) weakSelf = self; [self.client historyForChannel:channelName start:beginTime end:nil limit:100 reverse:NO includeTimeToken:YES withCompletion:^(PNHistoryResult *result, PNErrorStatus *status) { __strong __typeof__(weakSelf) strongSelf = weakSelf; if (!status) { block(result.data.messages); if ([result.data.messages count] == 100) { [strongSelf historyFromStartDate:result.data.start onChannel:channelName withProgress:block]; } } else { /** Handle message history download error. Check the 'category' property to find out why the request failed. Review the 'errorData' property (of type PNErrorData) of the status object to get additional information about the issue. Request can be resent using: [status retry]; */ } }]; }
-
[self.client historyForChannel:@"storage" withMetadata:YES completion:^(PNHistoryResult *result, PNErrorStatus *status) { if (!status.isError) { /** * Fetched data available here: * result.data.channels - dictionary with single key (name of requested channel) and * list of dictionaries as value. Each entry will include two keys: "message" - for * body and "metadata" for meta which has been added during message publish. */ } else { /** * Handle message history download error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry]; */ } }];
-
[self.client historyForChannel:@"chat" withMessageActions:YES completion:^(PNHistoryResult *result, PNErrorStatus *status) { if (!status.isError) { /** * Fetched data available here: * result.data.channels - dictionary with single key (name of requested channel) and * list of dictionaries. Each entry will include two keys: "message" - for body and * "actions" for list of added actions. */ } else { /** * Handle message history download error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry]; */ } }];
Fetch messages with metadata and actions
[self.client historyForChannel:@"chat" withMetadata:YES messageActions:YES completion:^(PNHistoryResult *result, PNErrorStatus *status) { if (!status.isError) { /** * Fetched data available here: * result.data.channels - dictionary with single key (name of requested channel) and * list of dictionaries. Each entry will include three keys: "message" - for body, * "metadata" for meta which has been added during message publish and "actions" * for list of added actions. */ } else { /** * Handle message history download error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry]; */ } }];
History (Builder Pattern)
Description
This function fetches historical messages of a channel.
This method uses the builder pattern; you can omit any optional arguments.
Method(s)
To get channel history using the Builder pattern, use the following method(s) in the Cocoa SDK:
- history().channels(NSArray *).start(NSNumber *).end(NSNumber *).limit(NSUInteger).reverse(BOOL).includeMetadata(BOOL).shouldIncludeMessageType(BOOL).shouldIncludeUUID(BOOL).includeMessageActions(BOOL).includeTimeToken(BOOL).performWithCompletion(PNHistoryCompletionBlock);
Parameter Type Required Description channels
NSString Yes List of channels
for which history should be returned.start
NSNumber No Timetoken for oldest event starting from which next should be returned events. Value will be converted to required precision internally. end
NSNumber No Timetoken for latest event till which events should be pulled out. Value will be converted to required precision internally. limit
NSUInteger No Maximum number of messages which should be returned for each channel. Default and maximum value is 100 for a single channel, 25 for multiple channels, and 25 when includeMessageActions
isYES
.reverse
BOOL No Setting to YES
traverses the time line in reverse, starting with the oldest message first.includeMetadata
BOOL No Whether event metadata should be included in response or not. shouldIncludeMessageType
BOOL No Pass YES
to receive the message type with each history message. Default isYES
.shouldIncludeUUID
BOOL No Pass YES
to receive the publisher uuid with each history message. Default isYES
.includeMessageActions
BOOL No Whether event actions should be included in response or not. When YES
, throws an exception if you call the method with more than onechannel
.includeTimeToken
BOOL No Whether event dates (timetokens) should be included in response or not. block
PNHistoryCompletionBlock Yes History pull completion block
.
Using the reverse
parameter:
Messages are always returned sorted in ascending time direction from history regardless of reverse
. The reverse
direction matters when you have more than 100 (or limit
, if it's set) messages in the time interval, in which case reverse
determines the end of the time interval from which it should start retrieving the messages.
Basic Usage
self.client.history().channels(@[@"my_channel"]).limit(15).performWithCompletion(^(PNHistoryResult *result, PNErrorStatus *status) {
if (status == nil) {
/**
Handle downloaded history using:
result.data.channels - dictionary with channels' history. Each key is channel name and value is
list of fetched messages.
*/
}
else {
/**
Handle message history download error. Check 'category' property
to find out possible reason because of which request did fail.
Review 'errorData' property (which has PNErrorData data type) of status
object to get additional information about issue.
Request can be resent using: [status retry]
*/
}
});
Response
Response objects which is returned by client when fetch messages
History API is used:
@interface PNHistoryData : PNServiceData
/**
* Channel history messages.
*
* Set only for PNHistoryOperation operation and will be empty array for other operation types.
*/
@property (nonatomic, readonly, strong) NSArray *messages;
/**
* Channels history.
*
* Each key represent name of channel for which messages has been received and values is list of
* messages from channel's storage.
*
* For PNHistoryOperation operation this property always will be empty dictionary.
*/
@property (nonatomic, readonly, strong) NSDictionary<NSString *, NSArray *> *channels;
/**
* Fetched history time frame start time.
*
* Set only for PNHistoryOperation operation and will be 0 for other operation types.
*/
@property (nonatomic, readonly, strong) NSNumber *start;
/**
* Fetched history time frame end time.
*
* Set only for PNHistoryOperation operation and will be 0 for other operation types.
*/
@property (nonatomic, readonly, strong) NSNumber *end;
@end
@interface PNHistoryResult : PNResult
// Fetch history request processed information.
@property (nonatomic, readonly, strong) PNHistoryData *data;
@end
Error response which is used in case of History API call failure:
@interface PNErrorData : PNServiceData
// Stringified error information.
@property (nonatomic, readonly, strong) NSString *information;
@end
@interface PNErrorStatus : PNStatus
// Whether status object represent error or not.
@property (nonatomic, readonly, assign, getter = isError) BOOL error;
// Additional information related to error status object.
@property (nonatomic, readonly, strong) PNErrorData *errorData;
@end
Other Examples
-
self.client.history() .channel(@"storage") .includeMetadata(YES) .performWithCompletion(^(PNHistoryResult *result, PNErrorStatus *status) { if (!status.isError) { /** * Fetched data available here: * result.data.channels - dictionary with single key (name of requested channel) and * list of dictionaries as value. Each entry will include two keys: "message" - for * body and "metadata" for meta which has been added during message publish. */ } else { /** * Handle message history download error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry]; */ } });
-
self.client.history() .channel(@"chat") .includeMessageActions(YES) .performWithCompletion(^(PNHistoryResult *result, PNErrorStatus *status) { if (!status.isError) { /** * Fetched data available here: * result.data.channels - dictionary with single key (name of requested channel) and * list of dictionaries. Each entry will include two keys: "message" - for body and * "actions" for list of added actions. */ } else { /** * Handle message history download error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry]; */ } });
Fetch messages with metadata and actions
self.client.history() .channel(@"chat") .includeMetadata(YES) .includeMessageActions(YES) .performWithCompletion(^(PNHistoryResult *result, PNErrorStatus *status) { if (!status.isError) { /** * Fetched data available here: * result.data.channels - dictionary with single key (name of requested channel) and * list of dictionaries. Each entry will include three keys: "message" - for body, * "metadata" for meta which has been added during message publish and "actions" * for list of added actions. */ } else { /** * Handle message history download error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry]; */ } });
Delete Messages from History
Requires Message Persistence add-on Requires that the Message Persistence add-on is enabled for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-
Description
Removes the messages from the history of a specific channel.
Note
There is a setting to accept delete from history requests for a key, which you must enable by checking the Enable Delete-From-History
checkbox in the key settings for your key in the Admin Portal.
Requires Initialization with secret key.
Method(s)
To Delete Messages from History
you can use the following method(s) in the Cocoa SDK.
- (void)deleteMessagesFromChannel:(NSString *)channel start:(nullable NSNumber *)startDate end:(nullable NSNumber *)endDate withCompletion:(nullable PNMessageDeleteCompletionBlock)block
Basic Usage
[self.client deleteMessagesFromChannel:@"channel" start:@15101397027611671 end:@15101397427611671
withCompletion:^(PNAcknowledgmentStatus *status) {
if (!status.isError) {
// Messages within specified time frame has been removed.
} else {
/**
* Handle message history download error. Check 'category' property to find out possible
* issue because of which request did fail.
*
* Request can be resent using: [status retry];
*/
}
}];
Other Examples
Delete specific message from history
To delete a specific message, pass the
publish timetoken
(received from a successful publish) in theEnd
parameter andtimetoken +/- 1
in theStart
parameter. e.g. if15526611838554310
is thepublish timetoken
, pass15526611838554309
inStart
and15526611838554310
inEnd
parameters respectively as shown in the following code snippet.[self.client deleteMessagesFromChannel:@"channel" start:@15526611838554310 end:@15526611838554309 withCompletion:^(PNAcknowledgmentStatus *status) { if (!status.isError) { // Messages within specified time frame has been removed. } else { /** * Handle message history download error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry]; */ } }];
Delete Messages from History (Builder Pattern)
Requires Message Persistence add-on Requires that the Message Persistence add-on is enabled for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-
Description
Removes the messages from the history of a specific channel.
Note
There is a setting to accept delete from history requests for a key, which you must enable by checking the Enable Delete-From-History
checkbox in the key settings for your key in the Admin Portal.
Requires Initialization with secret key.
Method(s)
To Delete Messages from History
you can use the following method(s) in the Cocoa SDK.
- deleteMessage().channel(NSString *).start(NSNumber *).end(NSNumber *).performWithCompletion(PNAcknowledgmentStatus *)
Basic Usage
self.client.deleteMessage().channel(@"channel").start(@15101397027611671).end(@15101397427611671)
.performWithCompletion(^(PNAcknowledgmentStatus *status) {
if (!status.isError) {
// Messages within specified time frame has been removed.
} else {
/**
* Handle message history download error. Check 'category' property to find out possible
* issue because of which request did fail.
*
* Request can be resent using: [status retry];
*/
}
});
Message Counts
Requires Message Persistence add-on Requires that the Message Persistence add-on is enabled for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-
Description
Returns the number of messages published on one or more channels since a given time. The count
returned is the number of messages in history with a timetoken
value greater than or equal to
than the passed value in the timetokens
parameter.
Note
For keys with unlimited message retention enabled, this method considers only messages published in the last 30 days.
Method(s)
You can use the following method(s) in the Cocoa SDK:
messageCounts().channels(NSArray<NSString *> *).timetokens(NSArray<NSNumber *> *).performWithCompletion(PNMessageCountCompletionBlock)
Parameter Type Required Defaults Description channels
NSArray<NSString *> * Yes The channels
to fetch the message counttimetokens
NSArray<NSNumber *> * Yes List with single or multiple timetokens, where each timetoken position in correspond to target channel
location in channel names list.completion
PNMessageCountCompletionBlock Yes Messages count fetch completion closure which pass two arguments: result
- in case of successful request processing data field will contain results of message count fetch operation;status
- in case of error occurred during request processing.
Basic Usage
self.client.messageCounts().channels(@[@"unread-channel-1", @"unread-channel-2"])
.timetokens(@[@(15501015683744028)])
.performWithCompletion(^(PNMessageCountResult *result, PNErrorStatus *status) {
if (!status.isError) {
// Client state retrieved number of messages for channels.
} else {
/**
Handle client state modification error. Check 'category' property
to find out possible reason because of which request did fail.
Review 'errorData' property (which has PNErrorData data type) of status
object to get additional information about issue.
Request can be resent using: [status retry]
*/
}
});
Returns
Note
Channels
without messages have a count of 0. Channels
with 10,000 messages or more have a count of 10000.
@interface PNMessageCountData : PNServiceData
/**
* @brief Dictionary where each key is name of channel and value is number of messages in it.
*/
@property (nonatomic, readonly, strong) NSDictionary<NSString *, NSNumber *> *channels;
@end
@interface PNMessageCountResult : PNResult
/**
* @brief Message count request processing information.
*/
@property (nonatomic, readonly, strong) PNMessageCountData *data;
@end
Other Examples
Retrieve count of messages using different timetokens for each channel
self.client.messageCounts().channels(@[@"unread-channel-1", @"unread-channel-2"]) .timetokens(@[@(15501015683744028), @(15501015683744130)]) .performWithCompletion(^(PNMessageCountResult *result, PNErrorStatus *status) { if (!status.isError) { // Client state retrieved number of messages for channels. } else { /** Handle client state modification error. Check 'category' property to find out possible reason because of which request did fail. Review 'errorData' property (which has PNErrorData data type) of status object to get additional information about issue. Request can be resent using: [status retry] */ } });