Updated Notify_msteams (markdown)

Notify_msteams.md

@@ -45,6 +45,7 @@ Valid syntax is as follows:
 | tokenA      | Yes      | The first part of 3 tokens provided to you after creating a *incoming-webhook*
 | tokenB      | Yes      | The second part of 3 tokens provided to you after creating a *incoming-webhook*
 | tokenC      | Yes      | The last part of 3 tokens provided to you after creating a *incoming-webhook*
+| template    | No       | Optionally point to your own custom JSON formatted Microsoft Teams **MessageCard**; [See here for details on their formatting](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using).
 
 #### Example
 Send a Microsoft Teams notification:
@@ -55,3 +56,125 @@ Send a Microsoft Teams notification:
 apprise -vv -t "Test Message Title" -b "Test Message Body" \
    msteams:///T1JJ3T3L2@DEFK543/A1BRTD4JD/TIiajkdnlazkcOXrIdevi7F/
 ```
+
+## Templating
+### The `template` URL Argument
+Define a `?template=` argument that points to a predefined **MessageCard** you've already prepared for Microsoft Teams.  The `template` parameter can either point to a local file or a web based URL.  It's contents must be JSON (or you'll get an error trying to process it), and it at the very minimum must have the basic pattern: 
+```json
+{
+  "@type": "MessageCard",
+  "@context": "https://schema.org/extensions"
+}
+```
+
+#### The Template Tokens
+The `template=` you point to, can either be fully populate and ready to go as is (up to the MSTeams chat server), or you can dynamically populate it on the fly each time you call Apprise. You do this by using the double curly brace `{{` and `}}` to surround a keyword that you invent; here is an example:
+```json
+{
+  "@type": "MessageCard",
+  "@context": "https://schema.org/extensions",
+  "summary": "{{app_id}}",
+  "sections": [
+    {
+        "activityImage": "{{app_image_url}}",
+        "activityTitle": "{{app_title}}",
+        "text": "Hello {{ target }}, how are you {{ whence }}?"
+    }
+  ]
+}
+```
+
+In the above example, we introduce several tokens... `app_id`, `app_title`, `target` and `whence`.  There are a few entries that will ALWAYS be set and you can not over-ride them. They are:
+* **app_id**: The Application identifier; usually set to `Apprise`, but developers of custom applications may choose to over-ride this and place their name here.  this is how you acquire this value.
+* **app_desc**:  Similar the the Application Identifier, this is the Application Description. It's usually just a slightly more descriptive alternative to the *app_id*.  This is usually set to `Apprise Notification` unless it has been over-ridden by a developer.
+* **app_color**: A hex code that identifies a colour associate with a message.  For instance, `info` type messages are generally blue where as `warning` ones are orange, etc.
+* **app_type**: The message type itself; it may be `info`, `warning`, `success`, etc
+* **app_title**: The actual title (`--title` or `-t` if from the command line) that was passed into the apprise notification when called.
+* **app_body**: The actual body (`--body` or `-b` if from the command line)  that was passed into the apprise notification when called.
+* **app_image_url**: The image URL associated with the message type (`info`, `warning`, etc) if one exists and/or was not specified to be turned off from the URL (`image=no`)
+* **app_url**: The URL associated with the Apprise instance (found in the **AppriseAsset()** object).  Unless this has been over-ridden by a developer, it's value will be `https://github.com/caronc/apprise`.
+
+Anything you invent outside of that is yours.  So lets get back to the `target` and `whence` that was define. Template tokens can be dynamically set by using the colon `:` operator before any URL argument you identify.  For example we can set these values on our Apprise URL like so:
+* `msteams://credentials/?template=/path/to/template.json&:target=Chris&whence=this%20afternoon`
+* `msteams://credentials/?template=http://host/to/template.json&:target=Chris&whence=this%20afternoon`
+
+A notification like so:
+```bash
+# using colons, we can set our target and whence dynamically from the
+# command line:
+apprise -t "My Title" -b "This is Ignored" \
+   "msteams://credentials/?template=http://host/to/template.json&:target=Chris&whence=this%20afternoon"
+```
+Would post to MSTeams (with respect to our template above):
+```json
+{
+  "@type": "MessageCard",
+  "@context": "https://schema.org/extensions",
+  "summary": "Apprise",
+  "sections": [
+    {
+        "activityImage": null,
+        "activityTitle": "My Title",
+        "text": "Hello Chris, how are you this afternoon?"
+    }
+  ]
+}
+```
+
+The default Apprise template today (and still has no change even after this commit looks like this):
+```json
+# Prepare our payload
+payload = {
+  "@type": "MessageCard",
+  "@context": "https://schema.org/extensions",
+  "summary": "{{app_desc}}",
+  "themeColor": "{{app_color}}",
+  "sections": [
+    {
+        "activityImage": null,
+        "activityTitle": "{{app_title}}",
+        "text": "{{app_body}}"
+    }
+  ]
+}
+```
+
+#### Other Template Examples:
+```json
+{
+  "@type": "MessageCard",
+  "@context": "https://schema.org/extensions",
+  "summary": "{{app_desc}}",
+  "themeColor": "{{app_color}}",
+  "sections": [
+    {
+      "activityImage": null,
+      "activityTitle": "{{app_title}}",
+      "text": "{{app_body}}",
+    },
+  ],
+ "potentialAction": [{
+
+        "@type": "ActionCard",
+        "name": "Add a comment",
+        "inputs": [{
+            "@type": "TextInput",
+            "id": "comment",
+            "isMultiline": false,
+            "title": "Add a comment here for this task"
+        }],
+        "actions": [{
+            "@type": "HttpPOST",
+            "name": "Add comment",
+            "target": "{{ target }}"
+        }]
+ }]
+}
+```
+
+#### Additional Template Notes
+* Tokens can have white space around them for readability if you like.  Hence `{{ token }}` is no different then `{{token}}`. 
+* All tokens are escaped properly, so don't worry if your defined token has a double quote in it (`"`); it would be correctly escaped before it is sent upstream.
+* Tokens ARE case sensitive, so `{{Token}}` NEEDS to be populated with a `:Token=` value on your URL.
+* Tokens that are not matched correctly simply are not swapped and the {{keyword}} will remain as is in the message.
+* Apprise always requires you to specify a `--body` (`-b`) at a very minimum which can be optionally referenced as `{{app_body}}` in your template.  Even if you choose not to use this token, you must still pass in something (anything) just to satisfy this requirement and make use of the template calls.