Messages

This page describes the formats of all message types. You can request messages of a specific type using flags.

For how to specify flags in requests, see Data format.

Each message also contains the tns field (<long>): the message time in nanoseconds (UTC). In Wialon Local, the tns field is available starting from version 2604.

The following message types are available:

To delete a message, use the messages/delete_message method. You can delete only the messages of a unit. The access right to the unit that you need depends on the message flag f. The conditions are checked in the following order:

You can’t delete the last message or the last position of a unit. In this case, error 4 is returned.

The deletion of a task isn’t recorded in the unit log.

For further information about ACL flags, see the Access flags section.

All message types except tasks contain the rt parameter, which stores the time when the server registered the message (UTC). It’s filled in for the messages that come from a unit, such as data messages and command results. It’s also filled in for events. In log records and messages about triggered notifications, rt is 0.

The flag of data messages is 0x0000 (0).

{
    "t": <uint>,       // Message time (UTC)
    "f": <uint>,       // Flags (see below)
    "tp": "ud",        // Message type ('ud' denotes a data message)
    "pos": {           // Location. null if the message contains no location data
        "y": <double>, // Latitude
        "x": <double>, // Longitude
        "z": <int>,    // Altitude
        "s": <uint>,   // Speed
        "c": <uint>,   // Course
        "sc": <ubyte>  // Number of satellites
    },
    "i": <uint>,       // Input data. Present only if the flag 0x02 is set
    "o": <uint>,       // Output data. Present only if the flag 0x04 is set
    "dr": <text>,      // Driver code. Present only if the flag 0x20 is set
    "p": {             // Parameters
        <text>: <double>
        ...
    },
    "sensors": {       // Present only when the calcSensors parameter is used
        "<sensor_id>": {
            "value": <double|text>,  // Raw sensor value
            "format": {
                "value": <text>      // Formatted sensor value with units
            }
        }
    },
    "lc": <int>,       // LBS message checksum
    "rt": <uint>       // Message registration time (UTC)
}

The sensors object is present only if the request contains the calcSensors parameter with a value other than 0. This parameter is accepted by the messages/load_interval and render/get_messages methods.

Sensor values are calculated only from data messages. In the messages of the other types, the sensor formulas get no data, so a numeric sensor returns -348201.3876 and a text sensor returns "---".

Data message flags:

The flag of SMS messages is 0x0100 (256).

{
    "t": <uint>,   // Message time (UTC)
    "f": 256,      // Flags: 256 (0x0100) denotes an SMS message
    "tp": "us",    // Message type ('us' denotes an SMS message)
    "st": <text>,  // Message text
    "mp": <text>,  // Modem phone number
    "rt": <uint>,  // Message registration time (UTC)
    "p": {}        // Parameters
}

The flag of commands is 0x0200 (512).

{
	"t": <uint>,	// Message time (UTC)
	"f": 512,	// Flags: 512 (0x0200) denotes a command
	"tp": "ucr",	// Message type ('ucr' denotes a command)
	"ca": <text>,	// Command name
	"cn": <text>,	// Command type
	"cp": <text>,	// Command parameters
	"ui": <long>,	// User ID
	"ln": <text>,	// Link name
	"lt": <text>,	// Link type
	"et": <uint>,	// Execution time
	"rt": <uint>,	// Message registration time (UTC)
	"p": {}		    // Parameters
}

Link types are described on the Update command definition page.

The flag of events is 0x0600 (1536).

{
	"t": <uint>,    // Message time (UTC)
	"f": <uint>,    // Flags (see below)
	"tp": "evt",    // Message type ('evt' denotes an event)
	"et": <text>,   // Event text
	"x": <double>,  // Longitude. 0 if the event has no position
	"y": <double>,  // Latitude. 0 if the event has no position
	"rt": <uint>,   // Message registration time (UTC)
	"p": {                         // Parameters
		"evt_name": <text>,        // Event name
		"evt_sub_type": <uint>,    // Event subtype (see below)
		"evt_reg_type": <uint>,    // Registration type (see below)
		"executed_branch": <text>, // Conditions that were met, joined by AND
		...
	}
}

Event flags:

If f is 0, the event is a simple event.

The evt_name, evt_sub_type, and evt_reg_type parameters are present in most events. They’re absent in the events registered by the unit/registry_insurance_event method and in the events that the unit/update_traffic_counter method registers when it resets the traffic counter.

The executed_branch parameter is present only in the events registered by notifications, by route control, and by the unit/registry_maintenance_event, unit/registry_fuel_filling_event, and unit/registry_charge_event methods. The events registered by the unit/registry_status_event and unit/registry_custom_event methods don’t contain it. The executed_branch parameter isn’t available in Wialon Local.

The other parameters depend on what registered the event.

For the values of evt_sub_type, see Event and task subtypes. For the values of evt_reg_type, see Event and task registration types.

In events registered before tasks were separated from events, the evt_name, evt_sub_type, and evt_reg_type parameters are named task_evt_name, task_sub_type, and task_reg_type. For details, see Tasks no longer tied to registered events.

The executed_branch parameter is absent in events registered before the notification system was updated. For details, see Notification system redesign.

The flag of online notifications is 0x0300 (768).

An online notification is created by the Display online notification in a pop-up window action. Unlike a message about a triggered notification, it isn’t stored on the server and is delivered only to the session as an event.

To receive online notifications, subscribe to the resource with the messages flag 0x00000020 (32) using core/update_data_flags and read the events with avl_evts. The event comes from the resource, not from the unit.

{
	"t": <uint>,                // Message time (UTC)
	"f": <uint>,                // Flags (see below)
	"tp": "unm",                // Message type
	"name": <text>,             // Notification name
	"txt": <text>,              // Notification text
	"color": <text>,            // Notification color in HTML notation, for example, #ff9a05
	"url": <text>,              // URL address of the notification sound
	"unit": <long>,             // ID of the unit for which the notification was triggered
	"blink": <uint>,            // Mini-map blinking when triggered: 1 — enabled, 0 — disabled
	"x": <double>,              // Longitude
	"y": <double>,              // Latitude
	"expression": <text>,       // Conditions of the notification, joined by AND and OR, for example, speed AND geozone
	"executed_branch": <text>,  // Conditions that were met, joined by AND. A part of expression
	"nid": <long>,              // Notification ID
	"rt": <uint>,               // Message registration time (UTC)
	"p": {}                     // Parameters
}

Unlike other message types, an online notification stores its parameters in the root of the object, and the p object is always empty.

All the parameters are always present in the message. If a value isn’t set, a text parameter is empty and a number is 0. If the message that triggered the notification has no coordinates, both x and y are 0.

The value of f is always 0x380 (896): 0x0300 (768) for the message type and 0x80 (128) for a message that isn’t stored on the server.

To get the full configuration of the notification, pass nid to the resource/get_notification_data method.

The messages/load_interval and messages/load_last methods never return messages of this type. To get the stored records of triggered notifications for a time period, use the flag 0x4000 (16384) described in Message about a triggered notification.

The flag of user log records is 0x0400 (1024). These records store the login and logout history of a user. They belong to a user, not to a unit or a resource.

{
	"t": <uint>,       // Message time (UTC)
	"f": 1024,         // Flags: 1024 denotes a user log record
	"tp": "xx",        // Message type
	"rt": <uint>,      // Message registration time (UTC)
	"p": {             // Parameters
		"type": <text>,     // Record type (see below)
		"host": <text>,     // Host from which the user connected
		"service": <text>,  // Service where the session was opened
		"app": <text>,      // Application where the session was opened
		"sid": <text>       // Session ID, 32 characters
	}
}

All the parameters are always present.

Record types:

The service and app parameters contain the name of the service or the application where the session was opened, for example, web/hosting.wialon.com for the web interface or hst-api.wialon.com for a request to the API. In a record of the login type, both parameters always contain the same value. In a record of the logout type, they come from different sources and can differ.

In a record of the logout type, t is the time of the last activity in the session, not the time when the session ended.

A record of the login type doesn’t always have a matching record of the logout type.

To get these records, use messages/load_interval or messages/load_last with the user ID in the itemId parameter, 0x0400 (1024) in the flags parameter, and 0xFF00 (65280) in the flagsMask parameter. You need the Request reports and messages 0x200 (512) access right to the user.

To receive new records as events, subscribe to the user with the messages flag 0x00000020 (32) using core/update_data_flags and read the events with avl_evts.

To get the records of the actions performed with an item, use the Log record message type.

The flag of billing messages is 0x0500 (1280).

{
	"t": <uint>,	// Message time (UTC)
	"f": <uint>,	// Flags: 0x1 is set when the message contains payment information
	"tp": "xx",	    // Message type
	"rt": <uint>,	// Message registration time (UTC)
	"p": {}		    // Parameters
}

The flag of SMS messages to and from the driver is 0x0900 (2304). Messages in both directions have this type. The flag 0x1 in the f parameter is set if the message is sent to the driver and isn’t set if the message is received from the driver.

{
	"t": <uint>,      // Message time (UTC)
	"f": <uint>,      // Flags: 0x1 is set for a message sent to the driver
	"tp": "xx",       // Message type
	"rt": <uint>,     // Message registration time (UTC)
	"p": {            // Parameters
		"phone": <text>,        // Driver phone number
		"sms_text": <text>,     // SMS text
		"driver_name": <text>,  // Driver name
		"driver_id": <uint>,    // Driver ID
		"modem_phone": <text>   // Modem phone number. Present only in messages received from the driver
	}
}

The flag of log records is 0x1000 (4096).

{
	"t": <uint>,      // Message time (UTC)
	"f": <uint>,      // Flags (see below)
	"tp": "xx",       // Message type
	"rt": <uint>,     // Message registration time (UTC)
	"p": {            // Parameters
		"user": <text>,       // Name of the user who performed the action
		"action": <text>,     // Action ID
		"host": <text>,       // Host from which the action was performed
		"p1": <text>,         // Action-specific parameter
		"p2": <text>,         // Action-specific parameter
		"p3": <text>,         // Type of the item, for example, avl_unit
		...
	}
}

In the response, the value of f doesn’t depend on the action. For units, it is always 0x1FE12 (130578). For all other items, it is always 0x1000 (4096).

Don’t use 0x1FE12 (130578) in requests. To request log records of any item, specify 0x1000 (4096) in the flags parameter and 0xFF00 (65280) in the flagsMask parameter.

The available action IDs and their parameters (p1, p2) are described on the item/add_log_record page.

To get the login and logout history of a user, use the User log message type.

To receive log records, you need two access rights: Request reports and messages 0x200 (512) to call messages/load_interval or messages/load_last, and Manage object log 0x800 (2048) to the item you request. Without the Manage object log right, the response contains no log records, and no error is returned. For the full list of rights, see the Access flags section.

The flag of video usage messages is 0x2000 (8192). These messages record the video traffic of a unit.

Video usage messages are available only in Wialon Hosting.

The device doesn’t send these messages. The server collects the records of the video service and stores them in the message history of the unit every 15 minutes, so a message can appear with such a delay. The time of the message is the time of the video traffic record, not the time when the server stored it.

{
	"t": <uint>,          // Message time (UTC)
	"f": 8192,            // Flags: 8192 denotes a video usage message
	"tp": "xx",           // Message type
	"rt": <uint>,         // Message registration time (UTC)
	"p": {                // Parameters
		"cha_n": <uint>,     // Camera channel number
		"bytes_in": <long>,  // Amount of video traffic in bytes
		"action": <uint>,    // Operation that used the traffic (see below)
		"conn_id": <uint>,   // Connection ID assigned by the video service
		"hw_id": <long>      // ID of the hardware type of the unit
	}
}

All the parameters are always present.

The action parameter shows which operation used the traffic and which codec the video uses:

The available values depend on the codec supported by the device of the unit.

Several messages can have the same conn_id if one connection produced several records of traffic. The video service numbers connections with a counter that starts over when the service restarts, so don’t use conn_id as a unique key.

The cha_n parameter contains the number of the camera channel reported by the device. The numbering comes from the protocol of the device, so it can differ between hardware types. To get the names of the cameras configured for a unit, use the unit/get_video_settings method.

The hw_id parameter contains the same value as the hw property of the unit, which is described in Advanced properties. To get the name of the hardware type by this value, use the core/get_hw_types method.

The system adds up the bytes_in values of a unit to calculate its video traffic consumption.

To get these messages, use messages/load_interval or messages/load_last with the unit ID in the itemId parameter, 0x2000 (8192) in the flags parameter, and 0xFF00 (65280) in the flagsMask parameter. You need the Request reports and messages 0x200 (512) access right to the unit. The rights to video data aren’t required.

These messages appear only for the units with video monitoring enabled. To enable video billing for a unit, use the unit/update_video_status method.

WLN messages have the following format:

REG;time;lon;lat;speed;course;double params;int params;text params;long params;boolean params;

Inside the section, the parameters are separated by commas. Example:

REG;1466585078;30.4367027283;59.7207145691;1;273;ALT:24.0,adc1:0.0,adc2:25.57,adc3:0.0,adc4:0.0,adc5:0.0,adc6:0.0,fuel1:0.0,fuel2:170.0,fuel3:0.0,odometer:7293607.0,acc:0.0,pwr_int:0.731,pwr_ext:25.751,hdop:1.7;in13:1,,SATS:5,count1:1,count2:0,temp1:0,temp2:23,temp3:0,sats_glonass:0,sats_gps:5;soft_version:"44";;;

When a notification is triggered, the system stores a message with flag 0x4000 (16384). These messages contain detailed information about the notification trigger event.

To get these messages, use messages/load_interval or messages/load_last with 0x4000 (16384) in the flags parameter and 0xFF00 (65280) in the flagsMask parameter. Don’t use 0x4000 as the mask: it also matches tasks, because their flag 0x5000 contains the same bit.

{
	"t": <uint>,      // Trigger time (UTC)
	"f": 16384,       // Flags: 16384 denotes a triggered notification
	"tp": "xx",       // Message type
	"rt": <uint>,     // Message registration time (UTC)
	"p": {            // Parameters
		"name": <text>,             // Notification name
		"resource_id": <uint>,      // ID of the resource where the notification is configured
		"trigger_type": <text>,     // Trigger type, for example, speed, geozone, or expression
		"actions": <text>,          // Action types, separated by commas, for example, message,event
		"unit_id": <uint>,          // ID of the unit for which the notification was triggered
		"text": <text>,             // Notification message text
		"trigger_time": <uint>,     // Trigger time (UTC)
		"alarm_msg_time": <uint>,   // Time of the message that triggered the notification (UTC). 0 if there was no such message
		"notification_id": <uint>,  // Notification ID
		"x": <double>,              // Longitude. Present only if the message that triggered the notification has a position
		"y": <double>,              // Latitude. Present only if the message that triggered the notification has a position
		"expression": <text>,       // Conditions of the notification, joined by AND and OR, for example, speed AND geozone. Can be empty
		"executed_branch": <text>,  // Conditions that were met, joined by AND. A part of expression
		"account_id": <uint>        // ID of the account of the resource. Absent if the resource has no billing account
	}
}

The notification_id, expression, and executed_branch parameters are absent in messages registered before the notification system was updated. They aren’t available in Wialon Local. For the changes in the notification system, see Notification system redesign.

The flag of tasks is 0x5000 (20480).

In Wialon Local, task messages are available starting from version 2504.

{
	"t": <uint>,                      // Message time (UTC)
	"f": 20480,                       // Flags: 20480 denotes a task
	"tp": "task",                     // Message type
	"task_id": <text>,                // Task ID
	"p": {                            // Parameters
		"task_id": <text>,            // Task ID
		"task_sub_type": <uint>,      // Task subtype. A number or a text (see below)
		"task_reg_type": <uint>,      // Registration type (see below)
		"task_account": <long>,       // ID of the account or of the user who created the unit (see below)
		"task_status": <uint>,        // Task status (see below)
		"task_description": <text>,   // Task description
		"task_priority": <uint>,      // Task priority (see below)
		"task_assignee": <long>,      // ID of the user the task is assigned to. 0 if the task isn't assigned
		"task_evt_name": <text>,      // Task name
		"task_tags": <text>,          // Text with a JSON object which contains the tags of the notification that created the task. Empty for tasks created manually
		"task_comments": [            // Comments
			{
				"id": <uint>,             // Comment ID
				"timestamp": <uint>,      // Time when the comment was added (UTC)
				"assignee": <long>,       // ID of the user who added the comment
				"last_edited_by": <long>, // ID of the user who edited the comment last
				"last_edit_time": <uint>, // Time of the last edit (UTC)
				"comment": <text>         // Comment text
			}
		],
		"task_update_time": <uint>,   // Time of the last update (UTC). 0 for a task registered by a notification and never updated
		"task_address_x": <double>,   // Longitude. 0 if the task has no position
		"task_address_y": <double>,   // Latitude. 0 if the task has no position
		"task_done_rejected": <uint>, // Time when the task was done or rejected (UTC). 0 for the other statuses
		"task_params": {              // Additional task parameters. Each parameter is present only if its value is set
			"filled": <double>,       // Amount of fuel filled
			"charged": <double>,      // Amount of energy charged
			"cost": <double>,         // Task cost
			"engine_hours": <double>, // Engine hours
			"mileage": <double>,      // Mileage
			"duration": <uint>        // Duration in seconds
		}
	}
}

Unlike other message types, a task message has no rt parameter. The messages/get_task_messages method returns the same p object, but instead of tp and task_id it returns the item_id parameter with the ID of the unit.

The task_account parameter depends on how the task was created: for a task created manually, it contains the ID of the account the unit belongs to (the bact property of the unit), and for a task registered by a notification, the ID of the user who created the unit (the crt property). For details about these properties, see Billing information.

The task_tags parameter is a text, not an object. It contains {} if the notification has no tags, and it’s empty for the tasks created manually.

The comments are returned in the order in which they were passed in the last unit/update_task request. Don’t rely on them being sorted by id or by timestamp.

Task statuses:

Task priorities:

For the values of task_sub_type and task_reg_type, see Event and task subtypes and Event and task registration types.

In the responses of messages/get_task_messages and in avl_evts events, the filled and mileage values are in the measurement system of the unit, which is set in its mu property. For details, see General properties. In the responses of messages/load_interval and messages/load_last, these values are always in the metric system (SI): liters and kilometers.

Tasks are created by the unit/create_task method and by the Create task action of a notification. To change the status, the priority, the assignee, or the comments of a task, use the unit/update_task method.

To get the tasks of a unit for a time period, use the messages/get_task_messages method. To receive new tasks as events, subscribe to the unit with the tasks flag 0x01000000 (16777216) using core/update_data_flags and read the events with avl_evts.

In both cases, you need the View object and its basic properties 0x1 (1) and Request reports and messages 0x200 (512) access rights to the unit, and the Tasks service must be enabled and active for the account.

You can also load the tasks of one unit with messages/load_interval or messages/load_last. To do this, specify 0x5000 (20480) in the flags parameter and 0xFF00 (65280) in the flagsMask parameter. You need the Request reports and messages 0x200 (512) access right to the unit.

The evt_sub_type parameter of an Event and the task_sub_type parameter of a Task have the same set of values.

For events and tasks registered by a notification, the subtype corresponds to the control type of the notification:

For an event registered by a notification, the control type is also available as text in the avl_trigger_type parameter.

For events and tasks registered by other sources, the subtype shows the source:

The values 22, 23, and 26 are used when a fuel filling, a battery charge, or a maintenance service is registered directly, without a notification. When the same event is registered by a notification, the subtype is 7 or 20.

The task_sub_type parameter of a task can contain either a number or a text value, so process both types.

In the accounts with the updated notification system (for details, see Notification system redesign), the text value is returned instead of the number. For a task registered by a notification, it contains the conditions that were met, joined by AND, the same as in the executed_branch parameter of an Event. For example, outage for a connection loss notification, or speed AND driver_unassigned for a notification with several conditions. For the names of the conditions which can be combined in one notification, see Supported condition types. Notifications with several conditions aren’t available in Wialon Local.

For the other tasks, including the tasks created manually and the tasks registered before the notification system was updated, the text value is formed from the numeric subtype. If a numeric subtype covers several conditions, the names are joined by OR.

The subtypes 24, 25, 27, 28, and 29 have no text value and are always returned as numbers. The subtype 32 (a combination of several conditions) is returned as a number only for the tasks registered before the notification system was updated.

This applies only to tasks. The evt_sub_type parameter of an Event is always a number.

The evt_reg_type parameter of an event and the task_reg_type parameter of a task show how the event or the task was registered: 1 for manually, 2 for automatically.