device.message.list (Receive alarm messages)

device.message.list: Receive alarm messages

This page covers real-time push. For history list, search, detail, and delete, see Query alarm history, Search messages by type, Query one alarm message, and Delete alarm messages. If motion detection is off or the device is disarmed, you may see no data—follow Capability usage · first end-to-end run to enable motion detection.

Method	API	Type name
Real-time push	Set callback	After subscribing to `capabilityEvent`, `msgType` is e.g. `detection.motion.detected`
Active query	`device.message.list` / `search` / `detail` / `delete`	Returned `msgType` matches push

Real-time push

Configure callback URL with setMessageCallback; query the current config with getMessageCallback.
Add capabilityEvent to callbackFlag (comma-separated with alarm, deviceStatus, etc.).
Callback HTTP body is the report payload below—the same shape as msgBody where pull is not offered overseas. Return an HTTP 2xx success response (200 is typical); status codes 200–399 count as success. Signing and health checks: Push configuration and Receive device messages.

If callbackFlag includes alarm or deviceStatus, payloads use did, cid, and a string msgType (not an eventId). See Event message types and Event message format.

After capabilityEvent subscription, capability events use msgType such as detection.motion.detected; property changes use device.property.report. Query APIs also return count / nextAlarmId—do not confuse that response JSON with this push payload.

Detection alarms often include thumbnail and alarm images; linked cloud recording adds token. Fields aiCopyWriting, securityRiskLevel, and aiTag appear only with Smart View cloud storage or AI Smart View plans. This push payload has no feedback (history APIs only).

Name	Type	Description
`msgType`	String	Equals `eventId`, e.g. `detection.motion.detected`
`deviceId`	String	Device serial number
`productId`	String	Model
`channelId`	String	Channel-level events; omitted on device-level
`outputData`	Object	Event-specific fields; `{}` when none (each event page documents this part)
`time`	Int	Report time, Unix seconds
`localTime`	String	Device local `yyyyMMddTHHmmss`
`alarmId`	String	Alarm id for detail / delete / paging
`token`	String	Present when linked cloud recording is available
`thumbUrl`	String	Thumbnail; returned when image exists
`picUrlArray`	Array	Alarm frames; expire—copy promptly
`labelType`	String	Message type label
`aiCopyWriting`	String	Smart View copy when plan is active
`securityRiskLevel`	String	Smart View only; push may be numeric string `1`–`10`; history APIs may normalize to level text
`aiTag`	String	Smart View only; push may be JSON array; history may normalize to a single tag string

{
 "msgType": "detection.motion.detected",
 "deviceId": "TESTIPC000012345",
 "productId": "56WGTET2",
 "channelId": "0",
 "outputData": {
 "extendContext": {
 "handleBit": 1
 }
 },
 "time": 1673406989,
 "localTime": "20230111T111629",
 "alarmId": "116257862023505xxxx",
 "token": "f2dc8c09eeae4b5bad6abf522c93d825",
 "thumbUrl": "https://example.imou.com/pic/thumb.jpg",
 "picUrlArray": [
 "https://example.imou.com/pic/frame1.jpg",
 "https://example.imou.com/pic/frame2.jpg"
 ],
 "labelType": "humanAlarm",
 "aiCopyWriting": "A man in black clothes rode past the store",
 "securityRiskLevel": "1",
 "aiTag": "person,vehicle"
}

Active query

Paginate by time: device.message.list (message-list · HTTP API message list). Search by labelType: device.message.search (message-search). Same v2 source as the alarm index.

These APIs query capability event history only. Legacy alarm / deviceStatus real-time payloads are in Receive device messages.

Example for POST https://openapi-[DataCenter].easy4ip.com/openapi/v2/device.message.list—see message-list page.

beginTime / endTime are device-local yyyyMMddTHHmmss, e.g. 20201022T000000.

{
 "id": "d5c287b4-5b2f-4f03-baf5-8032c5c354af",
 "system": {
 "ver": "1.0",
 "appId": "lcdxxxxxxxxx",
 "sign": "xjhCQBoJ9hRDsCjyDcHjtDNzRZ3ZJezcawsfWeiaoxU=",
 "time": 1706511734,
 "nonce": "f5a1ae2d-c09c-4d39-a744-83a5c2c653c2"
 },
 "params": {
 "token": "<yourAccessToken>",
 "deviceId": "TESTIPC000012345",
 "channelId": "0",
 "beginTime": "20201022T000000",
 "endTime": "20201022T235959",
 "nextAlarmId": "-1"
 }
}

Response messages[]: capability events have msgType equal to eventId. Page with nextAlarmId. Type search: Search messages by type. Single message: Query one alarm message. Delete: Delete alarm messages.

Unauthorized events are filtered out of list/search—not a whole-call DV2011.

Motion detection fields and legacy push names: Motion detection alarm. All events: Event types.