Single chat module

Prerequisites#

In order to send messages using the chat sdk , at first you need to establish the connection to the server. sdk provides methods for initializing the connection configuration as well as methods for making connection.

Note: Even if you don't have internet connection, you are still allowed to send messages which will be kept in offline database.Once the user connected to the internet, the messages will be sent automatically when user opens the app.

Preparing single chat jid#

Almost of the sdk methods expect jid as a input parameter, so sdk provides below utility method to prepare the jid. The method prepares the single chat jid from the given string by using chat config provided via [com.contusflysdk.api.ChatConnectionManager.initialize] method.

Note: The below characters is not allowed in uniqueId: U+0022 (") U+0026 (&) U+0027 (') U+002F (/) U+003A (:) U+003C (<) U+003E (>) U+0040 (@).

Argument	Type	Description
UNIQUE_USER_ID	`String`	unique userId for preparing JID, unique userId will be available during registration response in `username` field

var userJid = await Mirrorfly.getJid(username);

Text message#

Text is a basic form of communication between users. sdk provides methods to send the text message to the end users. once the user has sent message via sdk, it will give callback with status. if you want send the text message for a user, you can utilise the below method.

Argument	Type	Description
TO_JID	`String`	jid of the end user
TEXT	`String`	text message to be sent
REPLY_MESSAGE_ID	`String`	if it is a reply message for message A, then message A's `messageId` otherwise empty string

Mirrorfly.sendTextMessage(TEXT, TO_JID, replyMessageId).then((value) {
   var data = sendMessageModelFromJson(value);
     // you will get the message sent success response
 });

Note : You can listen to incoming messages by using the onMessageReceived listener.

Location message#

Location sharing is a famous communication between users. sdk provides methods to send the location message to the end users. once the user has sent message via sdk, it will give callback with status. if you want send the location message for a user, you can utilise the below method.

Argument	Type	Description
TO_JID	`String`	jid of the end user
LATITUDE	`double`	location latitude which needs to be sent
LONGITUDE	`double`	location longitude which needs to be sent
REPLY_MESSAGE_ID	`String`	if it is a reply message for message A, then message A's `messageId` otherwise empty string

Mirrorfly.sendLocationMessage(TO_JID, LATITUDE, LONGITUDE, REPLY_MESSAGE_ID).then((value) {
   var data = sendMessageModelFromJson(value);
  //you can add this message object to your arraylist,
  //then updated the UI
});

Note : You can listen to incoming messages by using the onMessageReceived listener.

Contact message#

Contact sharing is very useful communication between users. sdk provides methods to send the contact message to the end users. once the user has sent message via sdk, it will give callback with status. if you want send the contact message for a user, you can utilise the below method.

Argument	Type	Description
TO_JID	`String`	jid of the end user
CONTACT_NAME	`String`	contact name
CONTACT_NUMBERS	`List<String>`	list of numbers in that contact
REPLY_MESSAGE_ID	`String`	if it is a reply message for message A, then message A's `messageId` otherwise empty string

Mirrorfly.sendContactMessage(TO_JID, CONTACT_NAME, CONTACT_NUMBERS, REPLY_MESSAGE_ID).then((value) {
  ChatMessageModel chatMessageModel = sendMessageModelFromJson(value);
  //you can add this message object to your arraylist,
  //then updated the UI
});

Note : You can listen to incoming messages by using the onMessageReceived listener.

Document message#

Document sharing is very useful communication between users. sdk provides methods to send the document message to the end users. once the user has sent message via sdk, it will give callback with status. if you want send the document message for a user, you can utilise the below method.

Argument	Type	Description
TO_JID	`String`	jid of the end user
LOCAL_FILE_PATH	`String`	Local document `File path` of the document
REPLY_MESSAGE_ID	`String`	if it is a reply message for message A, then message A's `messageId` otherwise empty string

Mirrorfly.sendDocumentMessage(TO_JID, LOCAL_FILE_PATH, REPLY_MESSAGE_ID).then((value) {
  ChatMessageModel chatMessageModel = sendMessageModelFromJson(value);
  //you can add this message object to your arraylist,
  //then updated the UI
});

Note : You can listen for incoming media messages with the onMessageReceived event. Additionally, use the onMediaStatusUpdated event for status updates, and track upload/download progress using the onUploadDownloadProgressChanged event.

Note : In Mirrorfly.initializeSDK() storageFolderName should be defined to set your own local path to store app media files.

Video message#

Video sharing is very useful communication between users. sdk provides methods to send the video message to the end users. once the user has sent message via sdk, it will give callback with status. if you want send the video message for a user, you can utilise the below method.

Argument	Type	Description
TO_JID	`String`	jid of the end user
LOCAL_FILE_PATH	`String`	video `File path` object
VIDEO_CAPTION	`String`	caption text for video file
REPLY_MESSAGE_ID	`String`	if it is a reply message for message A, then message A's `messageId` otherwise empty string

Mirrorfly.sendVideoMessage(TO_JID, LOCAL_FILE_PATH, VIDEO_CAPTION,  REPLY_MESSAGE_ID).then((value) {
 var data = sendMessageModelFromJson(value);

});

Note : You can listen for incoming media messages with the onMessageReceived event. Additionally, use the onMediaStatusUpdated event for status updates, and track upload/download progress using the onUploadDownloadProgressChanged event.

Note : In Mirrorfly.initializeSDK() storageFolderName should be defined to set your own local path to store app media files.

Image message#

To send image as a message call the below method. Calling the below method will upload the image file to the server provided during sdk initialization then send the message

Argument	Type	Description
TO_JID	`String`	jid of the end user
IMAGE_FILE	`String`	image `File path` which needs to be sent
CAPTION	`String`	additional text which can be sent along with the image message
REPLY_MESSAGE_ID	`String`	if it is a reply message for message A, then message A's `messageId` otherwise empty string

Mirrorfly.sendImageMessage(TO_JID, IMAGE_FILE, CAPTION, REPLY_MESSAGE_ID).then((value) {
  ChatMessageModel chatMessageModel = sendMessageModelFromJson(value);
});

Note : You can listen for incoming media messages with the onMessageReceived event. Additionally, use the onMediaStatusUpdated event for status updates, and track upload/download progress using the onUploadDownloadProgressChanged event.

Note : In Mirrorfly.initializeSDK() storageFolderName should be defined to set your own local path to store app media files.

Audio message#

To send audio as a message call the below method. Calling the below method will upload the audio file to the server provided during sdk initialization then send the message

Argument	Type	Description
TO_JID	`String`	jid of the end user
AUDIO_FILE	`String`	audio `File path` we are sending
AUDIO_DURATION	`int`	duration of the audio file
IS_RECORDED	`bool`	`true`, if audio file is recorded.`false`, if audio file is attached.
REPLY_MESSAGE_ID	`String`	if it is a reply message for message A, then message A's `messageId` otherwise empty string

Mirrorfly.sendAudioMessage(TO_JID, AUDIO_FILE, IS_RECORDED, AUDIO_DURATION, REPLY_MESSAGE_ID).then((value) {
  var data = sendMessageModelFromJson(value);
});

Note : You can listen for incoming media messages with the onMessageReceived event. Additionally, use the onMediaStatusUpdated event for status updates, and track upload/download progress using the onUploadDownloadProgressChanged event.

Note : In Mirrorfly.initializeSDK() storageFolderName should be defined to set your own local path to store app media files.

Get messages of a user/group#

To fetch all the conversation between you and a single chat user or group, call the below method.

Mirrorfly.getMessagesOfJid(JID).then((value) {
  var chatMessageModel = chatMessageModelFromJson(value);

})

Argument	Type	Description
JID	`String`	Jid of the user/group

Get message from db#

Whenever you get callbacks from MessageEventsListener, you will get messageId sometimes at those times you can fetch the message from db using the below method and then update your list as well as notify the list view.

Argument	Type	Description
messageId	`String`	messageId of the message

Mirrorfly.getMessageOfId(messageId).then((value) {
  var data = sendMessageModelFromJson(value);
})

To get the uploaded/downloaded status of a media message Refer the snippet below.

Mirrorfly.getMessageOfId(MEDIA_MESSAGE_ID).then((value) {
    var data = sendMessageModelFromJson(value);
});

Argument	Type	Description
MEDIA_MESSAGE_ID	`String`	id of a message

Get messages of a user/group via pagination#

Initialization#

Mirrorfly.initializeMessageList(
    userJid: USER_JID, 
    messageId: MESSAGE_ID, 
    messageTime: MESSAGE_TIME, 
    exclude: EXCLUDE, 
    ascendingOrder: ASCENDING_ORDER, 
    limit: LIMIT,topicId: TOPIC_ID).then((isSuccess) {

});

Argument	Type	Description
USER_JID	`String`	Jid of the User/Group
MESSAGE_ID	`String`	Message id of the starting point `optional`
MESSAGE_TIME	`String`	Message time of the starting point `optional`
EXCLUDE	`String`	If `true` starting point message will be excluded in message list, default `true`
ASCENDING_ORDER	`String`	If `true` message list will be returned ascendingOrder by message time, default `false`
LIMIT	`String`	No of messages will be fetched for each request, default 25
TOPIC_ID	`String`	Topic ID to be fetched

Load Initial Messages#

To fetch initial conversations between you and a single chat user or group using pagination, call the below method.

Mirrorfly.loadMessages().then((chatList) {
  
  List<ChatMessageModel> chatMessageModel = chatMessageModelFromJson(chatList);
  
}).catchError((e) {
  
 // Handle the Error while fetching the Initial Message List

});

Load Previous Messages#

Mirrorfly.loadPreviousMessages().then((previousChatList) {
  
  List<ChatMessageModel> previousChatMessageModel = chatMessageModelFromJson(chatList);
  
}).catchError((e) {
  
// Handle the Error while fetching the Previous Message List

});

Load Next Messages#

Mirrorfly.loadNextMessages().then((value) {
  
  List<ChatMessageModel> nextChatMessageModel = chatMessageModelFromJson(chatList);
  
}).catchError((e) {
  
// Handle the Error while fetching the Previous Message List

});

Check Previous Set of Messages Available or not#

To check previous set of conversations available or not, call the below method.

var previousMessageAvailable = await Mirrorfly.hasPreviousMessages();

Check Next Set of Messages Available#

To check next set of conversations available or not, call the below method.

var nextMessageAvailable = await Mirrorfly.hasNextMessages();

Get media messages#

If you want to get the media messages for a user/group, you can utilise the below method.

Mirrorfly.getMediaMessages(JID).then((value) async {
    if (value != null) {
        var data = chatMessageModelFromJson(value);      
    }
});

Argument	Type	Description
JID	`String`	jid of the chat user

Above methods fetch media messages which are successfully sent and received

If media message feature unavailable for your plan then it will throw 403 exception.

Delete Messages#

Delete messsage is a feature which is found in modern messaging apps which allows the user to delete the message once it is sent.Once you sent the message, you can able to delete the messages by using built in sdk methods.

Delete for me#

If you want to delete the messages for yourself only then you can use the below method.

Note: The messages will not be deleted to the receipient.

Note: Single Chat Type is chat and Group Chat Type is groupchat

Argument	Type	Description
jid	`String`	jid of the chat user
messageList	`List<String>`	List of messageId to be deleted
chatType	`String`	`chat` for single chat, `groupchat`for group chat
isMediaDelete	`bool`	set `true` to delete media file in local otherwise set `false`

Mirrorfly.deleteMessagesForMe(jid,chatType, messageList,isMediaDelete).then((value){

});

Delete for everyone#

If you want to delete the messages for yourself and receiver then you can use the below method. The messages will also be deleted to the receipient.

Argument	Type	Description
jid	`String`	jid of the chat user
messageList	`List<String>`	List of messageId to be deleted
chatType	`String`	`chat` for single chat, `groupchat`for group chat
isMediaDelete	`bool`	set `true` to delete media file in local otherwise set `false`

Mirrorfly.deleteMessagesForEveryone(jid,chatType, messageList,isMediaDelete).then((value){

});

Favourite Messages#

Favourite messags is feature which allows users to mark some messages as favourites. so that they can see those important messages in future without searching for them in chat. Once you marked messages as favourite, you can get those from sdk to show it in your app's screen.

Argument	Type	Description
messageID	`String`	messageId of the message
chatUserJID	`String`	jid of the chat user
isFavourite	`bool`	`true`, if you are adding to favourites.`false` to remove from favourites
chatType	`String`	`chat` for single chat, `groupchat`for group chat

Make/Remove favourite#

You can mark the messages as Make/Remove favourite by using the below method.

Mirrorfly.updateFavouriteStatus(messageID, chatUserJID, isFavourite, chatType).then((value) {

});

Get all favourite messages#

The below method will return all the favourite messages from the local db.

Mirrorfly.getFavouriteMessages().then((value){
  var chatMessageList = chatMessageModelFromJson(value);

});

Message receipts#

info

To obserserve message's sent, delivered, read status refer the message callback listeners.

Message receipts is a feature which allows users to know the status of the sent messages as well as the delivered and read time for the messages. The chat app users are well informed about the status of the sent messages.

You need to update the ongoing chat user jid always whenever you are entering/exiting the chat window of user by using below method. it is used by plugin internally for receipts.

In Lifecycle Listener resume state, set the user jid as ongoing chat user.

Argument	Type	Description
JID	`String`	jid of the chat user

Mirrorfly.setOnGoingChatuser(JID);

Then, in Lifecycle Listener pause state, clear the ongoing chat user.

Mirrorfly.setOnGoingChatuser("");

Mark messages as delivered#

You don't need to send the delivery receipts explicitly, it will be automatically sent by the sdk.

Mark messages as read#

Once the user reads the messages of user B or entered into the chat window of user B, you can mark the messages as read by using the below method. In this case user B's jid will be passed to the below method. Then read receipts will be managed by sdk. sdk will utilise the ongoing chat user jid which is set by this method Mirrorfly.setOnGoingChatuser(JID);

Argument	Type	Description
JID	`String`	jid of the chat user

Mirrorfly.markAsRead(JID).then((bool? value) {

}).catchError((error) {
  // Error handling
});

Mark Conversations as read#

To set Multiple Conversations as Read, use this below method.

Argument	Type	Description
jidlist	`List<String>`	list of jid of the chats

Mirrorfly.markConversationAsRead(jidlist);

Get single chat message status#

To get the time of sent, delivered and seen status of a message sent by you in a single one to one chat call the below method.

Mirrorfly.getMessageStatusOfASingleChatMessage(MESSAGE_ID).then((value) {
  var response = json.decode(value);
  var seenTime = response["seenTime"];
  var deliveredTime = response["deliveredTime"];
})

Argument	Type	Description
MESSAGE_ID	`String`	message id of the message

Remove unread message separator#

To remove the unread message separator in a chat conversation list call the below method.

Argument	Type	Description
JID	`String`	Jid of the user/group

Mirrorfly.deleteUnreadMessageSeparatorOfAConversation(JID).then((bool? value) {
      
})

Upload/Download media message#

Whenever you receive a media message from a user, or when retrying to upload a already sent media message you can use built-in sdk functions to upload/download the media content / The below method is applicable only if you are using sdk media server, otherwise you have to handle uploading/downloading the media by your own implementation as well as update the status of the media message.

Mirrorfly.uploadMedia(MEDIA_MESSAGE_ID);

Mirrorfly.downloadMedia(MEDIA_MESSAGE_ID);

Argument	Type	Description
MEDIA_MESSAGE_ID	`String`	Id of the media message

Note : In Mirrorfly.initializeSDK() storageFolderName should be defined to set your own local path to store app media files.

Update media status#

Cancel upload/download#

Whenever you would like to cancel upload/download of a media message , you can use built-in sdk functions to cancel the media content upload/download.The below method is applicable only if you are using sdk media server, otherwise you have to handle cancelling the media by your own implementation as well as update the status of the media message.

Argument	Type	Description
messageId	`String`	message id of the media message

Mirrorfly.cancelMediaUploadOrDownload(messageId);

When the user cancelled the media download, then user need to restart the download using Mirrorfly.downloadMedia(MEDIA_MESSAGE_ID); method. In case of media upload, the upload initiated once the user sent the message In case of retry call Mirrorfly.uploadMedia(MEDIA_MESSAGE_ID);.

Encrypt/Decrypt media files#

To encrypt all media files while uploading to server, call below method to enable media encryption in SDK

Mirrorfly.setMediaEncryption(true);

Note: If this flag enabled then all type of media files will be encrypted while uploading and stored in server, On receiver side media files will be decrypted while downloading and readable file will be stored in local storage.