Imou Event Message Format: Which Alarms Include Images and Which Do Not

Do not expect picUrlArray in every Imou event. The live event-format documentation shows image arrays for specific face-detection and face-comparison payloads, while the general device alarm, device online/offline, gateway accessory, traffic, heatmap, sharing, binding, and authorization examples do not define that field. Parse by msgType and documented payload family, not one universal schema.

Why It Matters

An integration that makes picUrlArray mandatory will reject valid image-free events or show broken thumbnails. The opposite assumption is also risky: an event with an image URL may need prompt retrieval and official decryption handling. Your event model should preserve the original payload, identify its documented family, and make image processing conditional.

The authoritative boundary is the current event message format definition. It demonstrates multiple schemas rather than promising a single envelope with every field.

Architecture

callback receiver
  -> validate common routing fields where present
  -> classify documented payload family / msgType
  -> persist raw event
  -> if documented image field exists and is populated:
       enqueue image retrieval and approved decryption
     else:
       continue image-free workflow

Schema differences are visible in the official examples:

Documented payload family	Image field shown in its example?	Integration consequence
General device alarm	No picUrlArray	Do not reject motion or other general alarms for lacking an image
Device online/offline	No	Model this as status data, not media
Gateway accessory	No	Read family-specific desc fields only when documented
Face detection (aiFaceDetect)	Yes, picUrlArray	Treat URLs as conditional media references
Acquaintance/stranger face comparison	Yes, picUrlArray	Process according to that exact schema
Traffic statistics	No	Consume detail statistics, not snapshots
Heatmap	No	Consume documented desc heat data
Sharing, binding, unbinding, transfer, authorization changes	No	Handle as account/device lifecycle notifications

“No” means the current example does not define picUrlArray; it is not a claim that no future or device-specific variant can ever carry media. The live page must be rechecked when implementing a specific msgType.

Implementation Steps

1. Subscribe only to needed categories. Configure callbacks with setMessageCallback using documented flags.
2. Store the raw body before transformation. This supports troubleshooting when a newly observed documented shape differs from your normalized model.
3. Classify the message. Use the documented msgType and the payload family’s identifiers. Do not assume every family uses the same device or channel field names.
4. Validate family-specific required fields. For example, the general alarm example uses did and cid, while face examples use deviceId and channelId. Keep adapters separate.
5. Test for image presence conditionally. An image worker should run only if the relevant documented image field exists, is an array, and contains usable URLs.
6. Retrieve media promptly when applicable. The face-message examples state that image data on the platform has a maximum storage time of one day and advise saving it to the developer server as soon as possible. Do not convert that note into a universal retention or SLA claim for every event.
7. Use the official image-decryption path. Alarm thumbnails and covers can be encrypted. Use the platform-provided component or OpenSDK utility rather than treating every downloaded object as a browser-ready JPEG.

APIs and Official Documentation

• Event message format definition: canonical examples for general alarms, status, accessories, face events, statistics, heatmaps, and account/device lifecycle notifications.
• Event message type definition: documented event types; consult it instead of inventing msgType values.
• getAlarmMessage: queries alarm records for a device channel and may return picurlArray and thumbUrl in alarm records.
• Resource download: lists the official Image Decryption Demo and server-side component.

Notice the exact casing: callback examples use picUrlArray for certain face payloads, while getAlarmMessage documents picurlArray. Preserve the field name defined by each interface rather than normalizing before parsing.

Limits and Pitfalls

A selected alarm callback does not guarantee a picture. Many ordinary motion or human-related alarms may arrive without picUrlArray. Device capabilities, event type, configuration, and applicable services affect available media.

Do not infer schema from one sample. The event page deliberately presents different envelopes. A parser requiring appId, did, deviceId, cid, and channelId simultaneously will manufacture failures.

Do not equate push payloads with query responses. getAlarmMessage is a separate HTTP interface with its own fields and pagination. It can help retrieve documented alarm records, but it does not prove that every pushed event has an image or a matching query result.

Do not publish signed URLs. Image references can contain access material. Redact query strings from logs and support tickets, restrict stored media, and apply your own retention and access controls.

Do not rename fields silently. Keep a raw payload and versioned adapters. If your internal model uses imageUrls, record whether it came from picUrlArray, picurlArray, or another documented source.

Do not decode encrypted bytes as ordinary JPEG. A URL ending in an image-like suffix does not establish that the returned bytes are directly displayable. Follow the official decryption component and key-management guidance; never expose device security keys to a browser or public repository.

Do not promise image completeness. A robust UI should show an event without a thumbnail, display a clear “image unavailable” state, and keep the event useful through its type, time, device, and channel data.

Register at Imou Open Platform to explore cloud-video and AIoT APIs and SDKs, and validate each event family against current official schemas before making images part of your product contract.