$receiveMessages_Request method

  1. @experimental
Request $receiveMessages_Request({
  1. required String token,
  2. required ChatReceiveMessagesLookIntoFuture lookIntoFuture,
  3. ChatReceiveMessagesApiVersion? apiVersion,
  4. int? limit,
  5. int? lastKnownMessageId,
  6. int? lastCommonReadId,
  7. int? timeout,
  8. ChatReceiveMessagesSetReadMarker? setReadMarker,
  9. ChatReceiveMessagesIncludeLastKnown? includeLastKnown,
  10. ChatReceiveMessagesNoStatusUpdate? noStatusUpdate,
  11. ChatReceiveMessagesMarkNotificationsAsRead? markNotificationsAsRead,
  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:

  • apiVersion Defaults to "v1".
  • token
  • 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.
  • 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 String token,
  required ChatReceiveMessagesLookIntoFuture lookIntoFuture,
  ChatReceiveMessagesApiVersion? apiVersion,
  int? limit,
  int? lastKnownMessageId,
  int? lastCommonReadId,
  int? timeout,
  ChatReceiveMessagesSetReadMarker? setReadMarker,
  ChatReceiveMessagesIncludeLastKnown? includeLastKnown,
  ChatReceiveMessagesNoStatusUpdate? noStatusUpdate,
  ChatReceiveMessagesMarkNotificationsAsRead? markNotificationsAsRead,
  bool? oCSAPIRequest,
}) {
  final _parameters = <String, Object?>{};
  final __token = _$jsonSerializers.serialize(token, specifiedType: const FullType(String));
  _i4.checkString(
    __token,
    'token',
    pattern: RegExp(r'^[a-z0-9]{4,30}$'),
  );
  _parameters['token'] = __token;

  final __lookIntoFuture =
      _$jsonSerializers.serialize(lookIntoFuture, specifiedType: const FullType(ChatReceiveMessagesLookIntoFuture));
  _parameters['lookIntoFuture'] = __lookIntoFuture;

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

  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;

  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 = _i6.IterableExtension(_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;
}