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 the support article.

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

Method(s)

Use this Cocoa method:

- (void)addMessageActionWithRequest:(PNAddMessageActionRequest *)request
                         completion:(nullable PNAddMessageActionCompletionBlock)block;

* required

Parameter	Description
request * Type: PNAddMessageActionRequest	Request containing the message action details.
block Type: PNAddMessageActionCompletionBlock	Completion block.

PNAddMessageActionRequest

* required

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

Sample code

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 {

show all 24 lines

Response

Response objects returned by the client when the add 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

Enable Message Persistence for your key in the Admin Portal as described in the support article.

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

Method(s)

Use this Cocoa method:

addMessageAction()
    .channel(NSString *)
    .messageTimetoken(NSNumber *)
    .type(NSString *)
    .value(NSString *)
    .performWithCompletion(nullable PNAddMessageActionCompletionBlock);

* required

Parameter	Description
channel * Type: NSString	Channel name of the target message.
messageTimetoken * Type: NSNumber	Timetoken of the target message.
type * Type: NSString	Message action type.
value * Type: NSString	Message action value.
block Type: PNAddMessageActionCompletionBlock	Completion block.

Sample code

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 {

show all 24 lines

Response

Response objects returned by the client when the add 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

Enable Message Persistence for your key in the Admin Portal as described in the support article.

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

Method(s)

Use this Cocoa method:

- (void)removeMessageActionWithRequest:(PNRemoveMessageActionRequest *)request
                            completion:(nullable PNRemoveMessageActionCompletionBlock)block;

* required

Parameter	Description
request * Type: PNRemoveMessageActionRequest	Request containing the message action to remove.
block Type: PNRemoveMessageActionCompletionBlock	Completion block.

PNRemoveMessageActionRequest

* required

Parameter	Description
actionTimetoken * Type: NSNumber	Timetoken of the message action to remove.
channel * Type: NSString	Channel name of the target message.
messageTimetoken * Type: NSNumber	Timetoken of the target message.

Sample code

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]

show all 18 lines

Response

@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;

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 the support article.

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

Method(s)

removeMessageAction()
    .channel(NSString *)
    .messageTimetoken(NSNumber *)
    .actionTimetoken(NSNumber *)
    .performWithCompletion(nullable PNRemoveMessageActionCompletionBlock);

* required

Parameter	Description
channel * Type: NSString	Channel name of the target message.
messageTimetoken * Type: NSNumber	Timetoken of the target message.
actionTimetoken * Type: NSNumber	Timetoken of the message action to remove.
block Type: PNRemoveMessageActionCompletionBlock	Completion block.

Sample code

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]
             */
        }

show all 16 lines

Response

@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;

show all 16 lines

Get message actions

Requires Message Persistence

Enable Message Persistence for your key in the Admin Portal as described in the support article.

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

Method(s)

Use this Cocoa method:

- (void)fetchMessagesActionsWithRequest:(PNFetchMessagesActionsRequest *)request
                             completion:(PNFetchMessageActionsCompletionBlock)block;

* required

Parameter	Description
request * Type: PNFetchMessageActionsRequest	Request with parameters to fetch message actions.
block * Type: PNFetchMessageActionsCompletionBlock	Completion block.

PNFetchMessageActionsRequest

* required

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

Sample code

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).

show all 26 lines

Response

Response objects which is returned by client when fetch message reactions Message Reaction 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 reaction 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;

show all 23 lines

Error response which is used in case of Message Reaction 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;

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:

fetchMessageActions()
    .channel(NSString *)
    .start(NSNumber *)
    .end(NSNumber *)
    .limit(NSUInteger)
    .performWithCompletion(PNFetchMessageActionsCompletionBlock);

* required

Parameter	Description
channel * 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 * Type: PNFetchMessageActionsCompletionBlock	Fetch message reactions request completion block.

Sample code

self.client.fetchMessageActions()
    .channel(@"chat")
    .start(@(1234567891))
    .limit(200)
    .performWithCompletion(^(PNFetchMessageActionsResult *result,
                             NErrorStatus *status) {

        if (!status.isError) {
            /**
             * Message reaction successfully added.
             * Result object has following information:
             *     result.data.actions - list of message reaction 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).

show all 25 lines

Response

Response objects which is returned by client when fetch message reactions Message Reaction 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;

show all 23 lines

Error response

@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;

show all 16 lines