Message Delivery Usage

Introduction for Delayed Message Delivery

The following uses an MQTT device as an example to describe how to use a system topic to deliver messages to devices.

Figure 1 Process of delayed message delivery

1. An application or the third-party platform calls the API for delivering a message to a device to send a message to IoTDA. Example message:

   POST https://{Endpoint}/v5/iot/{project_id}/devices/{device_id}/messages
   Content-Type: application/json
   X-Auth-Token: ********
   
   {
     "message_id": "99b32da9-cd17-4cdf-a286-f6e849cbc364",  
     "name": "messageName",  
     "message": "HelloWorld"
   }

2. The platform sends a 201 Created message carrying the message status PENDING to the application.
3. The IoT platform pushes the message result to the application through the API for pushing a device message status change notification. If the device is offline, the message status is PENDING.

   Topic: $oc/devices/{device_id}/sys/messages/down  
   Data format:
   {  
       "resource": "device.message.status",  
       "event": "update",  
       "notify_data": {   
         "message_id": "string",   
         "name": "string",    
         "device_id": "string",    
         "status": "PENDING",   
         "timestamp": "string"  
        }
    }

4. The device goes online.
5. The device subscribes to the message delivery topic, which is used to receive messages. For details on the subscribed topic, see 6.
6. The platform sends the message to the device according to the protocol specifications. The MQTT device can receive messages delivered by the platform only after subscribing to the topic corresponding to the API Platform Delivering a Message. Example message:

   Topic: $oc/devices/{device_id}/sys/messages/down  
   Data format:
   {
       "object_device_id": "{object_device_id}",
       "name": "name",
       "id": "id",
       "content": "hello"
   }

7. The IoT platform pushes the final result of the message to the application. The message status is DELIVERED. For details about the used APIs, see Push a Device Message Status Change Notification.

   Topic: $oc/devices/{device_id}/sys/messages/down  
   Data format:
   {  
       "resource": "device.message.status",  
       "event": "update",  
       "notify_data": {   
         "message_id": "string",   
         "name": "string",    
         "device_id": "string",    
         "status": "DELIVERED",   
         "timestamp": "string"  
        }
    }

Introduction for QoS 1

The following uses an MQTT device as an example to describe how to use a system topic whose QoS is 1 to deliver messages to devices.

Figure 2 Process of using QoS 1 for message delivery

1. The device goes online.
2. Subscribe to a topic for the device and set QoS to 1.
   Figure 3 Setting QoS to 1 for the subscribed topic
   
3. An application or third-party platform calls the API for delivering a message to a device to send a message to IoTDA. Example message:

   POST https://{Endpoint}/v5/iot/{project_id}/devices/{device_id}/messages
   Content-Type: application/json
   X-Auth-Token: ********
   
   {
     "message_id": "99b32da9-cd17-4cdf-a286-f6e849cbc364",  
     "name": "messageName",  
     "message": "HelloWorld"
   }

4. The platform sends the message to the device according to the protocol specifications. The MQTT device can receive messages delivered by the platform only after subscribing to the topic corresponding to the API Platform Delivering a Message. Example message:

   Topic: $oc/devices/{device_id}/sys/messages/down  
   Data format:
   {
       "object_device_id": "{object_device_id}",
       "name": "name",
       "id": "id",
       "content": "hello"
   }

5. After delivering a message to the device, the IoT platform returns a 201 Created message to the application. The message status is DELIVERED. Message delivery is an asynchronous operation. The platform can return the response without waiting for an ACK message from the device.
6. If the IoT platform does not receive an ACK response from the device, it resends the message every 2 seconds for three times by default.
7. The device goes online again or subscribes to a topic.
8. If the device does not return an ACK response for the previous message and the message does not time out, the IoT platform resends the message every 10 seconds for five times by default. This mechanism of resending every 2 seconds is triggered.
9. The platform pushes the final message result to the application. The message status is DELIVERED or TIMEOUT. For details about the used APIs, see Push a Device Message Status Change Notification.

   Topic: $oc/devices/{device_id}/sys/messages/down  
   Data format:
   {  
       "resource": "device.message.status",  
       "event": "update",  
       "notify_data": {   
         "message_id": "string",   
         "name": "string",    
         "device_id": "string",    
         "status": "DELIVERED",   
         "timestamp": "string"  
        }
    }

Message Delivery Status

The following figure shows the MQTT device message execution status and status change mechanism.

Figure 4 Device message status