knockRoom method

Future<String> knockRoom(String roomIdOrAlias, { List<String>? serverName, String? reason, })

Note that this API takes either a room ID or alias, unlike other membership APIs.

This API "knocks" on the room to ask for permission to join, if the user is allowed to knock on the room. Acceptance of the knock happens out of band from this API, meaning that the client will have to watch for updates regarding the acceptance/rejection of the knock.

If the room history settings allow, the user will still be able to see history of the room while being in the "knock" state. The user will have to accept the invitation to join the room (acceptance of knock) to see messages reliably. See the /join endpoints for more information about history visibility to the user.

The knock will appear as an entry in the response of the /sync API.

roomIdOrAlias The room identifier or alias to knock upon.

serverName The servers to attempt to knock on the room through. One of the servers must be participating in the room.

reason Optional reason to be included as the reason on the subsequent membership event.

returns room_id: The knocked room ID.

Implementation

Future<String> knockRoom(String roomIdOrAlias,
    {List<String>? serverName, String? reason}) async {
  final requestUri = Uri(
      path: '_api/client/v3/knock/${Uri.encodeComponent(roomIdOrAlias)}',
      queryParameters: {
        if (serverName != null)
          'server_name': serverName.map((v) => v).toList(),
      });
  final request = Request('POST', baseUri!.resolveUri(requestUri));
  request.headers['authorization'] = 'Bearer ${bearerToken!}';
  request.headers['content-type'] = 'application/json';
  request.bodyBytes = utf8.encode(jsonEncode({
    if (reason != null) 'reason': reason,
  }));
  final response = await httpClient.send(request);
  final responseBody = await response.stream.toBytes();
  if (response.statusCode != 200) unexpectedResponse(response, responseBody);
  final responseString = utf8.decode(responseBody);
  final json = jsonDecode(responseString);
  return json['room_id'] as String;
}