Matrix.org offers a powerful and open source communication protocol. However, I found it a little challenging to read messages which are not displayed in the result of the /sync
api endpoint, when the result is indicated as limited. In the following, I want to give a mini tutorial on how to call which API endpoint to achieve this.
When calling the /sync
endpoint a result could look like this:
{
"next_batch": "s2352952476_758284974_774976_1322574340_1327267577_3188088_470174763_3437232269_212400",
[...]
"rooms": {
"join": {
"!iIGPLCzfAOrMSWriVl:matrix.org": {
"timeline": {
"events": [ ... ],
"prev_batch": "t65-2872959323_757284969_3131697_1323559674_1328554345_3189896_470624878_3443798779_212401",
"limited": true
}
}
The "limited": true
block indicates that the result is limited and more messages are available. The /rooms/<room_id>/messages
api endpoint must be called to obtain the missing messages.
When calling /sync
the first time, the parameter since
will not be set as the caller wants to obtain all data. If for a room the value in the field limited
is set true
as a next step the endpoint /rooms/<room_id>/messages
must be called. The following parameters should be set:
from
will be set to the value of the"prev_batch"
field from the/sync
resultdir
will be set to fix to the valueb
When using the parameters from above, the call looks the following:
/rooms/!iIGPLCzfAOrMSWriVl:matrix.org/messages?from=t65-2872959323_757284969_3131697_1323559674_1328554345_3189896_470624878_3443798779_212401&dir=b
A possible result of the call looks like the following:
{
"chunk": [...],
"start": "t65-2872959323_757284969_3131697_1323559674_1328554345_3189896_470624878_3443798779_212401",
"end": "t363-287475829_757284974_3076414_1323538718_1328524826_3189867_470610561_3443733601_212401"
}
The call of /rooms/<room_id>/messages
must be repeated with the value of the end
field from the last result set as the from
parameter in the new call. There are no more messages to read, if the field end
is either not provided or the value of the end
field equals the value start
field.
When /sync
is called with the parameter since
(i.e., the caller only wants the receive the delta since the last call), calling the endpoint /rooms/<room_id>/messages
is quite similar. The only difference is, that the parameter to
must be set to the same value which was set for since
when calling /sync
. If to
is not set, older messages which are not part of the delta will be displayed.