Messages

The Immerse Platform and SDK allows messages to be sent to and from users in a session. This feature can also be used to preserve a session’s state.

Anatomy of a Message

Messages can contain a lot of information. We have designed them so that they are as flexible as possible. The developer has complete control over what goes in a message’s payload.

When receiving a message, a user is presented with a Message object which contains the following information.

Field	Description
MessageType	The message type as specified in your custom messages settings. Message type value must greater than 999. 0-999 are reserved for internal SDK use.
ID	The ID of the message. This can be used to send and persist multiple messages of the same type.
Sender	The ID of the user that sent the message.
Timestamp	A server-time timestamp in milliseconds.
PayloadLength	Returns the length of the message payload
Payload	This part of the message is whatever you want it to be (note that payload length is restricted to 1200 bytes).

The message ID is 16 bytes and can be used to serialize more information than a simple number

Example: Hello World

This is a simple example of how to send and receive a message. It consists of three main parts.

1. Define your Message

In the provided example we are using message type 1000.

Any ushort value greater than the reserved range of 0-999 can be used

To test this script, create a new Message Definition with the following configuration:

Message Type: 1000
Profile: Participant
Is Persisted: ❌
Broadcast to Self: ✔

2. Listen for Incoming Messages

It is important to listen for a message before you expect to receive it. In this example, we start listening immediately on Start. Here we register a handler HandleMessage for the message type. This method will be called each time we receive a message of the specified type.

3. Send a Message

To send a message, you must first be connected. In the example below we are using the Yield Instruction WaitForConnectionStatus to wait until we are connected to the multi-user service.

using System.Collections;
using System.Text;
using ImmerseSDK.PlatformServices;
using ImmerseSDK.PlatformServices.Multiuser;
using ImmerseSDK.PlatformServices.Multiuser.Messaging;
using UnityEngine;

public class HelloWorld : MonoBehaviour
{    
    [Tooltip("Message type to use")]
    public ushort MessageType = 1000;
 
    [Tooltip("The message we are sending")]
    public string MessageText = "Hello World";
    
    private IEnumerator Start()
    {
        // Start listening for incoming messages
        MessageRegistry.Register(MessageType, HandleMessage);
        
        // Wait until we are connected before attempting to send a message
        yield return new WaitForConnectionStatus(ConnectionStatus.Connected);
        SendMessage();
    }

    /// <summary>
    /// Send the message
    /// </summary>
    [ContextMenu("Send Message")]
    private void SendMessage()
    {
        // Encode MessageText to a byte array and send our message
        var payload = Encoding.UTF8.GetBytes(MessageText);
        Networking.Client.SendMessage(MessageType, default, payload);
        Debug.Log("Message Sent");
    }
    
    /// <summary>
    /// Handles incoming messages
    /// </summary>
    /// <param name="message">Message received</param>
    private void HandleMessage(Message message)
    {
        // GetPayloadAsString will read the payload as a UTF8 string
        var messageText = message.GetPayloadAsString(); 
        Debug.Log("Message Received: " + messageText);
    }
}