$receiveMessages_Request method

  1. @experimental
Request $receiveMessages_Request({
  1. required ChatReceiveMessagesLookIntoFuture lookIntoFuture,
  2. required String token,
  3. int? limit,
  4. int? lastKnownMessageId,
  5. int? lastCommonReadId,
  6. int? timeout,
  7. ChatReceiveMessagesSetReadMarker? setReadMarker,
  8. ChatReceiveMessagesIncludeLastKnown? includeLastKnown,
  9. ChatReceiveMessagesNoStatusUpdate? noStatusUpdate,
  10. ChatReceiveMessagesMarkNotificationsAsRead? markNotificationsAsRead,
  11. ChatReceiveMessagesApiVersion? apiVersion,
  12. bool? oCSAPIRequest,
})

Receives chat messages from the given room.

  • Receiving the history ($lookIntoFuture=0): The next $limit messages after $lastKnownMessageId will be returned. The new $lastKnownMessageId for the follow up query is available as X-Chat-Last-Given header.
  • Looking into the future ($lookIntoFuture=1): If there are currently no messages the response will not be sent immediately. Instead, HTTP connection will be kept open waiting for new messages to arrive and, when they do, then the response will be sent. The connection will not be kept open indefinitely, though; the number of seconds to wait for new messages to arrive can be set using the timeout parameter; the default timeout is 30 seconds, maximum timeout is 60 seconds. If the timeout ends a successful but empty response will be sent. If messages have been returned (status=200) the new $lastKnownMessageId for the follow up query is available as X-Chat-Last-Given header. The limit specifies the maximum number of messages that will be returned, although the actual number of returned messages could be lower if some messages are not visible to the participant. Note that if none of the messages are visible to the participant the returned number of messages will be 0, yet the status will still be 200. Also note that X-Chat-Last-Given may reference a message not visible and thus not returned, but it should be used nevertheless as the $lastKnownMessageId for the follow-up query.

Returns a DynamiteRequest backing the receiveMessages operation. Throws a DynamiteApiException if the API call does not return an expected status code.

Parameters:

  • lookIntoFuture Polling for new messages (1) or getting the history of the chat (0).
  • limit Number of chat messages to receive (100 by default, 200 at most). Defaults to 100.
  • lastKnownMessageId The last known message (serves as offset). Defaults to 0.
  • lastCommonReadId The last known common read message (so the response is 200 instead of 304 when it changes even when there are no messages). Defaults to 0.
  • timeout Number of seconds to wait for new messages (30 by default, 30 at most). Defaults to 30.
  • setReadMarker Automatically set the last read marker when 1, if your client does this itself via chat/{token}/read set to 0. Defaults to 1.
  • includeLastKnown Include the $lastKnownMessageId in the messages when 1 (default 0). Defaults to 0.
  • noStatusUpdate When the user status should not be automatically set to online set to 1 (default 0). Defaults to 0.
  • markNotificationsAsRead Set to 0 when notifications should not be marked as read (default 1). Defaults to 1.
  • apiVersion Defaults to "v1".
  • token
  • oCSAPIRequest Required to be true for the API request to pass. Defaults to true.

Status codes:

  • 200: Messages returned
  • 304: No messages

See:

Implementation

@_i2.experimental
_i3.Request $receiveMessages_Request({
  required ChatReceiveMessagesLookIntoFuture lookIntoFuture,
  required String token,
  int? limit,
  int? lastKnownMessageId,
  int? lastCommonReadId,
  int? timeout,
  ChatReceiveMessagesSetReadMarker? setReadMarker,
  ChatReceiveMessagesIncludeLastKnown? includeLastKnown,
  ChatReceiveMessagesNoStatusUpdate? noStatusUpdate,
  ChatReceiveMessagesMarkNotificationsAsRead? markNotificationsAsRead,
  ChatReceiveMessagesApiVersion? apiVersion,
  bool? oCSAPIRequest,
}) {
  final _parameters = <String, Object?>{};
  final $lookIntoFuture =
      _$jsonSerializers.serialize(lookIntoFuture, specifiedType: const FullType(ChatReceiveMessagesLookIntoFuture));
  _parameters['lookIntoFuture'] = $lookIntoFuture;

  final $token = _$jsonSerializers.serialize(token, specifiedType: const FullType(String));
  _i4.checkString(
    $token,
    'token',
    pattern: RegExp(r'^[a-z0-9]{4,30}$'),
  );
  _parameters['token'] = $token;

  var $limit = _$jsonSerializers.serialize(limit, specifiedType: const FullType(int));
  $limit ??= 100;
  _parameters['limit'] = $limit;

  var $lastKnownMessageId = _$jsonSerializers.serialize(lastKnownMessageId, specifiedType: const FullType(int));
  $lastKnownMessageId ??= 0;
  _i4.checkNumber(
    $lastKnownMessageId,
    'lastKnownMessageId',
    minimum: 0,
  );
  _parameters['lastKnownMessageId'] = $lastKnownMessageId;

  var $lastCommonReadId = _$jsonSerializers.serialize(lastCommonReadId, specifiedType: const FullType(int));
  $lastCommonReadId ??= 0;
  _i4.checkNumber(
    $lastCommonReadId,
    'lastCommonReadId',
    minimum: 0,
  );
  _parameters['lastCommonReadId'] = $lastCommonReadId;

  var $timeout = _$jsonSerializers.serialize(timeout, specifiedType: const FullType(int));
  $timeout ??= 30;
  _i4.checkNumber(
    $timeout,
    'timeout',
    maximum: 30,
    minimum: 0,
  );
  _parameters['timeout'] = $timeout;

  var $setReadMarker =
      _$jsonSerializers.serialize(setReadMarker, specifiedType: const FullType(ChatReceiveMessagesSetReadMarker));
  $setReadMarker ??= 1;
  _parameters['setReadMarker'] = $setReadMarker;

  var $includeLastKnown = _$jsonSerializers.serialize(
    includeLastKnown,
    specifiedType: const FullType(ChatReceiveMessagesIncludeLastKnown),
  );
  $includeLastKnown ??= 0;
  _parameters['includeLastKnown'] = $includeLastKnown;

  var $noStatusUpdate =
      _$jsonSerializers.serialize(noStatusUpdate, specifiedType: const FullType(ChatReceiveMessagesNoStatusUpdate));
  $noStatusUpdate ??= 0;
  _parameters['noStatusUpdate'] = $noStatusUpdate;

  var $markNotificationsAsRead = _$jsonSerializers.serialize(
    markNotificationsAsRead,
    specifiedType: const FullType(ChatReceiveMessagesMarkNotificationsAsRead),
  );
  $markNotificationsAsRead ??= 1;
  _parameters['markNotificationsAsRead'] = $markNotificationsAsRead;

  var $apiVersion =
      _$jsonSerializers.serialize(apiVersion, specifiedType: const FullType(ChatReceiveMessagesApiVersion));
  $apiVersion ??= 'v1';
  _parameters['apiVersion'] = $apiVersion;

  final _path = _i5.UriTemplate(
    '/ocs/v2.php/apps/spreed/api/{apiVersion}/chat/{token}{?lookIntoFuture*,limit*,lastKnownMessageId*,lastCommonReadId*,timeout*,setReadMarker*,includeLastKnown*,noStatusUpdate*,markNotificationsAsRead*}',
  ).expand(_parameters);
  final _uri = Uri.parse('${_rootClient.baseURL}$_path');
  final _request = _i3.Request('get', _uri);
  _request.headers['Accept'] = 'application/json';
// coverage:ignore-start
  final authentication = _rootClient.authentications?.firstWhereOrNull(
    (auth) => switch (auth) {
      _i1.DynamiteHttpBearerAuthentication() || _i1.DynamiteHttpBasicAuthentication() => true,
      _ => false,
    },
  );

  if (authentication != null) {
    _request.headers.addAll(
      authentication.headers,
    );
  }

// coverage:ignore-end
  var $oCSAPIRequest = _$jsonSerializers.serialize(oCSAPIRequest, specifiedType: const FullType(bool));
  $oCSAPIRequest ??= true;
  _request.headers['OCS-APIRequest'] = const _i4.HeaderEncoder().convert($oCSAPIRequest);

  return _request;
}