requestTokenTo3PIDMSISDN method

Future<RequestTokenResponse> requestTokenTo3PIDMSISDN(String clientSecret, String country, String phoneNumber, int sendAttempt, { String? nextLink, String? idAccessToken, String? idServer, })

The homeserver must check that the given phone number is not already associated with an account on this homeserver. This API should be used to request validation tokens when adding a phone number to an account. This API's parameters and response are identical to that of the /register/msisdn/requestToken endpoint. The homeserver should validate the phone number itself, either by sending a validation message itself or by using a service it has control over.

clientSecret A unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters [0-9a-zA-Z.=_-]. Its length must not exceed 255 characters and it must not be empty.

country The two-letter uppercase ISO-3166-1 alpha-2 country code that the number in phone_number should be parsed as if it were dialled from.

nextLink Optional. When the validation is completed, the identity server will redirect the user to this URL. This option is ignored when submitting 3PID validation information through a POST request.

phoneNumber The phone number to validate.

sendAttempt The server will only send an SMS if the send_attempt is a number greater than the most recent one which it has seen, scoped to that country + phone_number + client_secret triple. This is to avoid repeatedly sending the same SMS in the case of request retries between the POSTing user and the identity server. The client should increment this value if they desire a new SMS (e.g. a reminder) to be sent.

idAccessToken An access token previously registered with the identity server. Servers can treat this as optional to distinguish between r0.5-compatible clients and this specification version.

Required if an id_server is supplied.

idServer The hostname of the identity server to communicate with. May optionally include a port. This parameter is ignored when the homeserver handles 3PID verification.

This parameter is deprecated with a plan to be removed in a future specification version for /account/password and /register requests.

Implementation

Future<RequestTokenResponse> requestTokenTo3PIDMSISDN(
  String clientSecret,
  String country,
  String phoneNumber,
  int sendAttempt, {
  String? nextLink,
  String? idAccessToken,
  String? idServer,
}) async {
  final requestUri =
      Uri(path: '_matrix/client/v3/account/3pid/msisdn/requestToken');
  final request = Request('POST', baseUri!.resolveUri(requestUri));
  request.headers['content-type'] = 'application/json';
  request.bodyBytes = utf8.encode(
    jsonEncode({
      'client_secret': clientSecret,
      'country': country,
      if (nextLink != null) 'next_link': nextLink,
      'phone_number': phoneNumber,
      'send_attempt': sendAttempt,
      if (idAccessToken != null) 'id_access_token': idAccessToken,
      if (idServer != null) 'id_server': idServer,
    }),
  );
  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 RequestTokenResponse.fromJson(json as Map<String, Object?>);
}