Doc: Adding MSISDN

docs/add_threePids.md

@@ -143,7 +143,7 @@ POST https://homeserver.org/_matrix/client/r0/account/3pid/add
 
 ## Remove email
 
-### User want to remove the email from his account
+### User want to remove an email from his account
 
 > POST https://homeserver.org/_matrix/client/r0/account/3pid/delete
 
@@ -173,3 +173,113 @@ POST https://homeserver.org/_matrix/client/r0/account/3pid/add
   "id_server_unbind_result": "success"
 }
 ```
+
+## Add phone number
+
+> POST https://homeserver.org/_matrix/client/r0/account/3pid/msisdn/requestToken
+
+```json
+{
+  "country": "FR",
+  "phone_number": "611223344",
+  "client_secret": "f1K29wFZBEr4RZYatu7xj8nEbXiVpr7J",
+  "send_attempt": 1
+}
+```
+
+Note that the phone number is sent without `+` and without the country code
+
+#### The phone number is already added to an account
+
+400
+
+```json
+{
+  "errcode": "M_THREEPID_IN_USE",
+  "error": "MSISDN is already in use"
+}
+```
+
+#### The phone number is free
+
+Wording: "A text message has been sent to +33611223344. Please enter the verification code it contains."
+
+200
+
+```json
+{
+  "msisdn": "33651547677",
+  "intl_fmt": "+33 6 51 54 76 77",
+  "success": true,
+  "sid": "253299954",
+  "submit_url": "https://homeserver.org/_matrix/client/unstable/add_threepid/msisdn/submit_token"
+}
+```
+
+## User receive a text message
+
+> Riot
+
+> Your Riot validation code is 892541, please enter this into the app
+
+### User enter the code to the app
+
+#### Wrong code
+
+> POST https://homeserver.org/_matrix/client/unstable/add_threepid/msisdn/submit_token
+
+```json
+{
+  "sid": "253299954",
+  "client_secret": "f1K29wFZBEr4RZYatu7xj8nEbXiVpr7J",
+  "token": "111111"
+}
+```
+
+400
+
+```json
+{
+  "errcode": "M_UNKNOWN",
+  "error": "Error contacting the identity server"
+}
+```
+
+This is not an ideal, but the client will display a hint to check the entered code to the user.
+
+#### Correct code
+
+> POST https://homeserver.org/_matrix/client/unstable/add_threepid/msisdn/submit_token
+
+```json
+{
+  "sid": "253299954",
+  "client_secret": "f1K29wFZBEr4RZYatu7xj8nEbXiVpr7J",
+  "token": "892541"
+}
+```
+
+200
+
+````json
+{
+  "success": true
+}
+````
+
+Then the app call `https://homeserver.org/_matrix/client/r0/account/3pid/add` as per adding an email and follow the same UIS flow
+
+## Remove phone number
+
+### User wants to remove a phone number from his account
+
+This is the same request and response than to remove email, but with this body:
+
+```json
+{
+  "medium": "msisdn",
+  "address": "33611223344"
+}
+```
+
+Note that the phone number is provided without `+`, but with the country code.