From 1e77bf43c6c09e8b0ad76f82f25c2ddd2d1e734f Mon Sep 17 00:00:00 2001 From: Maxime Dor Date: Mon, 25 Sep 2017 17:03:50 +0200 Subject: [PATCH] Add documentation to validate phone numbers --- docs/sessions/3pid.md | 20 +++++------- .../email}/smtp-connector.md | 4 ++- .../medium/msisdn/twilio-connector.md | 15 +++++++++ .../notifications/template-generator.md | 31 ++++++++++--------- 4 files changed, 42 insertions(+), 28 deletions(-) rename docs/threepids/{email/notifications => medium/email}/smtp-connector.md (88%) create mode 100644 docs/threepids/medium/msisdn/twilio-connector.md rename docs/threepids/{email => }/notifications/template-generator.md (72%) diff --git a/docs/sessions/3pid.md b/docs/sessions/3pid.md index 1e6293c..b456bcc 100644 --- a/docs/sessions/3pid.md +++ b/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 diff --git a/docs/threepids/email/notifications/smtp-connector.md b/docs/threepids/medium/email/smtp-connector.md similarity index 88% rename from docs/threepids/email/notifications/smtp-connector.md rename to docs/threepids/medium/email/smtp-connector.md index 8bff396..6aa686d 100644 --- a/docs/threepids/email/notifications/smtp-connector.md +++ b/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: diff --git a/docs/threepids/medium/msisdn/twilio-connector.md b/docs/threepids/medium/msisdn/twilio-connector.md new file mode 100644 index 0000000..3840ffc --- /dev/null +++ b/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' + +``` diff --git a/docs/threepids/email/notifications/template-generator.md b/docs/threepids/notifications/template-generator.md similarity index 72% rename from docs/threepids/email/notifications/template-generator.md rename to docs/threepids/notifications/template-generator.md index 04b6548..e2acc0a 100644 --- a/docs/threepids/email/notifications/template-generator.md +++ b/docs/threepids/notifications/template-generator.md @@ -1,6 +1,6 @@ -# Email notifications: Generate from templates -To create notification content, you can use the `template` generator which will read MIME email body, including headers, -encoded as UTF-8. +# Notifications: Generate from templates +To create notification content, you can use the `template` generator if supported for the 3PID medium which will read +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: + : 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_NAME%` | Name configured in `threepid.medium.email.identity.name` | -| `%RECIPIENT_MEDIUM%` | Set as `email` | +| `%FROM_EMAIL%` | Email address configured in `threepid.medium.<3PID medium>.identity.from` | +| `%FROM_NAME%` | Name configured in `threepid.medium.<3PID medium>.identity.name` | +| `%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 | -|--------------|--------------------------------------------------------| -| `%NEXT_URL%` | URL to continue with remote validation of the session. | +| Placeholder | Purpose | +|----------------------|--------------------------------------------------------| +| `%VALIDATION_TOKEN%` | The token needed to validate the session | +| `%NEXT_URL%` | URL to continue with remote validation of the session. |