---
source_url: https://www.pubnub.com/docs/sdks/swift/api-reference/message-actions
title: Message Actions API for Swift Native SDK
updated_at: 2026-05-28T15:04:07.941Z
sdk_name: PubNub Swift SDK
sdk_version: 10.1.6
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


# Message Actions API for Swift Native SDK

PubNub Swift SDK, use the latest version: 10.1.6

Install:

```bash
Add PubNub via Swift Package Manager or CocoaPods@10.1.6
```

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 in real time. Clients can also fetch past message actions from Message Persistence independently or when they fetch original messages.

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

:::note 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](https://www.pubnub.com/docs/sdks) and [Chat](https://www.pubnub.com/docs/chat/overview) 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

:::warning Requires Message Persistence
This method requires that Message Persistence is [enabled](https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-) for your key in the [Admin Portal](https://admin.pubnub.com/).
:::

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

### Method(s)

Use this Swift method:

```swift
func addMessageAction(
    channel: String,
    type actionType: String,
    value: String,
    messageTimetoken: Timetoken,
    custom requestConfig: PubNub.RequestConfiguration = PubNub.RequestConfiguration(),
    completion: ((Result<PubNubMessageAction, Error>) -> Void)?
)
```

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| channel | String | Yes |  | Channel name to add the message action to. |
| type | String | Yes |  | Message action type. |
| value | String | Yes |  | Message action value. |
| messageTimetoken | Timetoken | Yes |  | Timetoken of the target message. |
| custom | PubNub.RequestConfiguration | Optional | `PubNub.RequestConfiguration()` | Per-request configuration. See [Request Configuration](https://www.pubnub.com/docs/sdks/swift/api-reference/configuration#request-configuration). |
| completion | ((Result<PubNubMessageAction, | Optional | `nil` | Async result of the call. |

### Completion handler result

#### Success

The `PubNubMessageAction` that was added.

```swift
public protocol PubNubMessageAction {

  /// The type of action
  var actionType: String { get }

  /// The value that corresponds to the type
  var actionValue: String { get }

  /// The `Timetoken` for this specific action
  var actionTimetoken: Timetoken { get }

  /// The `Timetoken` for the message this action relates to
  var messageTimetoken: Timetoken { get }

  /// The publisher of the message action
  var publisher: String { get }

  /// The channel the action (and message) were sent on
  var channel: String { get }
}
```

#### Failure

An `Error` describing the failure.

### Sample code

:::tip Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
:::

```swift
import PubNubSDK
import Foundation

// Initializes a PubNub object with the configuration
let pubnub = PubNub(
  configuration: PubNubConfiguration(
    publishKey: "demo",
    subscribeKey: "demo",
    userId: "myUniqueUserId"
  )
)

// Add a message action to already existing message published at a specific timetoken
pubnub.addMessageAction(
  channel: "my_channel",
  type: "reaction",
  value: "smiley_face",
  messageTimetoken: 15_610_547_826_969_050
) { result in
  switch result {
  case let .success(messageAction):
    print("Action type \(messageAction.actionType) added at \(messageAction.actionTimetoken) with value \(messageAction.actionValue)")
    print("`\(messageAction.publisher)` added action onto message \(messageAction.messageTimetoken) on `\(messageAction.channel)`")
  case let .failure(error):
    print("Error from failed response: \(error.localizedDescription)")
  }
}
```

## Remove message action

:::warning Requires Message Persistence
This method requires that Message Persistence is [enabled](https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-) for your key in the [Admin Portal](https://admin.pubnub.com/).
:::

Remove a previously added action from a published message.

### Method(s)

Use this Swift method:

```swift
func removeMessageActions(
    channel: String,
    message timetoken: Timetoken,
    action actionTimetoken: Timetoken,
    custom requestConfig: PubNub.RequestConfiguration = PubNub.RequestConfiguration(),
    completion: ((Result<(channel: String, message: Timetoken, action: Timetoken), Error>) -> Void)?
)
```

| Parameter | Description |
| --- | --- |
| `channel` *Type: StringDefault: n/a | Channel name to remove the message action from. |
| `message` *Type: TimetokenDefault: n/a | Timetoken of the target message. |
| `action` *Type: TimetokenDefault: n/a | Timetoken of the message action to remove. |
| `custom`Type: `RequestConfiguration`Default: `RequestConfiguration()` | Per-request configuration. |
| `completion`Type: `((Result<(channel: String, message: Timetoken, action: Timetoken), Error>) -> Void)?`Default: `nil` | Async result of the call. |

#### Completion handler result

#### Success

A `Tuple` containing the channel, message `Timetoken`, and action `Timetoken` of the action that was removed.

#### Failure

An `Error` describing the failure.

### Sample code

```swift
// Remove a message action from a message. Both the message and the action are identified by their timetokens
pubnub.removeMessageActions(
  channel: "my_channel",
  message: 15_610_547_826_969_050,
  action: 15_610_547_826_970_050
) { result in
  switch result {
  case let .success(response):
    print("Action published at \(response.action) was removed from message \(response.message) on channel \(response.channel)")
  case let .failure(error):
    print("Error from failed response: \(error.localizedDescription)")
  }
}
```

## Get message actions

:::warning Requires Message Persistence
This method requires that Message Persistence is [enabled](https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-) for your key in the [Admin Portal](https://admin.pubnub.com/).
:::

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

:::note Truncated response
The number of message actions in the response may be truncated when internal limits are hit. If the response is truncated, a `more` property is returned with additional parameters. Send iterative calls to Message Persistence, adjusting the parameters to fetch more message actions.
:::

### Method(s)

Use this Swift method:

```swift
func fetchMessageActions(
    channel: String,
    page: PubNubBoundedPage? = PubNubBoundedPageBase(),
    custom requestConfig: PubNub.RequestConfiguration = PubNub.RequestConfiguration(),
    completion: ((Result<(actions: [PubNubMessageAction], next: PubNubBoundedPage?), Error>) -> Void)?
)
```

| Parameter | Description |
| --- | --- |
| `channel` *Type: StringDefault: n/a | Channel name to list message actions for. |
| `page`Type: PubNubBoundedPage?Default: `PubNubBoundedPageBase()` | Paging object to specify time bounds; provides `start`, `end`, and `limit`. |
| `custom`Type: [PubNub.RequestConfiguration](https://www.pubnub.com/docs/sdks/swift/api-reference/configuration#request-configuration)Default: `PubNub.RequestConfiguration()` | Per-request configuration. |
| `completion`Type: `((Result<(channel: String, message: Timetoken, action: Timetoken), Error>) -> Void)?`Default: `nil` | Async result of the call. |

#### Completion handler result

#### Success

An `Array` of `PubNubMessageAction` for the request channel, and the next request `PubNubBoundedPage` (if one exists).

```swift
public protocol PubNubMessageAction {

  /// The type of action
  var actionType: String { get }

  /// The value that corresponds to the type
  var actionValue: String { get }

  /// The `Timetoken` for this specific action
  var actionTimetoken: Timetoken { get }

  /// The `Timetoken` for the message this action relates to
  var messageTimetoken: Timetoken { get }

  /// The publisher of the message action
  var publisher: String { get }

  /// The channel the action (and message) were sent on
  var channel: String { get }
}
```

```swift
public protocol PubNubBoundedPage {

  /// The start value for the next set of remote data
  var start: Timetoken? { get }

  /// The bounded end value that will be eventually fetched to
  var end: Timetoken? { get }

  /// The previous limiting value (if any)
  var limit: Int? { get }
}
```

#### Failure

An `Error` describing the failure.

### Sample code

```swift
// Fetch all message actions for a channel
pubnub.fetchMessageActions(channel: "my_channel") { result in
  switch result {
  case let .success(response):
    print("The actions for the channel \(response.actions)")
    print("The next page used for pagination: \(String(describing: response.next))")
  case let .failure(error):
    print("Error from failed response: \(error.localizedDescription)")
  }
}
```

## Terms in this document

* **Channel** - A pathway for sending and receiving messages between devices, created automatically when you first use it, that can handle any number of users and messages for different communication needs, like 1-1 text chats, group conversations, and other data streaming.
* **Channel pattern** - A way to group and analyze channel data to track performance metrics like message counts and user engagement over time with PubNub Insights.