Get message history with actions
Show history messages within the given time range, along with their actions.
-
The response is a list of messages, ordered by ascending
timetoken, wherein some of the message objects may by augmented with actions. -
The actions for a given
messageare organized first by type, then by value. For a given (type, value) pair, all the unique UUIDs who posted that action will be shown, along with thetimetokenwhen the post occurred. Pagination can be controlled withstart,end, andmaxparameters, similar to theget_actions_by_timetokenoperation. -
The server may truncate the number of messages in the response, due to internal limits on the number of queries which can be performed per request. However, the server will always give "complete" messages, in the sense that the messages returned here will always have all their actions. If truncation of the original query occurs, a
morelink will be provided. This indicates that internal limiting has occurred, and the more link itself can be used to continue fetching the originally requested range of messages.
Consider the scenario where most messages have relatively few actions (<250), but the first message has somehow accumulated 25000 actions. If the user requests 25 messages with actions, the first request to history with actions would return only the first message, with all of its 25000 actions underneath it, and provide a more link to signal that truncation has occurred. Then the next request would contain the other 24 messages along with all their actions.
| Path Parameters |
|---|
sub_key string — REQUIREDYour app's subscribe key from Admin Portal. Example:
|
channel string — REQUIREDThe channel ID to perform the operation on. Example:
|
| Query Parameters |
|---|
start numberNewer boundary of the time slice (exclusive). PubNub retrieves messages by searching backward through time (newest to oldest), so Example:
|
end numberOlder boundary of the time slice (inclusive). PubNub retrieves messages by searching backward through time (newest to oldest), so Example:
|
max integerThe max number of messages to return. Default (and maximum value) is 100 messages where number of channels is 1, and 25 messages for any number of channels greater than one (or when retrieving message actions). The batch history is limited to 500 channels. Example:
|
include_meta booleanSet to true to include metadata with returned messages. This metadata is set using the meta parameter with the publish operation. Default is false. Example:
|
include_uuid booleanSet to true to include uuid with returned messages. This is set using the uuid parameter with the publish operation. Default is false. Example:
|
include_message_type booleanSet to true to include pubnub message type with returned messages. Default is false. Example:
|
include_custom_message_type booleanSet to true to include custom message type with returned messages. Default is false. Example:
|
auth stringString which is either the auth key (Access Manager legacy) or a valid token (Access Manager) used to authorize the operation if access control is enabled. Example:
|
uuid stringA UTF-8 encoded string of up to 92 characters used to identify the client. Example:
|
signature stringSignature used to verify that the request was signed with the secret key associated with the subscriber key. If Access Manager is enabled, either a valid authorization token or a signature are required. See Access Manager documentation for details on how to compute the signature. |
timestamp integerUnix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 second offset from NTP. Required if |
| Responses | |||||||||
|---|---|---|---|---|---|---|---|---|---|
200OK
| |||||||||
400The request was invalid.
|
sub_key*channel*startstart must be a higher timetoken value than end when both are provided.If provided, retrieval begins at this timetoken and moves backward in time, excluding the message at this timetoken. If not provided, it defaults to the current time. To page through results, provide a
start OR end timetoken. To retrieve a specific slice, provide both — start must be higher than end.For a full explanation with examples, see Message Persistence.
endend must be a lower timetoken value than start when both are provided.If provided, retrieval stops at this timetoken and includes the message at this timetoken. To page through results, provide an
end OR start timetoken. To retrieve a specific slice, provide both — end must be lower than start.For a full explanation with examples, see Message Persistence.
maxinclude_metainclude_uuidinclude_message_typeinclude_custom_message_typeauthuuidsignatureIf Access Manager is enabled, either a valid authorization token or a signature are required.
See Access Manager documentation for details on how to compute the signature.
timestampRequired if
signature parameter is supplied.status200errorfalseerror_messagechannelsmore{
"status": 200,
"error": false,
"error_message": "",
"channels": {
"demo-channel": [
{
"message": "Hi",
"timetoken": "15610547826970040",
"uuid": "my-uuid",
"message_type": 0,
"meta": {
"some-meta-key": "some_value"
},
"custom_message_type": "custom-user-msg-type",
"actions": {
"receipt": {
"read": [
{
"uuid": "user-7",
"actionTimetoken": "15610547826970044"
}
]
}
}
},
{
"message": "Hello",
"timetoken": "15610547826970000",
"uuid": "my-uuid",
"message_type": 0,
"meta": {
"some-meta-key": "some_value"
},
"custom_message_type": "custom-user-msg-type",
"actions": {
"reaction": {
"smiley_face": [
{
"uuid": "user-456",
"actionTimetoken": "15610547826970050"
}
],
"raccoon": [
{
"uuid": "user-789",
"actionTimetoken": "15610547826980050"
},
{
"uuid": "user-567",
"actionTimetoken": "15610547826970000"
}
]
}
}
}
]
},
"more": {
"url": "/v3/history-with-actions/s/channel/c?start=15610547826970000&max=98",
"start": "15610547826970000",
"max": 98
}
}status400errortrueerror_message"Invalid Arguments: start"channels{}