Message payload structuring

In Signaling, the built-in functionality enables you to send only string and binary messages. Although the SDK does not provide a built-in parsable and extensible message data structure, you can build your own structured message payload according to your business needs.

Some commonly used message types in Signaling scenarios are:

Plain text message: Contains text only.
Text message: Contains text and attachment URLs for images or files.
Video file message: Contains text description, video address, thumbnail address, and other related information.
Questionnaire and answer messages: Contains a question and preset answer options.
Invitation message: Invitation to join a private or group chat.
Signaling message: Invitation containing instructions to initiate a video or audio chat.
Command message: A control command message to a device in parallel driving, or a device status message uploaded by a sensor or an IoT application.
State synchronization messages: Position, viewpoint, or current status messages of a player in a game or metaverse.

Understand the tech

The message payload structure should be readable and extensible to reduce the cost of building and maintaining the app. A well-designed payload structure also facilitates compatibility between old and new versions during upgrades.

Consider an example where you send and receive the following types of message payloads through your Signaling app:

"This is a message!"
{message: "https://cdn.agora.io/assets/avatar.png"}
{message: { x = 10, y = 100, z = 55 } }

If your app receives a large number of such messages, it becomes difficult to determine if a particular message contains just text, a URL, or location information. If you scan all messages and check for substrings like https or x = , this approach becomes inefficient as the number of app users, message types, and the number of messages increase. To solve this problem, introduce predefined fields into your message payload structure to increase parsability and scalability. For example, add a type and other relevant fields to each message structure as follows:

Original message	Structured message
`"Hello, this is a message!"`	`{type: "text", message: "Hello, this is a message!"}`
`{message: "https://cdn.agora.io/assets/avatar.png"}`	`{type: "image", url: "https://cdn.agora.io/assets/avatar.png"}`
`{message: { x = 10, y = 100, z = 55 }}`	`{type: "position", coordinates: { x: 10, y: 100, z: 55 }}`

The type field enables you to identify the message format and parse the data in the message payload for different message types appropriately.

Signaling also provides the customType field in the publish and publishTopicMessage methods for sending additional custom message type information to the receiving end, along with the message. Use the customType field to identify the message type and parse the data in the message event.

String message = {
    "type": "image",
    "asset_url": "https://my.app/image.png",
    "thumb_url": "https://my.app/thumbnail/image.png",
    "mentionedUsers": ["Tony","Lily"],
    "sender": "Max"
};
// Send message with customType
PublishOptions options = new PublishOptions();
options.customType = "image";
mRtmClient.publish("channel_name", message, options, new ResultCallback<Void>() {
    @Override
    public void onSuccess(Void responseInfo) {
        log(CALLBACK, "send message success");
    }
    @Override
    public void onFailure(ErrorInfo errorInfo) {
        log(ERROR, errorInfo.toString());
    }
});
// When receiving a message, use the custom Type field to parse the message type
new RtmEventListener {
    @Override
    public void onMessageEvent(MessageEvent event) {
        log(INFO, "onMessageEvent");
        if (event.customType == "image") {
            log(INFO, "It is a image message!");
            // precess message
            log(INFO, "message: " + event.message.getData());
        }
    }
}

Sample message payload structures

This section provides some examples of parsable and extensible message structures commonly used in application scenarios. Customize these structures according to your business needs.

Text message

{
  "type": "text",
  "message": "This is a message",
  "mentionedUsers": ["Tony","Lily"],
  "sender": "Max"
}

Multilingual message

{
  "type": "translation",
  "message": {
        "en": "Hello",
        "zh": "你好",
        "jp": "こんにちは"
        },
  "mentionedUsers": ["Tony","Lily"],
  "sender": "Max"
}

Image attachment message

{
    "type": "attachment",
    "text": "Here is a image below!",
    "attachments": [
        {
            "type": "image",
            "asset_url": "https://bit.ly/2K74TaG",
            "thumb_url": "https://bit.ly/2Uumxti",
            "myCustomField": 123
        }
    ],
    "mentionedUsers": ["Tony","Lily"],
    "sender": "Max"
}

Picture message

{
  "type": "image",
  "asset_url": "https://my.app/image.png",
  "thumb_url": "https://my.app/thumbnail/image.png",
  "mentionedUsers": ["Tony","Lily"],
  "sender": "Max"
}

Video message

{
  "type": "video",
  "asset_url": "https://my.app/video.mp4",
  "thumb_url": "https://my.app/thumbnail/video.png",
  "mentionedUsers": ["Tony","Lily"],
  "sender": "Max"
}

Action prompt message

{
  "type": "action",
  "event": "Inputting",
  "sender": "Max"
}

Chat invitation message

{
  "type": "chatInvite",
  "channel": "this is the channel you are being invited to",
  "message": "Hi Tony, welcome to the team!"
}

Video call message

{
  "type": "chatInvite",
  "session": "your_video_session",
  "message": "Hi Tony, welcome to the video chat!",
  "sender": "Max"
}

Questionnaire message

{
  "type": "poll",
  "question": "Which option is right?",
  "answers":{
      "A": "Apple",
      "B": "Banana",
      "C": "Blackberry"
        },
  "sender": "Max"
}

Status synchronization message

{
  "type": "position",
  "question": "Which option is right?",
  "data":{
      "coordinate": { "x": 10, "y": 100, "z": 55 },
      "direction": {"pitch": 30, "roll" : 90, "yaw": 80}
        },
  "mentionedUsers": ["Tony","Lily"],
  "sender": "Max"
}

To convert the message payload structure to a string or binary type to meet the requirements for sending messages in Signaling, see Message payload serialization.