Chat API

Retrieves a chat room entity identified by its roomxtid.

GET /v3/igr/room/{copid}/{roomxtid} HTTP/1.1  
Host: api.instantcmr.com  
x-icmr-auth-1: {authentication-token}  

HTTP/1.1 200 OK  
Date: Thu, 23 Jan 2020 16:29:47 GMT  
Content-Type: application/json; charset=UTF-8  
ETag: {ETag} 
Content-Length: 1386  

{roomed}

Stores a chat room entity, optionally replacing any previous chat entity stored under roomxtid.

To create a new chat room, send a PUT chat room request to the url below, making sure that you generate a globally unique roomxtid for the entity. To ensure that you do not accidentally overwrite an existing chat room, send the request with an If-None-Match: * http header.

To update an existing chat room, send a PUT chat room request to the same url (using the same roomxtid) with the updated data in the request body. Send the request with an If-Match: ETag http header to avoid overwriting updates performed by others. The data sent in the request body will fully replace the data stored by the instantCMR Chat API. This also means that any data (e.g. a membership of the chat room) you skip from the request body will be deleted.

The request will succeed if

• The chat room entity version provided in the If-Match header matches the current entity version (etagroom) stored by instantCMR, or
• The chat room does not exist and an If-None-Match: * header is sent with the request, or
• The chat room sent in the request body matches exactly the current entity stored by instantCMR.

In all of the above cases the update will succeed and the response body will contain the updated chat room entity and the ETag http response header will contain the new etagroom of the chat room. If none of the above conditions are met, the update will be rejected and the response will contain a 412 PreconditionFailed http status code.

To ensure that lost updates are avoided it is recommended that all PUT chat room requests are accompanied by either an If-Match or an If-None-Match header. This way the request is guaranteed to be idempotent and is thus safe to be retried should it fail due to a network outage or backend error.

In case of a conflicting update it is recommended to retrieve the most recent version of the chat room entity using a GET chat room request which will also return the etagroom corresponding to the chat room in the ETag header of the response. The client should then merge its intended changes with the most recent version of the chat room and retry the request with the updated etagroom in the If-Match header. The update should typically succeed, but should it not, repeat the GET chat room & merge & resolve conflicts & PUT chat room process until the system arrives at a fixpoint.

Once set, the chat room identifier (roomxtid) cannot be updated.

Chat rooms can not be deleted either, although it is possible to remove all members from a chat room by sending a PUT chat room request with an empty rgboma field. Note however, that removing all members from a chat room will not remove previous messages posted into the chat room. When the chat room is reanimated later (by adding new members into it) all the new members will see the entire chat history of the chat room.

Members of the chat room can be optionally muted. Muted members of a chat room are unable to post messages via the instantCMR App or Hub, although messages can still be posted in a muted member’s name via PUT message request. In addition to the above muted members do not see read and delivery receipts of other muted members in the chat room.

A chat room can have up to 100 distinct members. Sending a PUT chat room request with more than 100 members in the rgboma field will fail with a 400 BadRequest http status code.

Although a user may be a member of an unlimited number of chat rooms, only the most recently updated 100 chat rooms will be displayed and synchronized to their devices.

When the member list of a chat room is modified (either by adding new members, removing previous members or both) the instantCMR API might require additional processing to administer joining or departing members. This processing might take from a few milliseconds up to a few seconds and is performed asynchronously after the PUT chat room request has finished. During this time amending the member list of the same chat room is prohibited and any such request will yield a 429 TooManyRequests http status code. As usually with similar responses the client is expected to perform a randomized exponential backoff (honoring any timeouts specified in the Retry-After response header) and retry the request later.

The title of a chat room may not exceed 2048 characters. Exceeding this limit in a PUT chat room request will yield a 400 BadRequest http status code.

PUT /v3/igr/room/{copid}/{roomxtid[?silent]} HTTP/1.1  
Host: api.instantcmr.com  
x-icmr-auth-1: {authentication-token}  
Content-Type: application/json  
[If-Match: {etagroom}]  
[If-None-Match: *]  
Content-Length: 1779  

{roomeu}

HTTP/1.1 200 OK  
Date: Thu, 23 Jan 2020 16:29:47 GMT  
Content-Type: application/json; charset=UTF-8  
ETag: {ETag} 
Content-Length: 1386  

{roomed}  

Posts a new message into a chat room.

To post a new message, send a PUT message request to the url below, making sure that you generate a postxtid that is unique within the chat room. Postxtid needs to be unique for each message, even for messages having the same contents sent by the same author, thus applying a hash function on the message contents will not suffice.

To ensure that lost updates are avoided, the client must provide an If-Match header with the etagpost of the most recent known message in the chat room.

The request will succeed if

• The sequence number of the last message posted in the chat room specified by roomxtid matches the etagpost submitted in the If-Match header of the PUT message request, or
• The message immediately following the message denoted by the sequence number submitted as etagpost in the If-Match header of the PUT message is identical to the message sent in the request body, including the message content, author and the client-generated message id (postxtid).

If the request fails due to a network outage or backend error, the request should be retried with the same postxtid in the url and same etagpost in the If-Match header using exponential backoff.

Due to technical limitations the Chat API might be temporarily unable to determine if the message would cause a lost update or duplicate posting. This should occur very infrequently and only for a brief duration. In such cases, the response will contain a 429 TooManyRequests http status code. The client should retry the same request with the same postxtid in the url and the same etagpost in the If-Match header using exponential backoff.

If the message would result in a lost update, the response will contain a 412 PreconditionFailed http status code. In this case the client should retrieve the most recent version of the chat room entity using the GET chat room request and retry the PUT message request with the same message content, same postxtid in the url but this time using the etagpost retrieved in the rovered.wetagdtupost.etag field of the chat room entity. The client should repeat the above process until it succeeds.

When the request succeeds, the most recent etagpost will be returned in the ETag header of the response. The client may save this value for posting future messages into the chat room.

Messages posted in a chat room may not exceed 8196 characters in length. Exceeding this limit will result in a 400 BadRequest http status code.

PUT /v3/igr/room/{copid}/{roomxtid}/post/{postxtid} HTTP/1.1  
Host: api.instantcmr.com  
x-icmr-auth-1: {authentication-token}  
Content-Type: application/json  
If-Match: {etagpost}  
Content-Length: 1779  

{posteu}  

HTTP/1.1 200 OK  
Date: Thu, 23 Jan 2020 16:29:47 GMT  
Content-Type: application/json; charset=UTF-8  
ETag: {ETag} 
Content-Length: 1386  

{posted}

Updates the delivery receipt of a member specified by userxtid of a chat room specified by roomxtid.

To update the delivery receipt of a given member send a PUT delivery receipt request to the url below, specifying the roomxtid of the chat room, userxtid of the member whose delivery receipt should be updated and the etagpost of the most recent message delivered to the member.

The response body will contain the updated chat room entity, including the membership record of the user containing the updated delivery receipt. Please note that the etagpost included in the response might be different from the one specified in the request as updates to stale message sequence numbers will be ignored by the Chat API (previously delivered messages can not be marked as ‘undelivered’).

On rare occasions it might be temporarily impossible to validate the request. In these cases the response will contain a 429 TooManyRequests http status code. Should that be the case the client should retry the same request with exponential backoff.

PUT /v3/igr/room/{copid}/{roomxtid}/user/{userxtid}/sr/{etagpost} HTTP/1.1  
Host: api.instantcmr.com  
x-icmr-auth-1: {authentication-token}  

HTTP/1.1 200 OK  
Date: Thu, 23 Jan 2020 16:29:47 GMT  
Content-Type: application/json; charset=UTF-8  
ETag: {ETag} 
Content-Length: 1386  

{roomed}

Updates the read receipt of a member specified by userxtid of a chat room specified by roomxtid.

To update the read receipt of a given member send a PUT read receipt request to the url below, specifying the roomxtid of the chat room, userxtid of the member whose read receipt should be updated and the etagpost of the most recent message read by the member.

The response body will contain the updated chat room entity, including the membership record of the user containing the updated read receipt. Please note that the etagpost included in the response might be different from the one specified in the request as updates to stale message sequence numbers will be ignored by the Chat API (previously read messages can not be marked as ‘unread’).

On rare occasions it might be temporarily impossible to validate the request. In these cases the response will contain a 429 TooManyRequests http status code. Should that be the case the client should retry the same request with exponential backoff.

PUT /v3/igr/room/{copid}/{roomxtid}/user/{userxtid}/rr/{etagpost} HTTP/1.1  
Host: api.instantcmr.com  
x-icmr-auth-1: {authentication-token}  

HTTP/1.1 200 OK  
Date: Thu, 23 Jan 2020 16:29:47 GMT  
Content-Type: application/json; charset=UTF-8  
ETag: {ETag} 
Content-Length: 1386  

{roomed}