QuickBlox Documentation

QuickBlox provides powerful Chat API and SDK to add real-time messaging and video calls to your web and mobile apps. Learn how to integrate QuickBlox across multiple platforms.

Advanced

Learn how to manage message statuses, attachments, and offline messaging.

🚧

This is our documentation for alpha version of QuickBlox Flutter SDK. Please contact our Customer Support Team to provide your feedback, suggestions, and requests to improve this page.

Mark message as delivered

As a sender, you may want to be informed that a message has been successfully delivered to the recipient. Use the mark-as-delivered functionality to receive confirmation about message delivery.

To track the event when the message is delivered to the user, you need to subscribe to this event. As a result, when a user receives a message, the SDK receives the MESSAGE_DELIVERED event.

StreamSubscription _deliveredMessageSubscription;

...

@override
void dispose() {
  _deliveredMessageSubscription.cancel();
}

...

try {
  _deliveredMessageSubscription = await QB.chat.subscribeChatEvent(QBChatEvents.MESSAGE_DELIVERED, (data){
   LinkedHashMap<dynamic, dynamic> messageStatusHashMap = data;
   Map<String, Object> messageStatusMap = new Map<String,Object>.from(messageStatusHashMap);
   Map<String, Object> payloadMap = new Map<String,Object>.from(messageStatusHashMap["payload"]);

  String messageId = payloadMap["messageId"];
  String userId = payloadMap["userId"];
  String statusType = messageStatusMap["type"];
    }
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

Use the markMessageDelivered() method to mark a message as delivered. As a result, the server will notify a sender about the delivery receipt.

try {
  await QB.chat.markMessageDelivered(qbMessage);
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

A message can be marked as delivered automatically by the server when a message has been successfully delivered to the recipient. Set markable as true using the sendMessage() method if you want, as a sender, to receive message delivery receipts from other recipients. Thus, the markable parameter enables the sender to request the delivery receipt. It also enables the recipient to confirm the message delivery. However, if markable is false or omitted, then you can notify a sender about the delivery receipt using the markMessageDelivered().

try {
  await QB.chat.sendMessage(
    dialogId, 
    body: messageBody, 
    attachments: attachments, 
    properties: properties, 
    markable: true, 
    dateSent: dateSent, 
    saveToHistory: true);
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

📘

Make sure to understand, that marking-as-delivered operation just confirms the fact of message delivery. The message acquires the delivered status when the message delivered event is received.

When a message is marked as delivered, the IDs of users who have received the message are stored in the message model, on the server. Thus, you can request a chat history from the server to get to know who received the message using the getDialogMessages() method. See this section to learn how to retrieve chat history.

Sent status

If you want to definitely know that your message has been delivered to the server you should enable stream management before connecting to the Chat server. See this section to learn how to enable stream management.

Then, you send a message to the server and if no error is returned, it is considered as sent (by default). There is no field for a sent status in the message model.

try {
  await QB.chat.sendMessage(dialogId, body: messageBody);
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details    
}

🚧

You should enable Stream Management before you do the login() because the Stream Management is initialized while Chat login is performed.

The Stream Management defines an extension for active management of a stream between a client and server, including features for stanza acknowledgments.

Mark message as read

As a sender, you may want to be informed that a message has been read by the recipient. Use the mark-as-read functionality to receive confirmation that a message has been read.

To track the event when the message is read to the user, you need to subscribe to this event using the code snippet below. As a result, when a user reads a message, the SDK receives the MESSAGE_READ event.

StreamSubscription _readMessageSubscription;

...

@override
void dispose() {
  _readMessageSubscription.cancel();
}

...

try {
  _readMessageSubscription = await QB.chat.subscribeChatEvent(QBChatEvents.MESSAGE_READ, (data){
   LinkedHashMap<dynamic, dynamic> messageStatusHashMap = data;
   Map<String, Object> messageStatusMap = new Map<String,Object>.from(messageStatusHashMap);
   Map<String, Object> payloadMap = new Map<String,Object>.from(messageStatusHashMap["payload"]);

  String messageId = payloadMap["messageId"];
  String userId = payloadMap["userId"];
  String statusType = messageStatusMap["type"];
    }
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

Use the markMessageRead() method to mark a message as read. As a result, the server will notify a sender about the read receipt.

try {
  await QB.chat.markMessageRead(qbMessage);
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

📘

When a message is marked as read, the IDs of users who have read the message stored in the message model, on the server. Thus, you can request a chat history from the server to get to know who read the message using the getDialogMessages() method. See this section to learn how to retrieve chat history.

Send typing indicators

You may want, as a sender, to let the recipient know that you are typing the message or have stopped typing the message. Use typing indicators as a form of chat-specific presence. Typing indicators enable you to indicate if users are typing messages in a dialog at the moment.

There are the following typing notifications supported.

  • typing. The user is composing a message. The user is actively interacting with a message input interface specific to this chat session (e.g. by typing in the input area of a chat window).
  • stopped. The user had been composing but now has stopped. The user has been composing but has not interacted with the message input interface for a short period of time (e.g. 30 seconds).

To track the event when the sender is typing the message, you need to subscribe to this event. As a result, when a sender is typing a message, the SDK receives the USER_IS_TYPING event.

StreamSubscription _userTypingSubscription;

...

@override
void dispose() {
  _userTypingSubscription.cancel();
}

...

try {
  _userTypingSubscription = await QB.chat.subscribeChatEvent(QBChatEvents.USER_IS_TYPING, (data){
   Map<String, Object> map = new Map<String, dynamic>.from(data);
   Map<String, Object> payload = 
     new Map<String, dynamic>.from(map["payload"]);
   int userId = payload["userId"];
    }
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

To track the event when the sender has stopped typing, you need to subscribe to this event. Thus, when a sender has stopped typing a message, the SDK receives the USER_STOPPED_TYPING event.

StreamSubscription _userStopTypingSubscription;

...

@override
void dispose() {
  _userStopTypingSubscription.cancel();
}

...

try {
  _userStopTypingSubscription = await QB.chat.subscribeChatEvent(QBChatEvents.USER_STOPPED_TYPING, (data){
   Map<String, Object> map = new Map<String, dynamic>.from(data);
   Map<String, Object> payload = 
     new Map<String, dynamic>.from(map["payload"]);
   int userId = payload["userId"];
    }
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

To notify a recipient that a sender is typing the message, use the sendIsTyping() method. As a result, the server will notify a recipient about the event.

try {
  await QB.chat.sendIsTyping(dialogId);
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

To notify a recipient that a sender had been composing a message but now has stopped, use the sendStoppedTyping() method. As a result, the server will notify a recipient about the event.

try {
  await QB.chat.sendStoppedTyping(dialogId);
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

Add extra data to a message

You have the option to extend the message with additional fields. Specify one or more key-value items to the message. Using these items, you can implement the ability for a user to send self-location information to another user or notification messages signifying that a user has left a group, etc.

try {
  String dialogId = "dsfs9344349hjkdsda9877932j2";
  String body: 'How are you today!';
  
  Map<String, Object> properties = Map();
  properties["customParam1"] = "book";
  properties["customParam2"] = 21;
  
  await QB.chat.sendMessage(dialogId, body: body, saveToHistory: true, properties: properties);
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

Argument

Required

Description

dialogId

yes

ID of a dialog.

body

no

A message text.

saveToHistory

no

Specifies if the message will be saved on the server. Set the saveToHistory as true to save the message on the server.

properties

no

Extra data. Specify any key-value pairs. In each pair, the key and value are both string values.

Attachments

Chat attachments are supported by the cloud storage API. In order to send a chat attachment, you need to upload the file to QuickBlox cloud storage and obtain a link to the file (file UID). Then you need to include this UID into chat message and send it.

try {
  QBFile file = await QB.content.upload(url, public: false);
  int id = file.id;
  String contentType = file.contentType;
     
  QBAttachment attachment = new QBAttachment();
  attachment.id = id.toString();
  attachment.contentType = contentType;

  //Required parameter
  attachment.type = "PHOTO";
  
  QBMessage message = new QBMessage();
  List<QBAttachment> attachmentsList = new List();
  attachmentsList.add(attachment);
     
  message.attachments = attachmentsList;
  
  // Send a message logic
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

The flow on the receiver's side is the following: when you receive a message, you need to get the file URL to download the file from the cloud storage.

//uid = attachment.id

try {
  String url = await QB.content.getPrivateURL(uid);
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

Offline messaging

The offline messaging functionality allows for customizing automatic push notifications displayed on a user's device when they are offline. In other words, if your opponent is offline when you are writing a message, they can automatically receive a push notification.

📘

Make sure to subscribe your users to pushes using SDKs. Review Push Notifications section for more details.

Offline messages are customized from the Dashboard. Just follow Dashboard => YOUR_APP => Chat => Offline messaging directory to locate offline messaging settings.

Here you will find the following settings:

  • Enable automatic push notifications for offline users - check it to receive push notifications from the server automatically.
  • Offline messaging text - text of your push notification.
  • Templates - set push notification template here. Use template variables to engage your push message.
  • Badge counter - set badge counter to include counter info into your push message. Useful to include unread counter - the number of unread messages a user has.
  • Sound - set push notification sound (for iOS only).
  • Category - describes "actions" that should be presented in the app notification in various views (for iOS only).
  • Content Available - enable it to indicate that new content is available (for iOS only).
  • Mutable content - enable it to modify the content of newly delivered notifications before the user is alerted. Use a notification service app extension to be able to modify the content of the notification. If the option is enabled, the system passes the notification to the service app extension for the subsequent modification of the notification payload before the actual delivery (for iOS only).

🚧

Currently, push notifications are supported in the mobile environment only.

📘

Set saveToHistory as true when sending messages to apply offline pushes. Review this section for mode details.

Send system messages

There is a way to send system messages to other users about some events. For example, a system message can be sent when a user has joined or left a group dialog. These messages work over a separate channel and are not be mixed up with regular chat messages. Thus, in order to receive these messages, you should subscribe to the QBChatEvents.RECEIVED_SYSTEM_MESSAGE event. See this section to learn how to subscribe to message events.

System messages are also not shown in the dialog history and, consequently, are not stored on the server. This means that these messages will be delivered only to online users. Send system messages using the sendSystemMessage() method.

try {
  int recipientId = 109364799;
  Map<String, Object> properties = Map();
  properties["someKey"] = "someValue";

  await QB.chat.sendSystemMessage(recipientId, properties: properties);
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

Parameters

Required

Description

recipientId

yes

ID of the recipient.

properties

no

Extra data. Specify any key-value pairs. In each pair, the key and value are both string values.

Check if a user is online

🚧

This feature is coming soon. Please check back later. For more updates and questions, feel free to contact our Customer Support Team.

Contact list

🚧

This feature is coming soon. Please check back later. For more updates and questions, feel free to contact our Customer Support Team.

Privacy (black) list

🚧

This feature is coming soon. Please check back later. For more updates and questions, feel free to contact our Customer Support Team.

Updated 6 months ago


What's Next

Video Calling

Advanced


Learn how to manage message statuses, attachments, and offline messaging.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.