Skip to main content
Android
iOS
macOS
Web
Linux C++
Unity

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 messageStructured 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.


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

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


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

Multilingual message


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

Image attachment message


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

Picture message


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

Video message


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

Action prompt message


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

Chat invitation message


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

Video call message


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

Questionnaire message


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

Status synchronization message


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

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.

Signaling