Message Actions API for JavaScript SDK

Message actions let a PubNub client for JavaScript add or remove metadata on published messages, such as receipts and reactions. A client that subscribes to a channel receives message action events through an event listener. A client also fetches past message actions from Message Persistence, either separately or together with the original messages.

For the concepts behind message actions, see Message actions.

Supported and recommended asynchronous patterns

PubNub supports Callbacks, Promises, and Async/Await for asynchronous JS operations. The recommended pattern is Async/Await and all sample requests in this document are based on it. This pattern returns a status only on detecting an error. To receive the error status, you must add the try...catch syntax to your code.

Each method returns a promise that resolves with the response and rejects with a PubNubError. The error carries a status object with category and statusCode, and status.errorData holds the details that PubNub returned for a failed request. Each method also takes a callback as the second argument, and with a callback the method returns nothing and PubNub calls it with (status, response). On success, status.error is false and status.operation names the operation, and on failure status.error is true and response is null. All examples use async/await, so wrap a call in try...catch to receive the error status.

Add message action​

addMessageAction() adds an action to a published message through a PubNub client for JavaScript and returns the added action.

required
channel required#
Type: string
Default: no default
The ID of the channel that stores the target message. An empty value is invalid. The method takes the ID string, not an SDK channel entity. The SDK rejects an empty value with Missing message channel.
messageTimetoken required#
Type: string
Default: no default
The timetoken of the published message to add the action to. The SDK rejects an empty value with Missing message timetoken.
action required#
Type: object
Default: no default
The message action to add, made of a type and a value. The SDK rejects a missing value with Missing Action.
property of action: type required#
Type: string
Default: no default
The type of the message action, a string that names the kind of metadata, such as reaction or receipt. An empty value is invalid. The SDK rejects an empty value with Missing Action.type and a value of more than 15 characters with Action.type value exceed maximum length of 15.
property of action: value required#
Type: string
Default: no default
The value of the message action, a string that carries the metadata, such as smiley_face or read. An empty value is invalid. The SDK rejects an empty value with Missing Action.value.

Returns​

The method returns a Promise that resolves to an AddMessageActionResponse. Its data property holds the added message action.

data#
Type: object
The added message action.
property of data: type#
Type: string
The type that the request set.
property of data: value#
Type: string
The value that the request set.
property of data: uuid#
Type: string
The User ID of the client that added the action.
property of data: actionTimetoken#
Type: string
The timetoken at which PubNub stored the action. Pass it to removeMessageAction() to remove the action.
property of data: messageTimetoken#
Type: string
The timetoken of the message that has the action.

Syntax

1pubnub.addMessageAction({
2 channel: string,
3 messageTimetoken: string,
4 action: { type: string, value: string }
5}): Promise<AddMessageActionResponse>;

Remove message action​

removeMessageAction() removes an action from a published message through a PubNub client for JavaScript.

required
channel required#
Type: string
Default: no default
The ID of the channel that stores the message with the action. An empty value is invalid. The method takes the ID string, not an SDK channel entity. The SDK rejects an empty value with Missing message action channel.
messageTimetoken required#
Type: string
Default: no default
The timetoken of the published message that has the action. The SDK rejects an empty value with Missing message timetoken.
actionTimetoken required#
Type: string
Default: no default
The timetoken of the message action to remove. The add operation returns this timetoken when it stores the action. The SDK rejects an empty value with Missing action timetoken.

Returns​

The method returns a Promise that resolves to a RemoveMessageActionResponse.

data#
Type: object
An empty object.

Syntax

1pubnub.removeMessageAction({
2 channel: string,
3 messageTimetoken: string,
4 actionTimetoken: string
5}): Promise<RemoveMessageActionResponse>;

Get message actions​

getMessageActions() gets the stored message actions of a channel through a PubNub client for JavaScript, within an optional range of action timetokens.

The response lists message actions in ascending order of their action timetokens, oldest first. PubNub can return fewer message actions than the requested range holds when the request reaches an internal limit. To fetch the rest, send another request with adjusted start and end values. A truncated JavaScript response carries a more property with the values for the next request.

required
channel required#
Type: string
Default: no default
The ID of the channel to get message actions for. An empty value is invalid. The method takes the ID string, not an SDK channel entity. The SDK rejects an empty value with Missing message channel.
start#
Type: string
Default: no default
The newer boundary of the range, as an action timetoken. The range is exclusive, so the response includes only actions with a lower timetoken. When you set both start and end, start must be the higher value.
end#
Type: string
Default: no default
The older boundary of the range, as an action timetoken. The range is inclusive, so the response includes actions with a timetoken equal to or higher than end.
limit#
Type: number
Default: no default
The number of message actions to return in one response.

Returns​

The method returns a Promise that resolves to a GetMessageActionsResponse.

data#
Type: array
The message actions in the range. Each item has the properties that addMessageAction() returns.
start#
Type: string or null
The action timetoken of the first item in data, or null when data is empty.
end#
Type: string or null
The action timetoken of the last item in data, or null when data is empty.
more#
Type: object
The values for the request that fetches the next page. Present only when PubNub truncated the response.
property of more: url#
Type: string
The prepared REST API URL of the next request.
property of more: start#
Type: string
The start value for the next request.
property of more: end#
Type: string
The end value for the next request.
property of more: limit#
Type: number
The limit value for the next request.

Syntax

1pubnub.getMessageActions({
2 channel: string,
3 start?: string,
4 end?: string,
5 limit?: number
6}): Promise<GetMessageActionsResponse>;

Was this page useful?

Last updated on