---
title: "system.util.sendMessage"
description: "This function sends a message to clients running under the Gateway, or to a project within the Gateway itself."
---

# system.util.sendMessage

> This function sends a message to clients running under the Gateway, or to a project within the Gateway itself.

This function is used in **Python Scripting**.

## Description
This function sends a message to clients running under the Gateway or to a project within the Gateway itself. To handle received messages, you must set up event script message handlers within a project. These message handlers run Jython code when a message is received. You can add message handlers under the [**Message**](../../../ignition-modules/perspective/scripting-in-perspective/perspective-session-events-scripts.md#message) section of the client/Gateway event script configuration dialogs. 

Messages cannot be received within a Designer. However, messages can be sent within the Designer in a script (assuming that read/write comm is enabled).

## Client Permission Restrictions
This scripting function has no [Client Permission](../../../ignition-modules/vision/vision-project-properties/vision-project-properties.md#vision-permissions-properties) restrictions.

## Syntax
`system.util.sendMessage(project, messageHandler, [payload], [scope], [clientSessionId], [user], [hasRole], [hostName], [remoteServers])`

### Parameters
Type | Parameter | Description 
------- | ------- | ------
String| `project` | The name of the project containing the message handler.
String| `messageHandler` | The name of the message handler that will fire upon receiving a message.
Dictionary[String, Any]| `payload` |  A dictionary which will get passed to the message handler. Use "payload" in the message handler to access dictionary variables. [optional]
String| `scope` | Limits the scope of the message delivery to "C" (clients), "G" (Gateway), "CG" for clients and the Gateway, or "S" Session. Any combination of C, G, and S are available. Defaults to "CS" if the user name, role, or host name parameters are set, and to "CGS" if none of these parameters are set. [optional]
String| `clientSessionId` | Limits the message delivery to a client with the specified session ID. [optional]
String| `user` | Limits the message delivery to clients where the specified user has logged in. [optional]
String| `hasRole` | Limits the message delivery to any client where the logged in user has the specified user role. [optional]
String| `hostName` | Limits the message delivery to the client that has the specified network host name. [optional]
List| `remoteServers` | A list of Strings representing Gateway Server names. The message will be delivered to each server in the list. Upon delivery, the message is distributed to the local Gateway and clients as per the other parameters. [optional]

### Returns
**List** - A List of strings containing information about each system that was selected for delivery, where each List item is comma-delimited.

### Scope
Gateway, Vision Client, Perspective Session 

## Code Examples

#### Example 1

```python title="Client and Gateway Scope Script"
# Simple message to both Client and Gateway handlers.
project="X"
# It's important that both Gateway and Client versions of this message handler have been created.
messageHandler="myMessageHandler"
scope="CG"
myDict = {'first': "Hello", 'second': "World"}
results=system.util.sendMessage(project,messageHandler,myDict,scope)
  
# Assuming that there is one local client running project X, the results List will contain these Strings:
#type=Gateway,project=X,messageHandler=testHandler,filterParams={hostName=, clientSessionId=, scope=CG, user=, hasRole=},sendStatus=SENT
 
#type=Client,sessionId=65F7A472,clientAddress=127.0.0.1,clientHostName=127.0.0.1,project=X,messageHandler=testHandler,filterParams={hostName=, clientSessionId=, scope=CG, user=, hasRole=},sendStatus=SENT
```

#### Example 2

```python title="Specified User Script"
# Message to client handlers only where a specified user is logged in.
system.util.sendMessage(project="X",messageHandler="myMessageHandler",scope="C",user="Bob")
```
#### Example 3

```python title="Remote Server Script"
# Message to remote servers over the Gateway Network (since 7.8.2).
servers = ["agent-8088", "agent-9000"]
system.util.sendMessage(project="X",messageHandler="myMessageHandler",remoteServers=servers)
```

#### Example 4 

The following example demonstrates how to trigger this function with a Tag Change Event.

1. Open the Project tab in the Designer and select **Session Events**.
2. On the Session Events screen, click **Message**.
3. Click the Add ![](sendMessageImgs/add.png) icon.
4. Enter **test** in the Message Handler Settings Name field.
5. Click **OK**.
6. Enter the following script and click **OK**.

    ```python title="Session Message Handler Script"
    def handleMessage(session, payload):
        system.util.getLogger("session event handler").info(str(payload))
    ```

    ![](sendMessageImgs/session-message-handlers.png)

7. Right-click on a tag in the Tag Browser that will be used to trigger the Tag Change Event and open the Tag Editor. In this example, our tag is a memory tag labeled test.   
8. Click **Scripting**. 
9. Click **Value Events** > **Value Changed**.
10. Enter the following script specifying the project, the message handler, payload, and scope. 

    ```python title="Value Changed Script"
    def valueChanged(tag, tagPath, previousValue, currentValue, initialChange, missedEvents):
        system.util.sendMessage(
            "Test",
            "test",
            {"cv": currentValue.value},
            scope="S"
        )
    ```

    ![](sendMessageImgs/tag-script.png)

11. Click **OK**.
12. Save your project. 

Now you can test this example, by launching your Perspective Session and changing the value of your tag. You'll see the messages appear on **Gateway Status** > **Diagnostics** > **Logs** page for each value change.

![](sendMessageImgs/logger-results.png)