Message Actions API for Cocoa Objective-C SDK

Use message actions to add or remove metadata on published messages. Common uses include receipts and reactions. Clients subscribe to a channel to receive message action events. Clients can also fetch past message actions from Message Persistence, either on demand or when fetching original messages.

Reactions

"Message Reactions" is a specific application of the Message Actions API for emoji or social reactions.

Message Actions vs. Message Reactions

Message Actions is the flexible, low-level API for adding any metadata to messages (read receipts, delivery confirmations, custom data), while Message Reactions specifically refers to using Message Actions for emoji/social reactions.

In PubNub Core and Chat SDKs, the same underlying Message Actions API is referred to as Message Reactions when used for emoji reactions - it's the same functionality, just different terminology depending on the use case.

Add message action​

Requires Message Persistence

Enable Message Persistence for your key in the Admin Portal as described in Enable the features your app calls.

Add an action to a published message. The response includes the added action.

Method(s)​

Use this Cocoa method:

1- (void)addMessageActionWithRequest:(PNAddMessageActionRequest *)request
2 completion:(nullable PNAddMessageActionCompletionBlock)block;
required
request required#
Request containing the message action details.
block#
Type: PNAddMessageActionCompletionBlock
Completion block.

PNAddMessageActionRequest​

required
type required#
Type: NSString
Message action type. Maximum 15 characters.
value required#
Type: NSString
Message action value.
channel required#
Type: NSString
Channel name of the target message.
messageTimetoken required#
Type: NSNumber
Timetoken of the target message.

Sample code​

1PNAddMessageActionRequest *request = [PNAddMessageActionRequest requestWithChannel:@"chat"
2 messageTimetoken:@(1234567890)];
3request.type = @"reaction";
4request.value = @"smile";
5
6[self.client addMessageActionWithRequest:request completion:^(PNAddMessageActionStatus *status) {
7 if (!status.isError) {
8 /**
9 * Message action successfully added.
10 * Created message action information available here: status.data.action
11 */
12 } else {
13 if (status.statusCode == 207) {
14 // Message action has been added, but event not published.
15 } else {
show all 24 lines

Response​

Response objects returned by the client when the add message action API is used:

1@interface PNAddMessageActionData : PNServiceData
2
3// Added message action.
4@property (nonatomic, nullable, readonly, strong) PNMessageAction *action;
5
6@end
7
8@interface PNAddMessageActionStatus : PNAcknowledgmentStatus
9
10// Add message action request processed information.
11@property (nonatomic, readonly, strong) PNAddMessageActionData *data;
12
13@end

Add message action (builder pattern)​

Requires Message Persistence

Enable Message Persistence for your key in the Admin Portal as described in Enable the features your app calls.

Add an action to a published message. The response includes the added action.

Method(s)​

Use this Cocoa method:

1addMessageAction()
2 .channel(NSString *)
3 .messageTimetoken(NSNumber *)
4 .type(NSString *)
5 .value(NSString *)
6 .performWithCompletion(nullable PNAddMessageActionCompletionBlock);
required
channel required#
Type: NSString
Channel name of the target message.
messageTimetoken required#
Type: NSNumber
Timetoken of the target message.
type required#
Type: NSString
Message action type.
value required#
Type: NSString
Message action value.
block#
Type: PNAddMessageActionCompletionBlock
Completion block.

Sample code​

1self.client.addMessageAction()
2 .channel(@"chat")
3 .messageTimetoken(@(1234567890))
4 .type(@"reaction")
5 .value(@"smile")
6 .performWithCompletion(^(PNAddMessageActionStatus *status) {
7 if (!status.isError) {
8 /**
9 * Message action successfully added.
10 * Created message action information available here: status.data.action
11 */
12 } else {
13 if (status.statusCode == 207) {
14 // Message action has been added, but event not published.
15 } else {
show all 24 lines

Response​

Response objects returned by the client when the add message action API is used:

1@interface PNAddMessageActionData : PNServiceData
2
3// Added message action.
4@property (nonatomic, nullable, readonly, strong) PNMessageAction *action;
5
6@end
7
8@interface PNAddMessageActionStatus : PNAcknowledgmentStatus
9
10// Add message action request processed information.
11@property (nonatomic, readonly, strong) PNAddMessageActionData *data;
12
13@end

Remove message action​

Requires Message Persistence

Enable Message Persistence for your key in the Admin Portal as described in Enable the features your app calls.

Remove a previously added action from a published message. The response is empty.

Method(s)​

Use this Cocoa method:

1- (void)removeMessageActionWithRequest:(PNRemoveMessageActionRequest *)request
2 completion:(nullable PNRemoveMessageActionCompletionBlock)block;
required
request required#
Request containing the message action to remove.
block#
Type: PNRemoveMessageActionCompletionBlock
Completion block.

PNRemoveMessageActionRequest​

required
actionTimetoken required#
Type: NSNumber
Timetoken of the message action to remove.
channel required#
Type: NSString
Channel name of the target message.
messageTimetoken required#
Type: NSNumber
Timetoken of the target message.

Sample code​

1PNRemoveMessageActionRequest *request = [PNRemoveMessageActionRequest requestWithChannel:@"chat"
2 messageTimetoken:@(1234567890)];
3request.actionTimetoken = @(1234567891);
4
5[self.client removeMessageActionWithRequest:request
6 completion:^(PNAcknowledgmentStatus *status) {
7
8 if (!status.isError) {
9 // Message action successfully removed.
10 } else {
11 /**
12 * Handle remove message action error. Check 'category' property to find out possible
13 * issue because of which request did fail.
14 *
15 * Request can be resent using: [status retry]
show all 18 lines

Response​

1@interface PNErrorData : PNServiceData
2
3// Stringified error information.
4@property (nonatomic, readonly, strong) NSString *information;
5
6@end
7
8@interface PNAcknowledgmentStatus : PNErrorStatus
9
10// Whether status object represent error or not.
11@property (nonatomic, readonly, assign, getter = isError) BOOL error;
12
13// Additional information related to error status object.
14@property (nonatomic, readonly, strong) PNErrorData *errorData;
15
show all 16 lines

Remove message action (builder pattern)​

Requires Message Persistence

Enable Message Persistence for your key in the Admin Portal as described in Enable the features your app calls.

Remove a previously added action from a published message. The response is empty.

Method(s)​

1removeMessageAction()
2 .channel(NSString *)
3 .messageTimetoken(NSNumber *)
4 .actionTimetoken(NSNumber *)
5 .performWithCompletion(nullable PNRemoveMessageActionCompletionBlock);
required
channel required#
Type: NSString
Channel name of the target message.
messageTimetoken required#
Type: NSNumber
Timetoken of the target message.
actionTimetoken required#
Type: NSNumber
Timetoken of the message action to remove.
block#
Type: PNRemoveMessageActionCompletionBlock
Completion block.

Sample code​

1self.client.removeMessageAction()
2 .channel("chat")
3 .messageTimetoken(@(1234567890))
4 .actionTimetoken(@(1234567891))
5 .performWithCompletion(^(PNCreateSpaceStatus *status) {
6 if (!status.isError) {
7 // Message action successfully removed.
8 } else {
9 /**
10 * Handle remove message action error. Check 'category' property to find out possible
11 * issue because of which request did fail.
12 *
13 * Request can be resent using: [status retry]
14 */
15 }
show all 16 lines

Response​

1@interface PNErrorData : PNServiceData
2
3// Stringified error information.
4@property (nonatomic, readonly, strong) NSString *information;
5
6@end
7
8@interface PNAcknowledgmentStatus : PNErrorStatus
9
10// Whether status object represent error or not.
11@property (nonatomic, readonly, assign, getter = isError) BOOL error;
12
13// Additional information related to error status object.
14@property (nonatomic, readonly, strong) PNErrorData *errorData;
15
show all 16 lines

Get message actions​

Requires Message Persistence

Enable Message Persistence for your key in the Admin Portal as described in Enable the features your app calls.

Get a list of message actions in a channel. The response sorts actions by the action timetoken in ascending order.

How to use the start and end parameters

PubNub retrieves messages by searching backward through time (newest to oldest). Because of this, the parameter names are the reverse of their intuitive meaning:

  • start is the newer boundary (higher timetoken value) - search begins here, exclusive
  • end is the older boundary (lower timetoken value) - search stops here, inclusive

When you provide both parameters, start must be a higher timetoken than end.

9:00 AM10:00 AM11:00 AM11:59 AM

Results are always returned in oldest-first order.

Method(s)​

Use this Cocoa method:

1- (void)fetchMessagesActionsWithRequest:(PNFetchMessagesActionsRequest *)request
2 completion:(PNFetchMessageActionsCompletionBlock)block;
required
request required#
Request with parameters to fetch message actions.
block required#
Type: PNFetchMessageActionsCompletionBlock
Completion block.

PNFetchMessageActionsRequest​

required
start required#
Type: NSNumber
Message action timetoken for the start of the range (exclusive).
end required#
Type: NSNumber
Message action timetoken for the end of the range (inclusive).
limit required#
Type: NSUInteger
Number of message actions to return.
channel required#
Type: NSString
Channel name to list message actions for.

Sample code​

1PNFetchMessageActionsRequest *request = [PNFetchMessageActionsRequest requestWithChannel:@"chat"];
2request.start = @(1234567891);
3request.limit = 200;
4
5[self.client fetchMessageActionsWithRequest:request
6 completion:^(PNFetchMessageActionsResult *result,
7 PNErrorStatus *status) {
8
9 if (!status.isError) {
10 /**
11 * Message actions successfully fetched.
12 * Result object has following information:
13 * result.data.actions - list of message action instances
14 * result.data.start - fetched messages actions time range start (oldest message
15 * action timetoken).
show all 26 lines

Response​

Response objects which is returned by client when fetch message reactions Message Reaction API is used:

1@interface PNFetchMessageActionsData : PNServiceData
2
3// List of fetched messages actions.
4@property (nonatomic, readonly, strong) NSArray<PNMessageAction *> *actions;
5
6/**
7 * Fetched messages actions time range start (oldest message reaction timetoken).
8 *
9 * This timetoken can be used as 'start' value to fetch older messages actions.
10 */
11@property (nonatomic, readonly, strong) NSNumber *start;
12
13// Fetched messages actions time range end (newest action timetoken).
14@property (nonatomic, readonly, strong) NSNumber *end;
15
show all 23 lines

Error response which is used in case of Message Reaction API call failure:

1@interface PNErrorData : PNServiceData
2
3// Stringified error information.
4@property (nonatomic, readonly, strong) NSString *information;
5
6@end
7
8@interface PNErrorStatus : PNStatus
9
10// Whether status object represent error or not.
11@property (nonatomic, readonly, assign, getter = isError) BOOL error;
12
13// Additional information related to error status object.
14@property (nonatomic, readonly, strong) PNErrorData *errorData;
15
show all 16 lines

Get Message Reactions (builder pattern)​

Requires Message Persistence

This method requires that Message Persistence is enabled for your key in the Admin Portal.

Get a list of message reactions in a channel. Returns a list of actions sorted by the action's timetoken in ascending order.

Method(s)​

To Get Message Reactions you can use the following method(s) in the Cocoa SDK:

1fetchMessageActions()
2 .channel(NSString *)
3 .start(NSNumber *)
4 .end(NSNumber *)
5 .limit(NSUInteger)
6 .performWithCompletion(PNFetchMessageActionsCompletionBlock);
required
channel required#
Type: NSString
Name of channel from which list of messages actions should be retrieved.
start#
Type: NSNumber
Message reaction timetoken denoting the start of the range requested. Return values will be less than start.
end#
Type: NSNumber
Message reaction timetoken denoting the end of the range requested. Return values will be greater than or equal to end.
limit#
Type: NSUInteger
Number of message reactions to return in response.
block required#
Type: PNFetchMessageActionsCompletionBlock
Fetch message reactions request completion block.

Sample code​

1self.client.fetchMessageActions()
2 .channel(@"chat")
3 .start(@(1234567891))
4 .limit(200)
5 .performWithCompletion(^(PNFetchMessageActionsResult *result,
6 NErrorStatus *status) {
7
8 if (!status.isError) {
9 /**
10 * Message reaction successfully added.
11 * Result object has following information:
12 * result.data.actions - list of message reaction instances
13 * result.data.start - fetched messages actions time range start (oldest message
14 * action timetoken).
15 * result.data.end - fetched messages actions time range end (newest action timetoken).
show all 25 lines

Response​

Response objects which is returned by client when fetch message reactions Message Reaction API is used:

1@interface PNFetchMessageActionsData : PNServiceData
2
3// List of fetched messages actions.
4@property (nonatomic, readonly, strong) NSArray<PNMessageAction *> *actions;
5
6/**
7 * Fetched messages actions time range start (oldest message action timetoken).
8 *
9 * This timetoken can be used as 'start' value to fetch older messages actions.
10 */
11@property (nonatomic, readonly, strong) NSNumber *start;
12
13// Fetched messages actions time range end (newest action timetoken).
14@property (nonatomic, readonly, strong) NSNumber *end;
15
show all 23 lines

Error response​

1@interface PNErrorData : PNServiceData
2
3// Stringified error information.
4@property (nonatomic, readonly, strong) NSString *information;
5
6@end
7
8@interface PNErrorStatus : PNStatus
9
10// Whether status object represent error or not.
11@property (nonatomic, readonly, assign, getter = isError) BOOL error;
12
13// Additional information related to error status object.
14@property (nonatomic, readonly, strong) PNErrorData *errorData;
15
show all 16 lines

Was this page useful?

Last updated on