Message Management

MessageLib offers comprehensive message management functionality, including message querying, deletion, push settings, and additional features. This topic describes interfaces, best practices, and other relevant information.

Quick start

Import module

import { TSmartMessage } from '@thingsmart/messagelib';
import { MessageBean, MessageListBean, MessageHasNew, MessageType } from '@thingsmart/messagelib';

Get instance

const messageInstance = TSmartMessage.getInstance();

API description

Query message list

Query a list of all messages

API description

async getMessageList(): Promise<TSmartAtopResponse<Array<MessageBean>>>

Return value

Promise<TSmartAtopResponse<Array<MessageBean>>>

Data model MessageBean

Field	Type	Description
dateTime	string	The date and time.
icon	string	The URL of the message icon.
msgTypeContent	string	The name of the message type.
msgContent	string	The message content.
msgType	number	The message type.
msgSrcId	string	The device ID. Only an alert has this parameter.
id	string	The message ID.

Sample code

try {
  const response = await TSmartMessage.getInstance().getMessageList();
  if (response.success) {
    const messageList = response.result;
    console.log('Message list:', messageList);
  } else {
    console.error('Failed to get the message list:', response.errorMsg);
  }
} catch (error) {
  console.error('Network error:', error);
}

Query a list of messages on pages

API description

async getMessageListByPage(requestParams: MessageListParams): Promise<TSmartAtopResponse<MessageListBean>>

Parameters

Parameter	Type	Description
requestParams	MessageListParams	The query parameters.

MessageListParams structure

Field	Type	Description
offset	number	The total number of messages already returned.
limit	number	The maximum number of entries to be returned per page.

Return value

Promise<TSmartAtopResponse<MessageListBean>>

Sample code

const params: MessageListParams = {
  offset: 0,
  limit: 20
};

try {
  const response = await TSmartMessage.getInstance().getMessageListByPage(params);
  if (response.success) {
    const messageListBean = response.result;
    console.log('The list of messages on pages:', messageListBean);
  }
} catch (error) {
  console.error('Failed to get the list of messages on pages:', error);
}

(Recommended) Query messages on pages by message type

API description

async getMessageListByMsgType(requestParams: MsgListByMsgTypeParams): Promise<TSmartAtopResponse<MessageListBean>>

Parameters

Parameter	Type	Description
requestParams	MsgListByMsgTypeParams	The query parameters by type.

MsgListByMsgTypeParams structure

Field	Type	Description
offset	number	The total number of messages already returned.
limit	number	The maximum number of entries to be returned per page.
msgType	MessageType	The enumerated values ​​for message types.

MessageType enumerated values

Value	Description
MessageType.ALARM	Alert messages.
MessageType.FAMILY	Home messages.
MessageType.NOTIFICATION	Notification messages.

Sample code

const params: MsgListByMsgTypeParams = {
  offset: 0,
  limit: 20,
  msgType: MessageType.ALARM
};

try {
  const response = await TSmartMessage.getInstance().getMessageListByMsgType(params);
  if (response.success) {
    const messageListBean = response.result;
    console.log('The list of alert messages:', messageListBean);
  }
} catch (error) {
  console.error('Failed to get alert messages:', error);
}

Query messages on pages by message source ID

API description

async getMessageListByMsgSrcId(requestParams: MsgListBySrcIdParams): Promise<TSmartAtopResponse<MessageListBean>>

Parameters

Parameter	Type	Description
requestParams	MsgListBySrcIdParams	The query parameters by message source.

MsgListBySrcIdParams structure

Field	Type	Description
offset	number	The entry number starting from which data is returned.
limit	number	The number of entries returned per page.
msgType	MessageType	The message type. Currently, only the alert type is supported.
msgSrcId	string	The ID of the source that generates the message.
encryptImage	boolean	Specifies whether to encrypt the image.

Sample code

const params: MsgListBySrcIdParams = {
  offset: 0,
  limit: 20,
  msgType: MessageType.ALARM,
  msgSrcId: "your_device_id",
  encryptImage: false
};

try {
  const response = await TSmartMessage.getInstance().getMessageListByMsgSrcId(params);
  if (response.success) {
    const messageListBean = response.result;
    console.log('Device alert messages:', messageListBean);
  }
} catch (error) {
  console.error('Failed to get device alert messages:', error);
}

Delete messages

Bulk delete messages

API description

async deleteMessages(msgIdList: Array<string>): Promise<TSmartAtopResponse<boolean>>

Parameters

Parameter	Type	Description
msgIdList	Array	The list of IDs for the messages to be deleted.

Sample code

const messageIds = ["msg_id_1", "msg_id_2", "msg_id_3"];

try {
  const response = await TSmartMessage.getInstance().deleteMessages(messageIds);
  if (response.success && response.result) {
    console.log('Messages were deleted successfully');
  } else {
    console.error('Failed to delete messages:', response.errorMsg);
  }
} catch (error) {
  console.error('Network error occurred while deleting messages:', error);
}

Bulk delete specific type of messages

API description

async deleteMessageByType(messageType: MessageType, msgIdList: Array<string> | null, msgSrcIdList: Array<string> | null): Promise<TSmartAtopResponse<boolean>>

Parameters

Parameter	Type	Description
messageType	MessageType	The message type.
msgIdList	Array | null	The list of IDs for the messages to be deleted.
msgSrcIdList	Array | null	The list of message source IDs. An empty value or null represents that alerts are not deleted.

Sample code

// Delete messages from the alert message list
const srcIds = ["src_id_1", "src_id_2"];
try {
  const response = await TSmartMessage.getInstance().deleteMessageByType(
    MessageType.ALARM,
    null,
    srcIds
  );
  if (response.success && response.result) {
    console.log('Alert messages were deleted successfully');
  }
} catch (error) {
  console.error('Failed to delete alert messages:', error);
}

// Delete messages from the alert message details
const msgIds = ["msg_id_1", "msg_id_2"];
try {
  const response = await TSmartMessage.getInstance().deleteMessageByType(
    MessageType.ALARM,
    msgIds,
    null
  );
  if (response.success && response.result) {
    console.log('Alert message details were deleted successfully');
  }
} catch (error) {
  console.error('Failed to delete alert message details:', error);
}

Check for new messages

API description

async requestMessageNew(): Promise<TSmartAtopResponse<MessageHasNew>>

Return value

Promise<TSmartAtopResponse<MessageHasNew>>

Data model of MessageHasNew

Field	Type	Description
alarm	boolean	Indicates whether alerts are generated.
family	boolean	Indicates whether home messages are generated.
notification	boolean	Indicates whether notifications are generated.

Sample code

try {
  const response = await TSmartMessage.getInstance().requestMessageNew();
  if (response.success) {
    const hasNew = response.result;
    if (hasNew.alarm) {
      console.log('There is a new alert message');
    }
    if (hasNew.family) {
      console.log('There is a new home message');
    }
    if (hasNew.notification) {
      console.log('There is a new notification message');
    }
  }
} catch (error) {
  console.error('Failed to check for new messages:', error);
}

Manage message push

Get on/off status of message push

API description

async getPushSwitchStatusByType(messageType: number): Promise<TSmartAtopResponse<boolean>>

Parameters

Parameter	Type	Description
messageType	number	The message type.

Sample code

try {
  const response = await TSmartMessage.getInstance().getPushSwitchStatusByType(1);
  if (response.success) {
    const isEnabled = response.result;
    console.log('Push notification switch status:', isEnabled ? 'Enabled' : 'Disabled');
  }
} catch (error) {
  console.error('Failed to get push notification switch status:', error);
}

Set on/off status of message push

API description

async setPushSwitchStatusByType(messageType: number, isClose: boolean): Promise<TSmartAtopResponse<boolean>>

Parameters

Parameter	Type	Description
messageType	number	The message type.
isClose	boolean	Indicates whether message push is disabled.

Sample code

try {
  const response = await TSmartMessage.getInstance().setPushSwitchStatusByType(1, false);
  if (response.success && response.result) {
    console.log('Push notification switch was set successfully');
  }
} catch (error) {
  console.error('Failed to set the push notification switch:', error);
}

Get the list of devices that support message push

API description

async getSupportPushDeviceList(homeId: number): Promise<TSmartAtopResponse<Array<PushDeviceBean>>>

Parameters

Parameter	Type	Description
homeId	number	The ID of the specified home.

Sample code

try {
  const response = await TSmartMessage.getInstance().getSupportPushDeviceList(12345);
  if (response.success) {
    const deviceList = response.result;
    console.log('Devices receiving push notifications:', deviceList);
  }
} catch (error) {
  console.error('Failed to get the devices receiving push notifications:', error);
}

Advanced features

Bulk read messages

API description

async readMessageList(messageType: MessageType, msgIdList: Array<string>): Promise<TSmartAtopResponse<boolean>>

Parameters

Parameter	Type	Description
messageType	MessageType	The message type. Currently, only the alert type is supported.
msgIdList	Array	The list of IDs for the messages.

Sample code

const msgIds = ["msg_id_1", "msg_id_2"];
try {
  const response = await TSmartMessage.getInstance().readMessageList(MessageType.ALARM, msgIds);
  if (response.success && response.result) {
    console.log('Multiple messages were marked as read');
  }
} catch (error) {
  console.error('Failed to mark multiple messages as read:', error);
}

Mark all messages as read

API description

async readAllMessage(messageType: MessageType): Promise<TSmartAtopResponse<boolean>>

Parameters

Parameter	Type	Description
messageType	MessageType	The message type. Currently, only the alert type is supported.

Sample code

try {
  const response = await TSmartMessage.getInstance().readAllMessage(MessageType.ALARM);
  if (response.success && response.result) {
    console.log('All messages were marked as read');
  }
} catch (error) {
  console.error('Failed to mark all messages as read:', error);
}

Get the latest message time

API description

async getMessageMaxTime(): Promise<TSmartAtopResponse<number>>

Return value

Promise<TSmartAtopResponse<number>>: Returns the timestamp of the latest message.

Sample code

try {
  const response = await TSmartMessage.getInstance().getMessageMaxTime();
  if (response.success) {
    const maxTime = response.result;
    console.log('Latest message time:', new Date(maxTime));
  }
} catch (error) {
  console.error('Failed to get the latest message time:', error);
}

Error handling

All APIs return responses in the TSmartAtopResponse format, which includes the following fields:

interface TSmartAtopResponse<T> {
  success: boolean;      // Indicates whether the request was successful
  result: T;            // Response data
  errorCode: string;    // Error code
  errorMsg: string;     // Error message
}

Example of general error handling

try {
  const response = await TSmartMessage.getInstance().getMessageList();

  if (response.success) {
    // Request was successful. Handle the data
    const data = response.result;
    console.log('Successfully retrieved data:', data);
  } else {
    // Request failed. Handle the error
    console.error('Request failed:', response.errorCode, response.errorMsg);

    // Handle specific errors based on error code
    switch (response.errorCode) {
      case 'NETWORK_ERROR':
        console.log('Network error, please check your network connection');
        break;
      case 'AUTH_FAILED':
        console.log('Authentication failed, please log in again');
        break;
      default:
        console.log('Unknown error:', response.errorMsg);
        break;
    }
  }
} catch (error) {
  // Network exception or other exceptions
  console.error('Exception:', error);
}

Best practices

Error handling

Always check the success field of the response and handle errors accordingly based on the error code.

Query on pages

It is recommended to use getMessageListByMsgType instead of the deprecated method, and set the pagination parameters appropriately.

const params = {
  offset: 0,
  limit: 20,  // It is recommended that each page contains no more than 50 items
  msgType: MessageType.ALARM
};

Resource management

Handle asynchronous operations promptly to avoid memory leaks.

let messageRequest: Promise<any> | null = null;

async function loadMessages() {
  try {
    messageRequest = TSmartMessage.getInstance().getMessageList();
    const response = await messageRequest;
    // Handle the response
  } finally {
    messageRequest = null;
  }
}

Type safety

Make full use of type checking in TypeScript.

// Recommended: Use explicit types
const params: MsgListByMsgTypeParams = {
  offset: 0,
  limit: 20,
  msgType: MessageType.ALARM
};

// Avoid using the any type
const params: any = { /* ... */ };