Messaging APIs - Date and Time of Message and Message Status

This section describes mesibo APIs to access various timestamps associated with a message, for exammple, when message was sent, delivered or read, and how to format the timestamp in human readable date and time representations.

The mesibo time and date API provides MesiboDateTime object, which store timestamps in milliseconds. The MesiboDateTime object offers access to various date and time components, such as year, month, day, hour, minute, second, and more. It also provides convenient functions for converting timestamps into human-readable date and time strings.

For example,

MesiboDateTime ts = message.getTimestamp();

You can then access the individual date and time properties of the MesiboDateTime object and conveniently convert the date and time into strings.

String date = ts.getDate();
String time = ts.getTime(true);

mesibo automatically detects the default date and time format based on the current locale, but you can customize this format to suit your requirements. You can also define custom strings to represent "today" and "yesterday" instead of formatted dates.

Message Timestamp

You can use the following functions to access the basic timestamp object for a message:

Sent or Received Timestamp

You can get the timestamp of the message when the message was received or sent by calling getTimestamp method.

MesiboDateTime mt = message.getTimestamp();

Delivered Timestamp

To retrieve the timestamp when a sent message was delivered, use the getDeliveryTimestamp method:

MesiboDateTime dt = message.getDeliveryTimestamp(peer);

Where

getDeliveryTimestamp returns null if the message was not delivered yet or it is an incoming message.

In Javascript, you need to pass a callback function which will be called with MesiboDateTime object instead of returning it.

message.getDeliveryTimestamp(peer, function(dt) {

});

Read Timestamp

To obtain the timestamp when a sent message was read, use the getReadTimestamp method:

MesiboDateTime rt = message.getReadTimestamp(peer);

Where

getReadTimestamp returns null if the message was not read yet.

In Javascript, you need to pass a callback function which will be called with MesiboDateTime object instead of returning it.

message.getReadTimestamp(peer, function(rt) {

});

Formatting Date and Time

You can utilize the following functions to obtain human-readable date and time strings from MesiboDateTime object.

MesiboDateTime ts = message.getTimestamp();

Get Formatted Message Date

Retrieve a formatted date string by calling one of the following functions:

String date = ts.getDate(monthFirst, today, yesterday, numerical);

or

String date = ts.getDate();

or

String date = ts.getNumericalDate();

Where

Get Formatted Message Time

Obtain a formatted time string by calling the following function:

String time = ts.getTime(seconds);

Where

Get Date in Natural Language

In addition to standard formatted date and time, you can also get dates in natural language form, like last Friday, this month, or 5 hours ago. This format is beneficial when approximating time. One practical application is displaying the last seen timestamp of a profile, accessible through profile.getLastSeen().

String date = ts.getDateInNaturalLanguage();

Additionally, you can input the parameter 'accuracy' in seconds to decrease the precision of the output, often for privacy purposes. For instance, using 3600 would reduce the precision to an hour, instead of default which is in seconds.

String date = ts.getDateInNaturalLanguage(3600);

Custom Date Format

The MesiboDateTime object offers access to various date and time components, such as year, month, day, hour, minute, second, and more. You can use them to create custom date and time representation. You can also use various utility functions describe below to aid in forming custom date string.

Localization functions

You can utilize the following static functions to detect the default date and time format for the current region:

Use MesiboDateTime.isMonthFirstDateFormat() to determine if the default date format for the current region places the month first.

boolean monthFirst = MesiboDateTime.isMonthFirstDateFormat(); 

Use MesiboDateTime.is24HourTimeFormat() to determine if the default time format for the current region uses a 12-hour or 24-hour notation.

boolean timeFormat = MesiboDateTime.is24HourTimeFormat(); 

You can use MesiboDateTime.setDefaultDateFormat(true) to override the month first format.

MesiboDateTime.setDefaultDateFormat(true); 

You can use MesiboDateTime.setDefaultRelativeDateText() to set text for today and yesterday which will be returned if the timestamp is one or two days old.

MesiboDateTime.setDefaultRelativeDateText("Today", "Yesterday"); 

You can use MesiboDateTime.setMonthName(1, "Jan") to customize name of months.

Utility Functions

You can utilize the following functions to get additional information:

Use getDaysElapsed() to obtain the count of days that have passed since the timestamp (counting from midnight). It returns 0 for today, 1 for yesterday, and so forth.

int days = ts.getDaysElapsed(); 

You can also use isToday() and isYesterday() functions. These functions internally use getDaysElapsed() to denote whether the timestamp represents today or yesterday.

Use getSecondsElapsed() to get the number of seconds that have passed since the timestamp.

int seconds = ts.getSecondsElapsed(); 

Use getMonthName() to get name of the month.

String month = ts.getMonth();