Message Relay Message Format Specification

Overview

This document specifies the JSON message format for relay messages used in uplink (device to backend) and downlink (backend to device) communications between Satellite devices and the enterprise backend system.

Note: We use UTF-8 Encoding.

Downlink messages

Downlink messages (backend to device) can be either sent based on the recipient's IMSI or phone number

Base Downlink Message Structure

Field	Type	Required	Description
recipient	DownlinkRecipient	Yes
timestamp	int32	Yes	Unix timestamp in seconds
senderPhoneNumber	string	No (required if the chat feature is enabled)	Phone number of the sender

DownlinkRecipient

Field	Type	Required	Description
type	"PhoneNumber" / "IMSI"	Yes	Identifier type
number	string	Yes	Phone number or IMSI

Text Message

Field	Type	Required	Description
type	"Text"	Yes
payload	string	At least one of payload or location must be present	Plain text message content
location	Location	At least one of payload or location must be present	Current device location

Sample Downlink Message (backend to device)

Request:

{
  "recipient": {
    "type": "IMSI",
    "number": "123456789012345"
  },
  "timestamp": 1742308785,
  "type": "Text",
  "payload": "Please reply back with your location"
}

Response:

{
  "messageId": "0003505dcb762d67d8cde52d0002"
}

CloseSOS

Field	Type	Required	Description
type	"CloseSOS"	Yes

DeviceStatusRequest

Field	Type	Required	Description
type	"DeviceStatusRequest"	Yes
alertUser	int8	Yes	Number of alerts (0 = silent, N = N alerts)

Uplink messages

Base Uplink Message Structure

Field	Type	Required	Description
messageId	string	Yes	Unique message identifier
sentVia	"Satellite" / "Internet"	Yes	Channel the uplink message was sent through
sender	string	No (required if the chat feature is enabled)	The phone number of the message sender
imsi	string	No (required if the chat feature is disabled)	The IMSI of the user's current device
timestamp	int32	Yes	Unix timestamp in seconds

Text Message

Field	Type	Required	Description
type	"Text"	Yes
recipient	string	No	Receiver mobile with country code (or "000000" for SOS)
payload	string	At least one of payload or location must be present	Plain text message content
location	Location	At least one of payload or location must be present	Current device location

Sample Text Uplink Message (device to backend)

{
  "messageId": "0003505dcb762d67d8cde52d0001",
  "sentVia": "Satellite",
  "sender": "14045550000",
  "imsi": "123456789012345",
  "timestamp": 1742308785,
  "type": "Text",
  "payload": "I have reached the summit",
  "location": {
    "latitude": 12.121,
    "longitude": 12.11
  }
}

StartTracking

Uplink-only message to inform backend of a tracking session.

Field	Type	Required	Description
type	"StartTracking"	Yes
duration	int16	Yes	Session duration in minutes
frequency	int16	Yes	Reporting frequency in seconds
location	Location	Yes	Starting location
accuracy	int8	Yes	Required accuracy in meters

Sample StartTracking Uplink Message (device to backend)

{
  "messageId": "0003505dcb762d67d8cde52d0001",
  "sentVia": "Satellite",
  "sender": "14045550000",
  "imsi": "123456789012345",
  "timestamp": 1742308785,
  "type": "StartTracking",
  "duration": 60,
  "frequency": 180,
  "location": { "latitude": 12.121, "longitude": 12.11 },
  "accuracy": 15
}

TrackLocation

Uplink-only message for reporting tracking points.

Field	Type	Required	Description
type	"TrackLocation"	Yes
sessionEnd	boolean	Yes	true if this is the final message in the session
locations	LocationWithTimestamp[]	Yes	Array of location points

Sample TrackLocation Uplink Message (device to backend)

{
  "messageId": "0003505dcb762d67d8cde52d0001",
  "sentVia": "Satellite",
  "imsi": "123456789012345",
  "timestamp": 1742308785,
  "type": "TrackLocation",
  "sessionEnd": false,
  "locations": [
    {
      "latitude": 12.121,
      "longitude": 12.11,
      "accuracy": 20,
      "timestamp": 1742308782
    },
    {
      "latitude": 12.121,
      "longitude": 12.12,
      "accuracy": 10,
      "timestamp": 1742308775
    }
  ]
}

OpenSOS

Uplink-only message to initiate an SOS alert.

Field	Type	Required	Description
type	"OpenSOS"	Yes
reason	int8	Yes	Alert reason code (see reason codes table below)
location	Location	Yes	Current location
message	string	No	Optional additional details

Reason Codes: It is up to the client to decide what the reason codes correspond to. Below is just a demonstration of what they can mean.

Code	Description
0	None
1	Fire Alert
2	No Fuel
3	Safety Concern
4	Medical
...	...

CloseSOS

Message to end an SOS session.

Field	Type	Required	Description
type	"CloseSOS"	Yes

DeviceStatusResponse

Sent in response to a DeviceStatusRequest.

Field	Type	Required	Description
type	"DeviceStatusResponse"	Yes
batteryHealth	int8	Yes	Battery life percentage (0-100)
appConnection	boolean	Yes	Status of connection to companion app
location	LocationWithAccuracy	No	Current location

Custom Message

Flexible binary payload for custom enterprise or application-specific messaging.

Note: The payload structure and interpretation are defined by the client application. The Enterprise BSS functions solely as a transparent transport mechanism, requiring client-side handling for both sending and receiving directions.

Field	Type	Required	Description
type	"CustomMessage"	Yes
data	string	Yes	hex encoded binary data

Common Structures

Location

Basic location structure:

Field	Type	Required	Description
latitude	float32	Yes
longitude	float32	Yes

LocationWithAccuracy

Extended location structure with accuracy:

Field	Type	Required	Description
latitude	float32	Yes
longitude	float32	Yes
accuracy	int8	Yes	Accuracy in meters

LocationWithTimestamp

Complete location structure for tracking:

Field	Type	Required	Description
latitude	float32	Yes
longitude	float32	Yes
accuracy	int8	Yes	Accuracy in meters
timestamp	int32	Yes	Unix timestamp in seconds