Mattermost: Add sending of attachments (#3946)

* Add sending of attachments

* Change required arguments and add changelog

- text was still default -> changed to required_one_of text or attachments
- Add version_added
- Add changelog fragment for mattermost attachments

Co-Authored-By: Felix Fontein <felix@fontein.de>

* Fix wrong indentation

* Add trailing comma

Co-authored-by: Felix Fontein <felix@fontein.de>

* Remove default=None

Co-authored-by: Felix Fontein <felix@fontein.de>

* Fix sentence

Co-authored-by: Felix Fontein <felix@fontein.de>

Co-authored-by: Felix Fontein <felix@fontein.de>

changelogs/fragments/3946-mattermost_attachments.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - mattermost - add the possibility to send attachments instead of text messages (https://github.com/ansible-collections/community.general/pull/3946).

plugins/modules/notification/mattermost.py

@@ -38,7 +38,15 @@ options:
     type: str
     description:
       - Text to send. Note that the module does not handle escaping characters.
-    required: true
+      - Required when I(attachments) is not set.
+  attachments:
+    type: list
+    elements: dict
+    description:
+      - Define a list of attachments.
+      - For more information, see U(https://developers.mattermost.com/integrate/admin-guide/admin-message-attachments/).
+      - Required when I(text) is not set.
+    version_added: 4.3.0
   channel:
     type: str
     description:
@@ -76,6 +84,22 @@ EXAMPLES = """
     channel: notifications
     username: 'Ansible on {{ inventory_hostname }}'
     icon_url: http://www.example.com/some-image-file.png
+
+- name: Send attachments message via Mattermost
+  community.general.mattermost:
+    url: http://mattermost.example.com
+    api_key: my_api_key
+    attachments:
+      - text: Display my system load on host A and B
+        color: '#ff00dd'
+        title: System load
+        fields:
+          - title: System A
+            value: "load average: 0,74, 0,66, 0,63"
+            short: True
+          - title: System B
+            value: 'load average: 5,16, 4,64, 2,43'
+            short: True
 """
 
 RETURN = '''
@@ -99,12 +123,16 @@ def main():
         argument_spec=dict(
             url=dict(type='str', required=True),
             api_key=dict(type='str', required=True, no_log=True),
-            text=dict(type='str', required=True),
+            text=dict(type='str'),
             channel=dict(type='str', default=None),
             username=dict(type='str', default='Ansible'),
             icon_url=dict(type='str', default='https://www.ansible.com/favicon.ico'),
             validate_certs=dict(default=True, type='bool'),
-        )
+            attachments=dict(type='list', elements='dict'),
+        ),
+        required_one_of=[
+            ('text', 'attachments'),
+        ],
     )
     # init return dict
     result = dict(changed=False, msg="OK")
@@ -115,7 +143,7 @@ def main():
 
     # define payload
     payload = {}
-    for param in ['text', 'channel', 'username', 'icon_url']:
+    for param in ['text', 'channel', 'username', 'icon_url', 'attachments']:
         if module.params[param] is not None:
             payload[param] = module.params[param]