# mattermost – Send Mattermost notifications

- Synopsis
- Parameters
- Examples
- Return Values
- Status

## Synopsis

- Sends notifications to http://your.mattermost.url via the Incoming WebHook integration.

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
api_key - / required |  | Mattermost webhook api key. Log into your mattermost site, go to Menu -> Integration -> Incoming Webhook -> Add Incoming Webhook. This will give you full URL. api_key is the last part. http://mattermost.example.com/hooks/`API_KEY`
channel - |  | Channel to send the message to. If absent, the message goes to the channel selected for the api_key.
icon_url - | Default: "https://www.ansible.com/favicon.ico" | Url for the message sender's icon.
text - / required |  | Text to send. Note that the module does not handle escaping characters.
url - / required |  | Mattermost url (i.e. http://mattermost.yourcompany.com).
username - | Default: "Ansible" | This is the sender of the message (Username Override need to be enabled by mattermost admin, see mattermost doc.

validate_certs
boolean

Choices:
- no
- yes ←

If `no`, SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates.

## Examples

    - name: Send notification message via Mattermost
      mattermost:
        url: http://mattermost.example.com
        api_key: my_api_key
        text: '{{ inventory_hostname }} completed'

    - name: Send notification message via Mattermost all options
      mattermost:
        url: http://mattermost.example.com
        api_key: my_api_key
        text: '{{ inventory_hostname }} completed'
        channel: notifications
        username: 'Ansible on {{ inventory_hostname }}'
        icon_url: http://www.example.com/some-image-file.png

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Returned | Description
--- | --- | ---
payload string | success | Mattermost payload
webhook_url string | success | URL the webhook is sent to

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

- Benjamin Jolivot (@bjolivot)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.