- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# win_msg – Sends a message to logged in users on Windows hosts

- Synopsis

- Parameters

- Notes

- See Also

- Examples

- Return Values

- Status

## Synopsis

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

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
display_seconds integer | Default: 10 | How long to wait for receiver to acknowledge message, in seconds.
msg string | Default: "Hello world!" | The text of the message to be displayed. The message must be less than 256 characters.
to string | Default: "*" | Who to send the message to. Can be a username, sessionname or sessionid.
wait boolean | Choices: no ← yes | 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.

## 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

win_say – Text to speech module for Windows to speak messages and optionally play sounds

  The official documentation on the win_say module.

win_toast – Sends Toast windows notification to logged in users on Windows 10 or later hosts

  The official documentation on the win_toast module.

## Examples

    - name: Warn logged in users of impending upgrade
      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 | Returned | Description
--- | --- | ---
display_seconds string | success | Value of display_seconds module parameter. Sample: 10
msg string | changed | Test of the message that was sent. Sample: Automated upgrade about to start. Please save your work and log off before 22 July 2016 18:00:00
rc integer | always | The return code of the API call.
runtime_seconds string | success | How long the module took to run on the remote windows host. Sample: 22 July 2016 17:45:51
sent_localtime string | success | local time from windows host when the message was sent. Sample: 22 July 2016 17:45:51
wait boolean | success | Value of wait module parameter.

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]

- This module is maintained by the Ansible Community. [community]

### Authors

- Jon Hawkesworth (@jhawkesworth)

Hint

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