From 8684de02cbaace20c85312c8438209c090c40bf3 Mon Sep 17 00:00:00 2001
From: reshetnik-alexey <oleksii.reshetnik@gmail.com>
Date: Thu, 27 Jan 2022 00:38:29 +0530
Subject: [PATCH] feat: added SMS configuration documentation

---
 docs/docs/concepts/email-sms.md | 99 +++++++++++++++++++++++++--------
 1 file changed, 75 insertions(+), 24 deletions(-)

diff --git a/docs/docs/concepts/email-sms.md b/docs/docs/concepts/email-sms.md
index 2353746f536a..af7488cca94d 100644
--- a/docs/docs/concepts/email-sms.md
+++ b/docs/docs/concepts/email-sms.md
@@ -112,44 +112,95 @@ courier:
 
 ## Sending SMS
 
-For sending SMS Ory Kratos requires an external SMS gateway, which must be able
-to satisfy the HTTP contract. The address of the SMS gateway endpoint must be
-set in the configuration file. Please note that it needs to be absolute, start
-with http:// or https:// scheme, and include path part - e.g.
-"https://api.sender.com/v1/message".
+For sending SMS Ory Kratos uses an external SMS gateway, which must have HTTP API
+(such as Twilio, your local SMS sender, or your own microservice). Request method,
+headers, body, and content-type are fully configurable using options below.
+
+### Configuration
+
+Default configuration of Ory Kratos does not include sending SMS. To enable it you
+need to set "enabled" flag to true, sender URL, authorization (if needed)
+and request body format.
+
+#### Sender phone number
+
+SMS message will come to the recipient from this phone number. Depending on your SMS sender
+settings you can use letters here (for example "Your Org Name").
+Default value is equal to "Ory Kratos".
 
 ```yaml title="path/to/my/kratos/config.yml"
 # $ kratos -c path/to/my/kratos/config.yml serve
 courier:
   sms:
-    host: https://api.sender.com/v1/message
+    from: '+12065550110'
 ```
 
-### HTTP API contract
-
-Kratos will send a POST request to the endpoint set in the config for phone
-verification and recovery (note that recovery using SMS is currently not
-implemented). Post request body has urlencoded format, and contains three
-parameters - "To", "From", and "Body". To - phone number of the recipient.
-From - configurable sender name. Body - SMS text. It will contain a link or OTP
-code for verification(in progress).
-
-Authorization with third party SMS gate via access tokens are not implemented
-yet.
-
-### Sender name
-
-The recipient of an email will see this as the sender’s address. You can
-customize the sender name for SMS by overriding the "from_name" config property.
-Default sender name is equal to "Kratos".
+#### Request configuration
 
 ```yaml title="path/to/my/kratos/config.yml"
 # $ kratos -c path/to/my/kratos/config.yml serve
 courier:
   sms:
-    from_name: 'Your Org Name'
+    request_config:
+      url: https://api.twilio.com/2010-04-01/Accounts/YourAccountID/Messages.json
+      method: POST
+      body: file://./path/to/path/to/my/kratos/config/twilio.request.jsonnet
+      header:
+        'Content-Type': "application/x-www-form-urlencoded"
+      auth:
+        type: basic_auth
+        config:
+          user: YourUsername
+          password: YourPass
+```
+
+The configuration consists of:
+
+- `url` - the URL, which should be called (mandatory). It needs to be absolute,
+  start with http:// or https:// scheme, and include path part - e.g.
+  "https://api.sender.com/v1/message".
+- `method` - the HTTP method (GET, POST, ...) (mandatory)
+- `body` - URI of a JsonNet template, used to render the payload
+  to send (optional). Use a `file://path/to/body.jsonnet` URL for referring to
+  local files. This property is ignored for HTTP `method`s, which do not support
+  sending of HTTP body payloads (TRACE).
+- `auth` - configuration of authentication and authorization mechanisms to be
+  used by request
+
+Courier binds the `From`, `To`, and `Body` variables into the JsonNet template.
+These variables are available through a `ctx` object. E.g. to create a body
+looking like `{ To: <some-number> }` to be sent to the SMS provider endpoint,
+the jsonnet template would look like this:
+`function(ctx) { To: ctx.To }`
+
+
+#### Authentication and Authorization
+
+
+For `auth` following mechanisms are supported:
+
+- Authentication via an Api Key. Type must be set to `api_key`.
+- Authentication via Basic Authentication. Type must be set to `basic_auth`.
+
+For `api_key` the config looks as follows:
+
+```yaml
+name: Some-Name
+value: The-Value-of-My-Key
+in: header # alternatively cookie
+```
+
+All properties are mandatory.
+
+For `basic_auth` the config looks as follows:
+
+```yaml
+user: My-User
+password: My-Pass-Value
 ```
 
+All properties are mandatory.
+
 ## Message templates
 
 Ory Kratos comes with built-in templates. If you wish to define your own, custom