Wialon API Notifications: Create, Edit, Enable

Notifications are resource subitems rather than unit properties, and one command handles their entire lifecycle across four call modes. The two most-viewed notification questions on the Wialon SDK board both closed without a resolution, and both were shape problems rather than logic problems: which parameters a given call mode actually requires, and what comes back afterwards. This page covers the command, the fields that matter for each mode, and the three response fields that let an integration coexist with a customer editing the same rules by hand.

Send only the parameters the call mode expects

Every operation on a notification goes through one command, documented on the notifications page:

svc=resource/update_notification&params={
  "itemId":<long>,
  "id":<long>,
  "callMode":<text>,
  "e":<uint>,
  ...
}

The reference is precise about the rest, and this is where error 4 comes from: all other parameters are required only for creating and updating. A delete needs itemId, id and callMode and nothing else. An enable needs those three plus e. Sending the full body on a mode that does not want it produces an invalid-input error that names nothing, and the natural fix is to stop passing one object everywhere and write four small functions with four honest signatures instead of one that hopes the caller remembers which fields matter today.

Address the resource, not the unit

The first parameter is the one most often supplied wrongly on a first attempt, and the mistake is a reasonable guess rather than carelessness. Notifications are subitems of a resource, so itemId carries the resource identifier while the units the rule applies to arrive separately in the un array. A developer thinking in terms of “a notification about this vehicle” reaches for the unit id, gets an error that names nothing, and starts checking the rest of the payload.

The distinction has a practical consequence beyond the first failed call. Because the rule lives on the resource, a customer with several resources has several independent notification namespaces, and an integration that assumes one resource per account will silently manage only part of the estate. Enumerate resources before assuming where a rule should live, particularly on accounts that were set up by a partner rather than directly.

Define the rule once and bind it to many units

The create and update body carries the rule itself:

The behaviour lives in trg and act, and they share a shape: a type string plus a parameter object whose keys depend entirely on that type. The reference documents the available control types, action types and notification flags in its Notifications chapter rather than on the command page, so check there before hardcoding a type string — an unrecognised type produces another error 4 with no explanation of which field was wrong.

Because un is an array, a notification is defined once and bound to many units, which makes the natural way to manage a fleet-wide rule an update to that array rather than a notification per unit. Integrations that create one notification per unit reach the account’s notification limits far sooner than they need to, and they turn every subsequent rule change into a loop that can fail partway through and leave the fleet in two different states.

Satisfy both timing layers before expecting anything to fire

Timing is expressed twice, in two independent layers, and both have to permit an evaluation before a notification does anything at all. The activation window set by ta and td is absolute: those are UNIX timestamps rather than offsets or durations, so a notification created with a deactivation time already in the past is accepted, stored, and never fires once. Nothing in the response distinguishes it from a working rule.

The schedule in sch is the second layer, and it controls when the rule is evaluated within a day or a week, inside whatever calendar window ta and td describe. The two are combined rather than alternatives, which is why a rule that looks correct in the interface can still be dead — an activation window that expired last month, or a schedule that only covers hours the fleet does not operate in. When a notification is reported as not working, check both layers before looking at the trigger, because a mis-set timestamp is far more common than a mis-specified condition and much faster to rule out.

Use crc to notice a customer editing your rules

The response on create and edit returns the notification id followed by the stored object:

[
  <notification id>,
  {
    "id": <long>,
    "n": "<name>",
    "txt": "<text>",
    "ta": <uint>,
    "td": <uint>,
    "ma": <uint>,
    "fl": <uint>,
    "ac": <uint>,
    "un": [<long>],
    "act": ["<text>"],
    "trg": "<text>",
    "trg_p": { },
    "crc": <long>,
    "ct": <uint>,
    "mt": <uint>
  }
]

On delete, the second element is null.

Three of those fields do more work than their names suggest. The crc field is a checksum of the notification’s binary representation, which gives a cheap way to detect that a notification changed without comparing every field one by one — and that matters because the customer can edit the same rules in the web interface at any time, without telling anyone, while your integration continues to believe its own copy is authoritative. The mt field carries the last modification time and does the same job at coarser granularity, which is useful for ordering. And ac is the executions count, so a rule you believe in with an ac of zero is either mis-scoped or bound to no units at all, and the number tells you which conversation to have.

If an integration manages notifications from code while the customer also edits them by hand, store crc and mt alongside your own copy and reconcile them on a schedule. Without that reconciliation the two sides drift silently, and the first symptom is a rule that quietly stopped firing weeks earlier.

Disable rather than delete when a customer pauses a rule

One distinction is worth building into whatever interface you expose on top of this, because the API makes both operations equally easy and only one of them is reversible. Calling enable with e set to 0 keeps the definition intact and stops it firing, which is what a customer pausing a rule for a season or during a migration actually wants. Calling delete discards the definition and takes the checksum and the execution count with it, so the rule cannot be restored, compared against its previous form, or asked how often it used to fire.

The asymmetry matters most in bulk operations. A synchronisation routine that reconciles a customer’s rules against a definition in your own system will, at some point, encounter a rule it does not recognise — and the tempting implementation deletes it. Disabling instead leaves a recoverable state and a conversation, rather than a support ticket about rules that vanished overnight.

The two questions that motivated this page were “Error: 1 after trying to get notification_data” with 5,894 views and “Error 4 on svc=resource/update_notification” with 2,772, and both closed with two replies or fewer and no answer. The board is offline, every URL now redirects to the help.wialon.com root, and captured pages survive for roughly 61% of threads in the Wayback Machine.

• Pass itemId as the resource and put the units in un, not the other way round.
• Store crc and mt with your copy so an interface edit is detectable.
• Disable with callMode enable and e of 0 rather than deleting, unless the rule is genuinely gone for good.