Alert wording
An alert says what happened twice: in English, in title and description, and language-neutral, in code and
params. Show an alert in your users' language from code and params; keep title for logs and for an alert
with no code. Never parse title or description: their words can change.
Both are on every alert from GET /v1/alerts and GET /v1/alerts/{id}, and in the data of the
zaitrack.alert.raised.v1 webhook:
{
"title": "Speeding: 133 km/h (limit 120 km/h)",
"description": "133 km/h (limit 120 km/h)",
"code": "speeding.over_limit",
"params": { "value": "133", "limit": "120" }
}
codeis<kind>.<what>. A code keeps its meaning once published; new codes are added as alerts learn to say new things.paramsholds the code's parameters, every value a string. A parameter marked optional below is left out when the event did not carry it.titleis the rule's name,:anddescription, unless the rule titles its alerts itself. To keep the rule's name (your user's own words) beside your wording, take thetitlebefore: <description>; whentitledoes not end so, show it as it is.- An alert raised before codes existed has
code""andparams{}: show itsdescription. - A code you do not know yet: show the alert's
description.
Parameter types
| Type | On the wire | Show it |
|---|---|---|
number | a plain decimal with Western digits: "52", "12.5" | in your users' digits, with the unit in the table |
instant | RFC 3339 in UTC: "2026-10-12T08:00:00Z" | in the organisation's time zone; where the vehicle reports another zone, add that zone's short name: 20:02 (UAE) |
day | a calendar day: "2026-12-31" | in your users' date format, as that day |
money | currency code and amount in its own decimals: "SAR 968.20" | in your users' number format, with the currency |
id | a code or reference: a job number, a card, a key | as it is, left to right |
text | words a person or another system wrote: a name, a place, a reason | as it is, quoted, in its own direction |
enum | one word of a fixed set (the set is named in brackets below) | translated; a word you do not know, as it is |
<kind>.other codes carry another system's own words in detail (a text); show them quoted.
Codes
The English is the reference wording. A part in [ ] is left out when a parameter in it is missing.
| Code | English | Parameters |
|---|---|---|
camera.blocked | Camera blocked: [camera {channel}] | channel number, optional |
camera.device_fault | Video device fault | |
camera.other | {fault}[ (camera {channel})] | fault id; channel number, optional |
camera.signal_lost | Video signal lost: [camera {channel}] | channel number, optional |
camera.storage_fault | Recorder storage fault | |
crash.detected | possible crash at {at}[, {speed} km/h][ ({lat}, {lon})] | at instant; speed number (km/h), optional; lat number (deg), optional; lon number (deg), optional |
dispatch.late | {job}[ ({reference})] stop {stop} {stopName} | job id; reference id, optional; stop number; stopName text |
dispatch.will_be_late | {job}[ ({reference})] stop {stop} {stopName} will be late: ETA {eta}, window ends {windowEnd} | job id; reference id, optional; stop number; stopName text; eta instant; windowEnd instant |
dispatch.window_missed | {job}[ ({reference})] stop {stop} {stopName} missed its window ending {windowEnd} | job id; reference id, optional; stop number; stopName text; windowEnd instant |
document.expired | [{subject}: ]{document}[ "{title}"][ {number}] expired on {on} | subject text, optional; subjectType enum [subject-type]; document enum [document-kind]; title text, optional; number id, optional; on day |
document.expires_in | [{subject}: ]{document}[ "{title}"][ {number}] expires in {days} days ({on}) | subject text, optional; subjectType enum [subject-type]; document enum [document-kind]; title text, optional; number id, optional; on day; days number (days) |
document.expires_on | [{subject}: ]{document}[ "{title}"][ {number}] expires on {on} | subject text, optional; subjectType enum [subject-type]; document enum [document-kind]; title text, optional; number id, optional; on day |
document.expires_today | [{subject}: ]{document}[ "{title}"][ {number}] expires today ({on}) | subject text, optional; subjectType enum [subject-type]; document enum [document-kind]; title text, optional; number id, optional; on day |
driver_key.blocked | blocked {keyKind} {key} presented ({detail}) | keyKind enum [key-kind]; key id; detail text |
driver_key.not_permitted | [{driver}: ]{keyKind} presented by a driver who may not drive ({detail}) | driver text, optional; keyKind enum [key-kind]; detail text |
driver_key.refused | the vehicle refused the driver of {keyKind} {key}: {detail} | keyKind enum [key-kind]; key id; detail text |
driver_key.unknown | unknown {keyKind} {key} presented — not a key the fleet gave a driver | keyKind enum [key-kind]; key id |
driver_safety.event | {event} ({camera} camera) | event enum [safety-event]; camera enum [camera] |
fuel.drain | {litres} l taken out of the tank while the vehicle stood ({before} l → {after} l, {from} – {to}) | litres number (l); before number (l); after number (l); from instant; to instant |
fuel.purchase_flagged | {litres} l for {amount}[ at {station}]: {summary} | litres number (l); amount money; station text, optional; summary text |
geofence.entered | entered geofence "{fence}" | fence text |
geofence.left | left geofence "{fence}" | fence text |
hos.other | Hours of service: {detail} | detail text |
idling.engine_on | engine on, not moving for over {minutes} min | minutes number (min) |
immobiliser.not_restored | back from service mode, the tracker's immobiliser is still off: {reason} | reason text |
inspection.defects | {defects} | worst enum [defect-severity]; inspection enum [inspection-kind]; count number; defects text |
inspection.unsafe | Not safe to operate. {defects} | worst enum [defect-severity]; inspection enum [inspection-kind]; count number; defects text |
low_voltage.below | supply voltage {value} V (minimum {min} V) | value number (V); min number (V) |
maintenance.due_soon | {plan} due soon[ at {dueKm} km][ at {dueHours} engine hours][ on {dueOn}] | plan text; dueKm number (km), optional; dueHours number (h), optional; dueOn day, optional |
maintenance.overdue | {plan} overdue[ at {dueKm} km][ at {dueHours} engine hours][ on {dueOn}] | plan text; dueKm number (km), optional; dueHours number (h), optional; dueOn day, optional |
offline.no_data | no data for {minutes} min (last report {last}) | minutes number (min); last instant |
screening.hit | {decision} {trigger} ({hits} new hit(s)): {summary} | decision enum [screening-decision]; trigger enum [screening-trigger]; hits number; summary text |
secure_trip.other | {route}[ ({reference})]: {detail} | route text; reference id, optional; detail text |
speeding.over_limit | {value} km/h (limit {limit} km/h) | value number (km/h); limit number (km/h) |
tachograph.infringement | card {card} ({severity}): {explanation} | card id; severity enum [tachograph-severity]; explanation text |
tire.condition | Tire[ {brand}][ {serial}][ at {position}]: {condition}[ ({value} {unit}, limit {limit} {unit})] | brand text, optional; serial id, optional; position id, optional; condition enum [tire-condition]; value number, optional; limit number, optional; unit id, optional |
toll.anomaly | {amount} at {gantry} ({issuer}): {summary} | amount money; gantry text; issuer text; summary text |
trailer.condition | {asset}[ ({ident})]: {condition} | asset text; ident id, optional; condition enum [trailer-condition] |
trailer.reefer_excursion | {asset}[ ({ident})]: reefer temperature out of range[ ({value} °C, limit {limit} °C)] | asset text; ident id, optional; value number (°C), optional; limit number (°C), optional |
trailer.seal_battery_low | {asset}[ ({ident})]: e-seal battery low[ ({value} %)] | asset text; ident id, optional; value number (%), optional |
trailer.unaccounted | {asset}[ ({ident})]: not reporting[ for {hours} h] | asset text; ident id, optional; hours number (h), optional |
Enum sets
| Set | Words |
|---|---|
camera | cab, road |
defect-severity | minor, major, critical |
document-kind | dangerous-goods, inspection-certificate, insurance, licence, medical, other, passport, professional-card, registration, residence-permit, road-permit |
inspection-kind | pre-trip, post-trip |
key-kind | ibutton, rfid |
safety-event | blind_spot, distracted, driver_abnormal, drowsy, fcw, ldw, obstacle, phone_use, road_sign, seatbelt_off, smoking, tailgate, unsafe_lane_change |
screening-decision | clear, warn, block |
screening-trigger | request, rescreen |
subject-type | driver, vehicle |
tachograph-severity | minor, serious, very-serious, most-serious, unclassified |
tire-condition | critical_pressure, high_temperature, low_pressure, low_tread, pressure_imbalance |
trailer-condition | moved_sealed, reefer_excursion, seal_battery_low, seal_opened, seal_tampered, unaccounted |