Message Actions API for Cocoa Swift SDK

This SDK has been replaced by a new PubNub Swift SDK written purely in Swift. Check out the Swift SDK documentation.

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 Swift method:

open func addMessageAction(with: PNAddMessageActionRequest, completion: PNAddMessageActionCompletionBlock?)

* required

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

PNAddMessageActionRequest

* required

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

Sample code

let request = PNAddMessageActionRequest(channel: "chat", messageTimetoken: 1234567890)
request.type = "reaction"
request.value = "smile"

self.client.addMessageAction(with: request, completion: { status in
    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 23 lines

Response

open class PNAddMessageActionData : PNServiceData {
    // Added message action.
    open var action: PNMessageAction? { get }
}

open class PNAddMessageActionStatus : PNAcknowledgmentStatus {
    // Add message action request processed information.
    open var data: PNAddMessageActionData { get }
}

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 Swift method:

addMessageAction()
    .channel(String)
    .messageTimetoken(NSNumber)
    .type(String)
    .value(String)
    .performWithCompletion(PNAddMessageActionCompletionBlock?)

* required

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

Sample code

self.client.addMessageAction()
    .channel("chat")
    .messageTimetoken(1234567890)
    .type("reaction")
    .value("smile")
    .performWithCompletion({ status in
        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

open class PNAddMessageActionData : PNServiceData {
    // Added message action.
    open var action: PNMessageAction? { get }
}

open class PNAddMessageActionStatus : PNAcknowledgmentStatus {
    // Add message action request processed information.
    open var data: PNAddMessageActionData { get }
}

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 Swift method:

open func removeMessageAction(
    with request: PNRemoveMessageActionRequest,
    completion: PNRemoveMessageActionCompletionBlock?
)

* required

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

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

let request = PNRemoveMessageActionRequest(channel: "chat", messageTimetoken: 1234567890)
request.actionTimetoken = 1234567891

self.client.removeMessageAction(with: request, completion: { status in
    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

open class PNErrorData : PNServiceData {
    // Stringified error information.
    open var information: String { get }
}

open class PNAcknowledgmentStatus : PNErrorStatus {
    // Whether status object represent error or not.
    open var isError: Bool { get }

    // Additional information related to error status object.
    open var data: PNErrorData { get }
}

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(String)
    .messageTimetoken(NSNumber)
    .actionTimetoken(NSNumber)
    .performWithCompletion(PNRemoveMessageActionCompletionBlock?)

* required

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

Sample code

self.client.removeMessageAction()
    .channel("channel")
    .messageTimetoken(1234567890)
    .actionTimetoken(1234567891)
    .performWithCompletion({ status in
        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

open class PNErrorData : PNServiceData {
    // Stringified error information.
    open var information: String { get }
}

open class PNAcknowledgmentStatus : PNErrorStatus {
    // Whether status object represent error or not.
    open var isError: Bool { get }

    // Additional information related to error status object.
    open var data: PNErrorData { get }
}

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 Swift method:

open func fetchMessageActions(
    with request: PNFetchMessageActionsRequest,
    completion: PNFetchMessageActionsCompletionBlock
)

* required

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

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: UInt	Number of message actions to return.
channel * Type: String	Channel name to list message actions for.

Sample code

self.client.fetchMessageActions()
    .channel("chat")
    .start(1234567891)
    .limit(200)
    .performWithCompletion({ (result, status) in
        if !(status?.isError ?? false) {
            /**
             * 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 {

show all 23 lines

Response

open class PNFetchMessageActionsData : PNServiceData {
    // List of fetched messages actions.
    open var actions: [PNMessageAction] { get }

    /**
     * Fetched messages actions time range start (oldest message action timetoken).
     *
     * This timetoken can be used as 'start' value to fetch older messages actions.
    */
    open var start: NSNumber { get }

    // Fetched messages actions time range end (newest action timetoken).
    open var end: NSNumber { get }
}

show all 19 lines

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

open class PNErrorData : PNServiceData {
    // Stringified error information.
    open var information: String { get }
}

open class PNErrorStatus : PNStatus {
    // Whether status object represent error or not.
    open var isError: Bool { get }

    // Additional information related to error status object.
    open var data: PNErrorData { get }
}

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 Swift SDK:

fetchMessageActions()
    .channel(String)
    .start(NSNumber)
    .end(NSNumber)
    .limit(UInt)
    .performWithCompletion(PNFetchMessageActionsCompletionBlock)

* required

Parameter	Description
channel * Type: String	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: UInt	Number of message reactions to return in response.
closure * Type: PNFetchMessageActionsCompletionBlock	Fetch message reactions request completion closure.

Sample code

self.client.fetchMessageActions()
    .channel("chat")
    .start(1234567891)
    .limit(200)
    .performWithCompletion({ (result, status) in
        if !(status?.isError ?? false) {
            /**
             * Message reaction successfully fetched.
             * 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).
            */
        } else {

show all 23 lines

Response

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

open class PNFetchMessageActionsData : PNServiceData {
    // List of fetched messages actions.
    open var actions: [PNMessageAction] { get }

    /**
     * Fetched messages actions time range start (oldest message reaction timetoken).
     *
     * This timetoken can be used as 'start' value to fetch older messages reactions.
    */
    open var start: NSNumber { get }

    // Fetched messages actions time range end (newest action timetoken).
    open var end: NSNumber { get }
}

show all 19 lines

Error response

open class PNErrorData : PNServiceData {
    // Stringified error information.
    open var information: String { get }
}

open class PNErrorStatus : PNStatus {
    // Whether status object represent error or not.
    open var isError: Bool { get }

    // Additional information related to error status object.
    open var data: PNErrorData { get }
}