Message Center

Last Updated on : 2023-10-09 01:57:20download

API list

`Action`	Description
message.checkNew	Determine whether user has unread messages
message.alarmGroupList	Query alert group
message.alarmList	Query list of alerts
message.homeList	Query list of messages for home
message.notificationList	Query list of notifications
message.deleteAlarmGroup	Delete alert group
message.deleteById	Delete details of messages
message.readAlarmGroup	Mark alert group as read

Determine whether user has unread messages

API description

Determines whether a user specified by user ID has unread messages. These messages are classified into three types.

API endpoint

action: message.checkNew

Request parameter

Parameter name	Parameter type	Description	Required
uid	String	The user’s unique identifier.	Yes

Response parameter

Parameter name	Type	Description
code	Integer	The response code. For more information, see Error codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result. Valid values: `alarm`: alert. `home`: message for a home. `notification`: notification. `true`: The user has unread messages. `false`: The user does not have any unread message.

Sample request

{
  "action": "message.checkNew",
  "params": {
    "uid": "ay15742xxxxx"
  }
}

Sample response

{
    "success":true,
    "t":1540799929837,
    "result":{
      "alarm":false,
      "home":true,
      "notification":false
    }
}

Error codes

The following table lists common error codes for the API calls. For more error codes, see Global Error Codes.

Error codes	Description
500	A system error has occurred while processing your request.
1106	Invalid permission.

Query alert group

API description

Get a group of alerts for a specified user. The result is returned on pages. The alerts are aggregated based on a device or a statistical model. You can further call alarmList to get the details of these alerts.

API endpoint

action: message.alarmGroupList

Request parameter

Parameter name	Parameter type	Description	Required
uid	String	The user’s unique identifier.	Yes
time_zone_id	String	The time zone ID. Only `Asia/Shanghai` is supported.	Yes
page_no	Integer	The page number, starting from `1`. Default value: `1`.	No
page_size	Integer	The number of entries returned per page. Default value: `15`. Maximum value: `100`.	No

Response parameter

Parameter name	Type	Description
code	Integer	The response code. For more information, see Error codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

Description of result

Parameter name	Type	Description
messages	List	The list of aggregated alerts.
page_no	Integer	The total number of returned pages.
total_count	Integer	The total number of returned entries.

Description of messages

Parameter name	Type	Description
id	Long	The ID of the alert group.
date_time	String	The time when the alert was generated.
read_status	Integer	The status that indicates whether a message has been read. `0`: unread. `1`: read.
home_id	Integer	The ID of the home to which a message belongs.
home_name	String	The name of the home to which a message belongs.
icon	String	The recommended icon.
message_content	String	The content of the alert.
message_title	String	The title of the alert.
message_group_id	String	The ID of the alert group. This parameter is required to query the details of alerts and delete an alert group.

Sample request

{
  "action": "message.alarmGroupList",
  "params": {
    "uid": "ay1578921339xxxxxxxx",
    "time_zone_id": "Asia/Shanghai"
  }
}

Sample response

{
    "success": true,
    "t":1540799929837,
    "result": {
        "messages":[
        {
            "id":556446,
            "date_time":"2020-8-11 19:59",
            "read_status":0,
            "home_id":10694416,
            "home_name":"My Home",
            "icon":"https://images.tuyacn.com/smart/icon/axxxxxxlV6/5yyyyyyyy42dd.png",
            "message_content":"Test of brightness alert",
            "message_group_id":"vdexxxxxx6223",
            "message_title":"Test of brightness alert"
        },
        {
            "id":547450,
            "date_time":"2020-8-10 05:59",
            "read_status":0,
            "home_id":10694416,
            "home_name":"My Home",
            "icon":"https://airtake.cos.ap-shanghai.test.com/misc/test.png",
            "message_content":"A task is not triggered in the **test of an automation scene for a light**.",
            "message_group_id":"Vhh00osEGkmdF8RS",
            "message_title":"Message about an automation task"
        }
    ],
    "pageNo":1,
    "totalCount":2
    }
}

Error codes

The following table lists common error codes for the API calls. For more error codes, see Global Error Codes.

Error codes	Description
500	A system error has occurred while processing your request.
1106	Invalid permission.
1109	Invalid parameter.

Query list of alerts

API description

Get the details of alerts that are included in a specific alert group.

API endpoint

action: message.alarmList

Request parameter

Parameter name	Type	Parameter type	Description	Required
uid	String	URI	The user’s unique identifier.	Yes
message_group_id	String	URI	The ID of the alert group.	Yes
time_zone_id	String	The time zone ID. Only `Asia/Shanghai` is supported.	Yes
page_no	Integer	URL	The page number, starting from `1`. Default value: `1`.	No
page_size	Integer	URL	The number of entries returned per page. Default value: `15`. Maximum value: `100`.	No

Response parameter

Parameter name	Type	Description
code	Integer	The response code. For more information, see Error codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

Description of result

Parameter name	Type	Description
messages	List	The list of alerts.
page_no	Integer	The total number of returned pages.
total_count	Integer	The total number of returned entries.

Description of messages

Parameter name	Type	Description
id	Long	The ID of the alert.
date_time	String	The time when the alert was generated.
icon	String	The recommended icon.
message_content	String	The content of the alert.
message_title	String	The title of the alert.
message_source_id	String	The ID of the source that triggers the alert.

Sample request

{
  "action": "message.alarmList",
  "params": {
    "uid": "ay1578921339xxxxxxxx",
    "message_group_id": "vdexxxxxx6223",
    "time_zone_id": "Asia/Shanghai"
  }
}

Sample response

{
    "success": true,
    "t":1540799929837,
    "result": {
        "messages":[
        {
            "id": 1491082638,
            "date_time":"2020-8-11 19:59",
            "icon":"https://images.tuyacn.com/smart/icon/axxxxxxlV6/5yyyyyyyy42dd.png",
            "message_content":"Test of brightness alert",
            "message_title":"Test push notification of a brightness alert"
            "message_source_id": "vdexxxxxx6223"
        },
          {
            "id": 1491079892,
            "date_time":"2020-8-11 19:58",
            "icon":"https://images.tuyacn.com/smart/icon/axxxxxxlV6/5yyyyyyyy42dd.png",
            "message_content":"Test of brightness alert",
            "message_title":"Test push notification of a brightness alert"
            "message_source_id": "vdexxxxxx6223"
        }
    ],
    "pageNo":1,
    "totalCount":2
    }
}

Error codes

The following table lists common error codes for the API calls. For more error codes, see Global Error Codes.

Error codes	Description
500	A system error has occurred while processing your request.
1106	Invalid permission.
1109	Invalid parameter.

Query list of messages for home

API description

Query a list of messages for a home to which a specific user belongs.

API endpoint

action: message.homeList

Request parameter

Parameter name	Type	Parameter type	Description	Required
uid	String	URI	The user’s unique identifier.	Yes
time_zone_id	String	The time zone ID. Only `Asia/Shanghai` is supported.	Yes
page_no	Integer	URL	The page number, starting from `1`. Default value: `1`.	No
page_size	Integer	URL	The number of entries returned per page. Default value: `15`. Maximum value: `100`.	No

Response parameter

Parameter name	Type	Description
code	Integer	The response code. For more information, see Error codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

Description of result

Parameter name	Type	Description
messages	List	The list of home messages and notifications.
page_no	Integer	The total number of returned pages.
total_count	Integer	The total number of returned entries.

Description of messages

Parameter name	Type	Description
id	Long	The message ID.
date_time	String	The time when the message was generated.
icon	String	The recommended icon.
message_content	String	The content of the message.
message_title	String	The title of the message.
message_source_id	String	The ID of the source that generates the message.

Sample request

{
  "action": "message.homeList",
  "params": {
    "uid": "ay1578xxxxxxxx",
    "time_zone_id": "Asia/Shanghai"
  }
}

Sample response

{
    "success": true,
    "t":1540799929837,
    "result": {
        "messages":[
        {
            "id": 1463072653,
            "date_time":"2020-8-6 21:00",
            "icon":"https://airtake.cos.ap-shanghai.test.com/misc/test.png",
            "message_content":"The IR air conditioner added to **My home** is ready for use.",
            "message_title":"Add device",
            "message_source_id": "6c975b3013aa413cd1n9bo"
        },
          {
            "id": 1503785831,
            "date_time":"2020-8-4 22:17",
            "icon":"https://airtake.cos.ap-shanghai.test.com/misc/test.png",
            "message_content":"XXXXXX invites you to join the home named **My home**. Choose **Me > Home Management** on the app and accept the invitation.",
            "message_title":"Invitation to be home member",
            "message_source_id": "ay1578921339405Lr3au"
        }
    ],
    "pageNo":1,
    "totalCount":2
    }
}

Error codes

The following table lists common error codes for the API calls. For more error codes, see Global Error Codes.

Error codes	Description
500	A system error has occurred while processing your request.
1106	Invalid permission.
1109	Invalid parameter.

Query list of notifications

API description

Query a list of notifications that are sent to a specific user.

API endpoint

action: message.notificationList

Request parameter

Parameter name	Type	Parameter type	Description	Required
uid	String	URI	The user’s unique identifier.	Yes
time_zone_id	String	The time zone ID. Only `Asia/Shanghai` is supported.	Yes
page_no	Integer	URL	The page number, starting from `1`. Default value: `1`.	No
page_size	Integer	URL	The number of entries returned per page. Default value: `15`. Maximum value: `100`.	No

Response parameter

Parameter name	Type	Description
code	Integer	The response code. For more information, see Error codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

Description of result

Parameter name	Type	Description
messages	List	The list of home messages and notifications.
page_no	Integer	The total number of returned pages.
total_count	Integer	The total number of returned entries.

Description of messages

Parameter name	Type	Description
id	Long	The message ID.
date_time	String	The time when the notification was generated.
icon	String	The recommended icon.
message_content	String	The content of the notification.
message_title	String	The title of the notification.
message_source_id	String	The ID of the source that generates the notification. This parameter value is returned to indicate the progress of processing user feedback.

Sample request

{
  "action": "message.notificationList",
  "params": {
    "uid": "ay1578xxxxxxxx",
    "time_zone_id": "Asia/Shanghai"
  }
}

Sample response

{
    "success": true,
    "t":1540799929837,
    "result": {
        "messages":[
        {
            "id": 1491386944,
            "date_time":"2020-8-11 21:02",
            "icon":"https://airtake.cos.ap-shanghai.test.com/misc/test.png",
            "message_content":"Hello, your feedback has replies. Please check the replies at your earliest convenience.",
            "message_title":"Update of feedback processing status",
            "message_source_id": "FCN202008119to22br7z9xi"
        },
          {
            "id": 1452057379,
            "date_time":"2020-8-4 22:17",
            "icon":"https://airtake.cos.ap-shanghai.test.com/misc/test.png",
            "message_content":"This account has been used for login on another mobile device. Device model: XXXX. If this operation was not performed by you, we recommend that you change your login password immediately to prevent unauthorized use of your account.",
            "message_title":"Notification"
        }
    ],
    "pageNo":1,
    "totalCount":2
    }
}

Error codes

The following table lists common error codes for the API calls. For more error codes, see Global Error Codes.

Error codes	Description
500	A system error has occurred while processing your request.
1106	Invalid permission.
1109	Invalid parameter.

Delete alert group

API description

Delete a summary of alerts.

API endpoint

action: message.deleteAlarmGroup

Request parameter

Parameter name	Type	Parameter type	Description	Required
uid	String	URI	The user’s unique identifier.	Yes
message_group_ids	String	URL	The ID of the alert group. To delete multiple alert groups, separate the group IDs with commas (,). Up to 100 alert groups are supported.	Yes

Response parameter

Parameter name	Type	Description
code	Integer	The response code. For more information, see Error codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	The returned result.

Sample request

{
  "action": "message.deleteAlarmGroup",
  "params": {
    "uid": "ay15742xxxxx",
    "message_group_ids": "Vhh00osEGkmdF8RS,vdexxxxxx6223"
  }
}

Sample response

{
    "success":true,
    "t":1540799929837,
    "result":true
}

Error codes

The following table lists common error codes for the API calls. For more error codes, see Global Error Codes.

Error codes	Description
500	A system error has occurred while processing your request.
1106	Invalid permission.
1109	Invalid parameter.

Delete messages

API description

Delete a message that might be an alert, home message, or notification.

API endpoint

action: message.deleteById

Request parameter

Parameter name	Type	Parameter type	Description	Required
uid	String	URI	The user’s unique identifier.	Yes
ids	String	URL	The ID of the message group. To delete multiple messages, separate the message IDs with commas (,). Up to 100 alert groups are supported.	Yes

Response parameter

Parameter name	Type	Description
code	Integer	The response code. For more information, see Error codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	The returned result.

Sample request

{
  "action": "message.deleteAlarmGroup",
  "params": {
    "uid": "ay15742xxxxx",
    "ids": "1491386944,1452057379"
  }
}

Sample response

{
    "success":true,
    "t":1540799929837,
    "result":true
}

Error codes

The following table lists common error codes for the API calls. For more error codes, see Global Error Codes.

Error codes	Description
500	A system error has occurred while processing your request.
1106	Invalid permission.
1109	Invalid parameter.

Mark alert aggregation as read

API description

Set the status of an alert aggregation to be read.

API endpoint

action: message.readAlarmGroup

Request parameter

Parameter name	Type	Parameter type	Description	Required
uid	String	URI	The user’s unique identifier.	Yes
ids	String	URL	The ID of the alert group. To mark multiple alert groups, separate the group IDs with commas (,). Up to 100 alert groups are supported.	Yes

Response parameter

Parameter name	Type	Description
code	Integer	The response code. For more information, see Error codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

Sample request

{
  "action": "message.deleteAlarmGroup",
  "params": {
    "uid": "ay15742xxxxx",
    "ids": "556446,547450"
  }
}

Sample response

{
    "success":true,
    "t":1540799929837,
    "result":true
}

Error codes

The following table lists common error codes for the API calls. For more error codes, see Global Error Codes.

Error codes	Description
500	A system error has occurred while processing your request.
1106	Invalid permission.