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
Message Persistence add-on
This method requires that the Message Persistence add-on is enabled for your key in the Admin Portal.
Requires Message Persistence add-on
This method requires that the Message Persistence add-on is enabled for your key in the Admin Portal. See Enable the features your app calls.
addMessageAction() adds an action to a published message through a PubNub client for JavaScript and returns the added action.
channelrequired#- 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. messageTimetokenrequired#- The timetoken of the published message to add the action to. The SDK rejects an empty value with
Missing message timetoken. actionrequired#- The message action to add, made of a
typeand avalue. The SDK rejects a missing value withMissing Action. - property of action:
typerequired# - The type of the message action, a string that names the kind of metadata, such as
reactionorreceipt. An empty value is invalid. The SDK rejects an empty value withMissing Action.typeand a value of more than 15 characters withAction.type value exceed maximum length of 15. - property of action:
valuerequired# - The value of the message action, a string that carries the metadata, such as
smiley_faceorread. An empty value is invalid. The SDK rejects an empty value withMissing Action.value.
Sample code
Returns
The method returns a Promise that resolves to an AddMessageActionResponse. Its data property holds the added message action.
data#- The added message action.
- property of data:
type# - The
typethat the request set. - property of data:
value# - The
valuethat the request set. - property of data:
uuid# - The User ID of the client that added the action.
- property of data:
actionTimetoken# - The timetoken at which PubNub stored the action. Pass it to
removeMessageAction()to remove the action. - property of data:
messageTimetoken# - The timetoken of the message that has the action.
Examples for Add message action
Syntax
1pubnub.addMessageAction({
2 channel: string,
3 messageTimetoken: string,
4 action: { type: string, value: string }
5}): Promise<AddMessageActionResponse>;
Basic usage
1
1
Returns
1// Example of status
2{
3 "error": false,
4 "operation": "PNAddMessageActionOperation",
5 "statusCode": 200
6}
7
8// Example of response
9{
10 "data": {
11 "type": "reaction",
12 "value": "smiley_face",
13 "uuid": "user-456",
14 "actionTimetoken": "15610547826970050",
15 "messageTimetoken": "15610547826969050"
show all 17 linesRemove message action
Message Persistence add-on
This method requires that the Message Persistence add-on is enabled for your key in the Admin Portal.
Requires Message Persistence add-on
This method requires that the Message Persistence add-on is enabled for your key in the Admin Portal. See Enable the features your app calls.
removeMessageAction() removes an action from a published message through a PubNub client for JavaScript.
channelrequired#- 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. messageTimetokenrequired#- The timetoken of the published message that has the action. The SDK rejects an empty value with
Missing message timetoken. actionTimetokenrequired#- 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.
Sample code
Returns
The method returns a Promise that resolves to a RemoveMessageActionResponse.
data#- An empty object.
Examples for Remove message action
Syntax
1pubnub.removeMessageAction({
2 channel: string,
3 messageTimetoken: string,
4 actionTimetoken: string
5}): Promise<RemoveMessageActionResponse>;
Basic usage
1
Returns
1// Example of status
2{
3 "error": false,
4 "operation": "PNRemoveMessageActionOperation",
5 "statusCode": 200
6}
7
8// Example of response
9{
10 "data": {}
11}
Get message actions
Message Persistence add-on
This method requires that the Message Persistence add-on is enabled for your key in the Admin Portal.
Requires Message Persistence add-on
This method requires that the Message Persistence add-on is enabled for your key in the Admin Portal. See Enable the features your app calls.
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.
channelrequired#- 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#- 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
startandend,startmust be the higher value. end#- 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#- The number of message actions to return in one response.
Sample code
Returns
The method returns a Promise that resolves to a GetMessageActionsResponse.
data#- The message actions in the range. Each item has the properties that
addMessageAction()returns. start#- The action timetoken of the first item in
data, ornullwhendatais empty. end#- The action timetoken of the last item in
data, ornullwhendatais empty. more#- The values for the request that fetches the next page. Present only when PubNub truncated the response.
- property of more:
url# - The prepared REST API URL of the next request.
- property of more:
start# - The
startvalue for the next request. - property of more:
end# - The
endvalue for the next request. - property of more:
limit# - The
limitvalue for the next request.
Examples for Get message actions
Syntax
1pubnub.getMessageActions({
2 channel: string,
3 start?: string,
4 end?: string,
5 limit?: number
6}): Promise<GetMessageActionsResponse>;
Basic usage
1
Returns
1// Example of status
2{
3 "error": false,
4 "operation": "PNGetMessageActionsOperation",
5 "statusCode": 200
6}
7
8// Example of response
9{
10 "data": [
11 {
12 "type": "reaction",
13 "value": "smiley_face",
14 "uuid": "user-456",
15 "actionTimetoken": "15610547826970050",
show all 21 lines