Message Actions API for PubNub Cocoa Objective-C SDK
Add or remove actions on published messages to build features like receipts, reactions, or to associate custom metadata to messages. Clients can subscribe to a channel to receive message action events on that channel. They can also fetch past message actions from Message Persistence independently or when they fetch original messages.
Add Message Action
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
Add an action on a published message
. Returns the added action in the response.
Method(s)
To Add a Message Action you can use the following method(s) in the Cocoa SDK:
- (void)addMessageActionWithRequest:(PNAddMessageActionRequest *)request completion:(nullable PNAddMessageActionCompletionBlock)block
Parameter Type Required Description request
PNAddMessageActionRequest Yes Add message action
request with all information about newmessage action
which will be passed to PubNub service.block
PNAddMessageActionCompletionBlock No Add message action
request completionblock
.PNAddMessageActionRequest
Parameter Type Required Description type
NSString Yes What feature this message action represents. Maximum 15
characters.value
NSString Yes Value which should be added with message action type. channel
NSString Yes Name of channel which stores the message for which action
should be added.messageTimetoken
NSNumber Yes Timetoken (PubNub's high precision timestamp) of message to which action
should be added.
Basic Usage
PNAddMessageActionRequest *request = [PNAddMessageActionRequest requestWithChannel:@"chat"
messageTimetoken:@(1234567890)];
request.type = @"reaction";
request.value = @"smile";
[self.client addMessageActionWithRequest:request completion:^(PNAddMessageActionStatus *status) {
if (!status.isError) {
/**
* Message action successfully added.
* Created message action information available here: status.data.action
*/
} else {
if (status.statusCode == 207) {
// Message action has been added, but event not published.
} else {
/**
* Handle add message action error. Check 'category' property to find out possible
* issue because of which request did fail.
*
* Request can be resent using: [status retry]
*/
}
}
}];
Response
Response objects which is returned by client when add message action
Message Action API is used:
@interface PNAddMessageActionData : PNServiceData
// Added message action.
@property (nonatomic, nullable, readonly, strong) PNMessageAction *action;
@end
@interface PNAddMessageActionStatus : PNAcknowledgmentStatus
// Add message action request processed information.
@property (nonatomic, readonly, strong) PNAddMessageActionData *data;
@end
Add Message Action (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
Add an action on a published message
. Returns the added action in the response.
Method(s)
To Add a Message Action you can use the following method(s) in the Cocoa SDK:
addMessageAction().channel(NSString *).messageTimetoken(NSNumber *).type(NSString *).value(NSString *).performWithCompletion(nullable PNAddMessageActionCompletionBlock)
Parameter Type Required Description channel
NSString Yes Name of channel which store message for which action
should be added.messageTimetoken
NSNumber Yes Timetoken of message for which action
should be added.type
NSString Yes What feature this message action
represents.value
NSString Yes Value which should be stored along with message action
.block
PNAddMessageActionCompletionBlock No Add message action
request completionblock
.
Basic Usage
self.client.addMessageAction()
.channel(@"chat")
.messageTimetoken(@(1234567890))
.type(@"reaction")
.value(@"smile")
.performWithCompletion(^(PNAddMessageActionStatus *status) {
if (!status.isError) {
/**
* Message action successfully added.
* Created message action information available here: status.data.action
*/
} else {
if (status.statusCode == 207) {
// Message action has been added, but event not published.
} else {
/**
* Handle add message action error. Check 'category' property to find out possible
* issue because of which request did fail.
*
* Request can be resent using: [status retry]
*/
}
}
});
Response
Response objects which is returned by client when add message action
Message Action API is used:
@interface PNAddMessageActionData : PNServiceData
// Added message action.
@property (nonatomic, nullable, readonly, strong) PNMessageAction *action;
@end
@interface PNAddMessageActionStatus : PNAcknowledgmentStatus
// Add message action request processed information.
@property (nonatomic, readonly, strong) PNAddMessageActionData *data;
@end
Remove Message Action
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
Remove a peviously added action on a published message
. Returns an empty response.
Method(s)
To Remove a Message Action you can use the following method(s) in the Cocoa SDK:
- (void)removeMessageActionWithRequest:(PNRemoveMessageActionRequest *)request completion:(nullable PNRemoveMessageActionCompletionBlock)block
Parameter Type Required Description request
PNRemoveMessageActionRequest Yes Remove message action
request with information about existingmessage action
.block
PNRemoveMessageActionCompletionBlock No Remove message action
request completionblock
.
PNRemoveMessageActionRequest
Parameter | Type | Required | Description |
---|---|---|---|
actionTimetoken | NSNumber | Yes | Message action addition timetoken. |
channel | NSString | Yes | Name of channel which store message for which action should be removed. |
messageTimetoken | NSNumber | Yes | Timetoken (PubNub's high precision timestamp) of message to which action should be removed. |
Basic Usage
PNRemoveMessageActionRequest *request = [PNRemoveMessageActionRequest requestWithChannel:@"chat"
messageTimetoken:@(1234567890)];
request.actionTimetoken = @(1234567891);
[self.client removeMessageActionWithRequest:request
completion:^(PNAcknowledgmentStatus *status) {
if (!status.isError) {
// Message action successfully removed.
} else {
/**
* Handle remove message action error. Check 'category' property to find out possible
* issue because of which request did fail.
*
* Request can be resent using: [status retry]
*/
}
}];
Response
Response objects which is returned by client when remove message action
Message Action API is used:
@interface PNErrorData : PNServiceData
// Stringified error information.
@property (nonatomic, readonly, strong) NSString *information;
@end
@interface PNAcknowledgmentStatus : PNErrorStatus
// 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
Remove Message Action (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
Remove a peviously added action on a published message
. Returns an empty response.
Method(s)
removeMessageAction().channel(NSString *).messageTimetoken(NSNumber *).actionTimetoken(NSNumber *).performWithCompletion(nullable PNRemoveMessageActionCompletionBlock)
Parameter Type Required Description channel
NSString Yes Name of channel which store message for which action
should be removed.messageTimetoken
NSNumber Yes Timetoken of message for which action
should be removed.actionTimetoken
NSNumber Yes Action
addition timetoken.block
PNRemoveMessageActionCompletionBlock No Remove message action
request completionblock
.
Basic Usage
self.client.removeMessageAction()
.channel("chat")
.messageTimetoken(@(1234567890))
.actionTimetoken(@(1234567891))
.performWithCompletion(^(PNCreateSpaceStatus *status) {
if (!status.isError) {
// Message action successfully removed.
} else {
/**
* Handle remove message action error. Check 'category' property to find out possible
* issue because of which request did fail.
*
* Request can be resent using: [status retry]
*/
}
});
Response
Response objects which is returned by client when remove message action
Message Action API is used:
@interface PNErrorData : PNServiceData
// Stringified error information.
@property (nonatomic, readonly, strong) NSString *information;
@end
@interface PNAcknowledgmentStatus : PNErrorStatus
// 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
Get Message Actions
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
Get a list of message actions in a channel
. Returns a list of actions sorted by the action's timetoken in ascending order.
Method(s)
To Get Message Actions you can use the following method(s) in the Cocoa SDK:
- (void)fetchMessagesActionsWithRequest:(PNFetchMessagesActionsRequest *)request completion:(PNFetchMessageActionsCompletionBlock)block
Parameter Type Required Description request
PNFetchMessageActionsRequest Yes Fetch message actions
request with all information which should be used to fetch existingmessages actions
.block
PNFetchMessageActionsCompletionBlock Yes Fetch message actions
request completionblock
.
PNFetchMessageActionsRequest
Parameter | Type | Required | Description |
---|---|---|---|
start | NSNumber | Yes | Return values will be less than start. |
end | NSNumber | Yes | Return values will be greater than or equal to end. |
limit | NSUInteger | Yes | Number of messages actions to return in response. |
channel | NSString | Yes | Name of channel from which list of message actions should be retrieved. |
Basic Usage
PNFetchMessageActionsRequest *request = [PNFetchMessageActionsRequest requestWithChannel:@"chat"];
request.start = @(1234567891);
request.limit = 200;
[self.client fetchMessageActionsWithRequest:request
completion:^(PNFetchMessageActionsResult *result,
PNErrorStatus *status) {
if (!status.isError) {
/**
* Message actions successfully fetched.
* Result object has following information:
* result.data.actions - list of message action instances
* result.data.start - fetched messages actions time range start (oldest message
* action timetoken).
* result.data.end - fetched messages actions time range end (newest action timetoken).
*/
} else {
/**
* Handle fetch message actions error. Check 'category' property to find out possible
* issue because of which request did fail.
*
* Request can be resent using: [status retry]
*/
}
}];
Response
Response objects which is returned by client when fetch message actions
Message Action API is used:
@interface PNFetchMessageActionsData : PNServiceData
// List of fetched messages actions.
@property (nonatomic, readonly, strong) NSArray<PNMessageAction *> *actions;
/**
* Fetched messages actions time range start (oldest message action timetoken).
*
* This timetoken can be used as 'start' value to fetch older messages actions.
*/
@property (nonatomic, readonly, strong) NSNumber *start;
// Fetched messages actions time range end (newest action timetoken).
@property (nonatomic, readonly, strong) NSNumber *end;
@end
@interface PNFetchMessageActionsResult : PNResult
// Fetch message actions request processed information.
@property (nonatomic, readonly, strong) PNFetchMessageActionsData *data;
@end
Error response which is used in case of Message Action 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
Get Message Actions (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
Get a list of message actions in a channel
. Returns a list of actions sorted by the action's timetoken in ascending order.
Method(s)
To Get Message Actions you can use the following method(s) in the Cocoa SDK:
fetchMessageActions().channel(NSString *).start(NSNumber *).end(NSNumber *).limit(NSUInteger).performWithCompletion(PNFetchMessageActionsCompletionBlock)
Parameter Type Required Description channel
NSString Yes Name of channel from which list of messages actions
should be retrieved.start
NSNumber No Message action
timetoken denoting the start of the range requested. Return values will be less than start.end
NSNumber No Message action
timetoken denoting the end of the range requested. Return values will be greater than or equal to end.limit
NSUInteger No Number of message actions
to return in response.block
PNFetchMessageActionsCompletionBlock Yes Fetch message actions
request completionblock
.
Basic Usage
self.client.fetchMessageActions()
.channel(@"chat")
.start(@(1234567891))
.limit(200)
.performWithCompletion(^(PNFetchMessageActionsResult *result,
NErrorStatus *status) {
if (!status.isError) {
/**
* Message action successfully added.
* Result object has following information:
* result.data.actions - list of message action instances
* result.data.start - fetched messages actions time range start (oldest message
* action timetoken).
* result.data.end - fetched messages actions time range end (newest action timetoken).
*/
} else {
/**
* Handle fetch message actions error. Check 'category' property to find out possible
* issue because of which request did fail.
*
* Request can be resent using: [status retry]
*/
}
});
Response
Response objects which is returned by client when fetch message actions
Message Action API is used:
@interface PNFetchMessageActionsData : PNServiceData
// List of fetched messages actions.
@property (nonatomic, readonly, strong) NSArray<PNMessageAction *> *actions;
/**
* Fetched messages actions time range start (oldest message action timetoken).
*
* This timetoken can be used as 'start' value to fetch older messages actions.
*/
@property (nonatomic, readonly, strong) NSNumber *start;
// Fetched messages actions time range end (newest action timetoken).
@property (nonatomic, readonly, strong) NSNumber *end;
@end
@interface PNFetchMessageActionsResult : PNResult
// Fetch message actions request processed information.
@property (nonatomic, readonly, strong) PNFetchMessageActionsData *data;
@end
Error response which is used in case of Message Action 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