Add documentation to validate phone numbers

docs/sessions/3pid.md

@@ -98,11 +98,17 @@ Built-in generators and connectors for supported 3PID types:
 
 ### Email
 Generators:
-- [Template](https://github.com/kamax-io/mxisd/blob/master/docs/threepids/email/notifications/template-generator.md)
+- [Template](https://github.com/kamax-io/mxisd/blob/master/docs/threepids/notifications/template-generator.md)
 
 Connectors:
-- [SMTP](https://github.com/kamax-io/mxisd/blob/master/docs/threepids/email/notifications/smtp-connector.md)
+- [SMTP](https://github.com/kamax-io/mxisd/blob/master/docs/threepids/medium/email/smtp-connector.md)
 
+#### MSISDN (Phone numbers)
+Generators:
+- [Template](https://github.com/kamax-io/mxisd/blob/master/docs/threepids/notifications/template-generator.md)
+
+Connectors:
+ - [Twilio](https://github.com/kamax-io/mxisd/blob/master/docs/threepids/medium/msisdn/twilio-connector.md) with SMS
 
 ## Usage
 ### Configuration
@@ -178,16 +184,6 @@ ID for each generator.
 In the above example, emails notifications are generated by the `example2` module and sent with the `example1` module.  
 By default, `template` is used as generator and `smtp` as connector.
 
-mxisd comes with the following IDs built-in:  
-**Connectors**
-- `smtp` for a basic SMTP connector, attempting STARTLS by default.
-See [the dedicated document](https://github.com/kamax-io/mxisd/tree/master/docs/threepids/email/notifications/smtp-connector.md)
-
-**Generators**
-- `template`, loading content from template files, using built-in mxisd templates by default.
-See [the dedicated document](https://github.com/kamax-io/mxisd/tree/master/docs/threepids/email/notifications/template-generator.md)
-for further configuration and customization options.
-
 ---
 
 `session.policy.validation` is the core configuration to control what users configured to use your Identity server

docs/threepids/medium/email/smtp-connector.md

@@ -1,5 +1,7 @@
 # Email notifications - SMTP connector
-The following configuration items are available:
+Connector ID: `smtp`
+
+Example configuration:
 ```
 threepid:
   medium:

docs/threepids/medium/msisdn/twilio-connector.md

@@ -0,0 +1,15 @@
+# SMS notifications - Twilio connector
+Connector ID: `twilio`
+
+Example configuration:
+```
+threepid:
+  medium:
+    msisdn:
+      connectors:
+        twilio:
+          accountSid: 'myAccountSid'
+          authToken: 'myAuthToken'
+          number: '+123456789'
+
+```

docs/threepids/notifications/template-generator.md

@@ -1,6 +1,6 @@
-# Email notifications: Generate from templates
+# Notifications: Generate from templates
-To create notification content, you can use the `template` generator which will read MIME email body, including headers,
+To create notification content, you can use the `template` generator if supported for the 3PID medium which will read
-encoded as UTF-8.
+content from configured files.
 
 Placeholders can be integrated into the templates to dynamically populate such content with relevant information like
 the 3PID that was requested, the domain of your Identity server, etc.
@@ -13,7 +13,7 @@ To configure paths to the various templates:
 ```
 threepid:
   medium:
-    email:
+    <YOUR 3PID MEDIUM HERE>:
       generators:
         template:
           invite: '/path/to/invite-template.eml'
@@ -22,16 +22,16 @@ threepid:
               local: '/path/to/validate-local-template.eml'
               remote: 'path/to/validate-remote-template.eml'
 ```
-The `template` generator is the default, so no further configuration is needed.
+The `template` generator is usually the default, so no further configuration is needed.
 
 ##  Global placeholders
 | Placeholder           | Purpose                                                                      |
 |-----------------------|------------------------------------------------------------------------------|
 | `%DOMAIN%`            | Identity server authoritative domain, as configured in `matrix.domain`       |
 | `%DOMAIN_PRETTY%`     | Same as `%DOMAIN%` with the first letter upper case and all other lower case |
-| `%FROM_EMAIL%`        | Email address configured in `threepid.medium.email.identity.from`            |
+| `%FROM_EMAIL%`        | Email address configured in `threepid.medium.<3PID medium>.identity.from`    |
-| `%FROM_NAME%`         | Name configured in `threepid.medium.email.identity.name`                     |
+| `%FROM_NAME%`         | Name configured in `threepid.medium.<3PID medium>.identity.name`             |
-| `%RECIPIENT_MEDIUM%`  | Set as `email`                                                               |
+| `%RECIPIENT_MEDIUM%`  | The 3PID medium, like `email` or `msisdn`                                    |
 | `%RECIPIENT_ADDRESS%` | The address to which the notification is sent                                |
 
 ## Events
@@ -43,14 +43,14 @@ This template is used when someone is invited into a room using an email address
 | `%SENDER_ID%`         | Matrix ID of the user who made the invite                                                |
 | `%SENDER_NAME%`       | Display name of the user who made the invite, if not available/set, empty                |
 | `%SENDER_NAME_OR_ID%` | Display name of the user who made the invite. If not available/set, its Matrix ID        |
-| `%INVITE_MEDIUM%`     | The 3PID medium for the invite. Always set to `email`                                    |
+| `%INVITE_MEDIUM%`     | The 3PID medium for the invite.                                                          |
 | `%INVITE_ADDRESS%`    | The 3PID address for the invite.                                                         |
 | `%ROOM_ID%`           | The Matrix ID of the Room in which the invite took place                                 |
 | `%ROOM_NAME%`         | The Name of the room in which the invite took place. If not available/set, empty         |
 | `%ROOM_NAME_OR_ID%`   | The Name of the room in which the invite took place. If not available/set, its Matrix ID |
 
 ### Local validation of 3PID Session
-This template is used when to user which added their email address to their profile/settings and the session policy
+This template is used when to user which added their 3PID address to their profile/settings and the session policy
 allows at least local sessions.  
 
 #### Placeholders
@@ -60,13 +60,14 @@ allows at least local sessions.
 | `%VALIDATION_TOKEN%` | The token needed to validate the local session, in case the user cannot use the link |
 
 ### Remote validation of 3PID Session
-This template is used when to user which added their email address to their profile/settings and the session policy only
+This template is used when to user which added their 3PID address to their profile/settings and the session policy only
 allows remote sessions.
 
 **NOTE:** 3PID session always require local validation of a token, even if a remote session is enforced.  
-One cannot bind a MXID to the session until the remote
+One cannot bind a MXID to the session until both local and remote sessions have been validated.
 
 #### Placeholders
 | Placeholder          | Purpose                                                |
-|--------------|--------------------------------------------------------|
+|----------------------|--------------------------------------------------------|
+| `%VALIDATION_TOKEN%` | The token needed to validate the session               |
 | `%NEXT_URL%`         | URL to continue with remote validation of the session. |