You are reading an unmaintained version of the Ansible documentation. Unmaintained Ansible versions can contain unfixed security vulnerabilities (CVE). Please upgrade to a maintained version. See the latest Ansible documentation.

community.windows.win_msg – Sends a message to logged in users on Windows hosts

Note

This plugin is part of the community.windows collection (version 1.8.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.windows.

To use it in a playbook, specify: community.windows.win_msg.

Synopsis

• Wraps the msg.exe command in order to send messages to Windows hosts.

Parameters

Parameter	Comments
display_seconds integer	How long to wait for receiver to acknowledge message, in seconds. Default: 10
msg string	The text of the message to be displayed. The message must be less than 256 characters. Default: “Hello world!”
to string	Who to send the message to. Can be a username, sessionname or sessionid. Default: “*”
wait boolean	Whether to wait for users to respond. Module will only wait for the number of seconds specified in display_seconds or 10 seconds if not specified. However, if wait is yes, the message is sent to each logged on user in turn, waiting for the user to either press ‘ok’ or for the timeout to elapse before moving on to the next user. Choices: no ← (default) yes

Notes

Note

• This module must run on a windows host, so ensure your play targets windows hosts, or delegates to a windows host.

• Messages are only sent to the local host where the module is run.

• The module does not support sending to users listed in a file.

• Setting wait to yes can result in long run times on systems with many logged in users.

See Also

See also

community.windows.win_say

The official documentation on the community.windows.win_say module.

community.windows.win_toast

The official documentation on the community.windows.win_toast module.

Examples

- name: Warn logged in users of impending upgrade
  community.windows.win_msg:
    display_seconds: 60
    msg: Automated upgrade about to start.  Please save your work and log off before {{ deployment_start_time }}

Return Values

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

Key	Description
display_seconds string	Value of display_seconds module parameter. Returned: success Sample: 10
msg string	Test of the message that was sent. Returned: changed Sample: “Automated upgrade about to start. Please save your work and log off before 22 July 2016 18:00:00”
rc integer	The return code of the API call. Returned: always Sample: 0
runtime_seconds string	How long the module took to run on the remote windows host. Returned: success Sample: “22 July 2016 17:45:51”
sent_localtime string	local time from windows host when the message was sent. Returned: success Sample: “22 July 2016 17:45:51”
wait boolean	Value of wait module parameter. Returned: success Sample: false

Authors

• Jon Hawkesworth (@jhawkesworth)