Message Center

Last Updated on : 2024-06-05 03:15:12download

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.