Matrix.org: Read all messages when results from /sync are limited

read matrix messages when sync is limited mini tutorial.MD

Mini tutorial: Read matrix messages when sync is limited

Purpose

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.

Problem description

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.

API calls when calling /sync without "since"

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 result
• dir will be set to fix to the value b

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.

API calls when calling /sync with "since"

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.