The QuickBlox Developer Hub

Welcome to the QuickBlox developer hub. You'll find comprehensive guides and documentation to help you start working with QuickBlox as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

This is our new 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.

Chat API is built on top of real-time (XMPP) protocol. In order to use it you need to setup real-time connection with QuickBlox Chat server and use it to exchange data. By default, real-time Chat works over secure TLS connection.

Connect to Chat server

To connect to Chat server use the code snippet below.

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

Check if connected to Chat server

Check the connection state using the following code snippet.

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

Disconnect from Chat server

Disconnect from the Chat server using the snippet below.

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

Reconnection

The SDK reconnects automatically when the connection to the Chat server is lost. There is a way to disable it and then manage it manually.

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

Chat in background

To handle correctly do disconnect() when an app goes to background and connect() when an app goes to the foreground.

Dialogs

All chats between users are organized in dialogs. There are 3 types of dialogs:

  • 1-1 dialog - a conversation between 2 users.
  • group dialog - a conversation between the specified list of users.
  • public dialog - an open conversation. Any user from your app can subscribe to it.

You need to create a new dialog and then use it to chat with other users. You also can obtain a list of your existing dialogs.

Create new dialog

Create 1-1 dialog

You need to pass QBChatDialogTypes.CHAT as a type and ID of an opponent you want to create a chat with.

try {
  QBDialog createdDialog = await QB.chat.createDialog(
      [234234324, 3243243],    
      "Private Chat", 
      dialogType: QBChatDialogTypes.CHAT);
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}
Parameters
Description

occupantIds

ID of the opponent.

dialogName

Name of a dialog.

dialogType

(optional) Type of a dialog. By default, a
public dialog
will be created.

Create group dialog

You need to pass QBChatDialogTypes.GROUP_CHAT as a type and IDs of opponents you want to create a chat with.

try {
  QBDialog createdDialog = await QB.chat.createDialog(
      [234234324, 3243243],
      "Group Chat", 
      dialogType: QBChatDialogTypes.GROUP_CHAT);
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}
Parameters
Description

occupantIds

List of opponents.

dialogName

Name of a dialog.

dialogType

(optional) Type of a dialog. By default, a
public dialog
will be created.

Create public dialog

It's possible to create a public dialog, so any user from your application can subscribe to it. There is no a list with occupants, this dialog is just open for everybody. You need to pass QBChatDialogTypes.PUBLIC_CHAT as a type to create a public dialog:

try {
  QBDialog createdDialog = await QB.chat.createDialog(
      [234234324, 3243243],
      "Public Chat", 
      dialogType: QBChatDialogTypes.PUBLIC_CHAT);
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}
Parameters
Description

occupantIds

List of opponents.

dialogName

Name of a dialog.

dialogType

(optional) Type of a dialog. By default, a
public dialog
will be created.

Retrieve list of dialogs

It's common to request all your conversations on every app login.

try {
  List<QBDialog> dialogs = await QB.chat.getDialogs(
      sort: qbSort, 
      filter: qbFilter, 
      limit: limit, 
      skip: skip);
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}
Parameters
Description

sort

(optional) Parameter for sorting dialogs.

filter

(optional) Parameter for filtering dialogs.

limit

(optional) Limit load dialog quantity.

skip

(optional) Quantity skipped dialogs.

It will return all your 1-1 dialogs, group dialogs, and public dialogs you are subscribed to.

If you want to retrieve only conversations updated after some specific date time, you can pass the filter. This is useful if you cache conversations somehow and do not want to obtain the whole list of your conversations on every app start.

Update dialog

Update a group dialog name and occupants using updateDialog() method.

try {
  QBDialog updatedDialog = await QB.chat.updateDialog(
      dialogId,
      addUsers: addUsers, 
      removeUsers: removeUsers, 
      dialogName: dialogName);
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}
Parameters
Description

dialogId

ID of a dialog.

addUsers

(optional) List of users that will be added.

removeUser

(optional) List of users that will be removed.

dialogName

(optional) Name of a dialog.

Important note

Only group dialog owner and admins can remove other users from a group dialog.

Remove dialog

The following snippet is used to delete a conversation.

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

Important note

Only dialog owner can remove the conversation for all users.

Chat history

Every chat conversation stores its chat history which you can retrieve.

try {
  List<QBMessage> messages = await QB.chat.getDialogMessages(
    	dialogId, 
    	sort: qbSort, 
    	filter: qbFilter, 
    	limit: limit, 
    	skip: skip, 
    	markAsRead: false);
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}
Parameters
Description

dialogId

ID of a dialog.

sort

(optional) Parameter for sorting messages.

filter

(optional) Parameter for filtering messages.

limit

(optional) Limit of load messages.

skip

(optional) Quantity of skipped dialogs.

markAsRead

(optional) Mark loaded messages read.

If you want to retrieve chat messages that were sent after or before a specific date-time only, you can use the filter. This is useful if you implement pagination for loading messages in your app.

Pay attention

All retrieved chat messages will be marked as read after the request. If you decide not to mark chat messages as read, then make sure to add markAsRead parameter as false to your request.

Send/Receive chat messages

Receive messages

To receive a notification from SDK about a new incoming message, you have to subscribe to such events using subscribeMessageEvents.

try {
  await QB.chat.subscribeMessageEvents(dialogId, eventName, (data) {
    Map<String, Object> map = new Map<String, dynamic>.from(data);
    String messageType = map["type"];
    String messageBody = "system message";
    if (messageType == QBChatEvents.RECEIVED_NEW_MESSAGE) {
      Map<String, Object> payload =
          new Map<String, dynamic>.from(map["payload"]);
      messageBody = payload["body"];
      messageId = payload["id"];
    }
  });
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

After subscribing to message events you have to set up events listener to handle different connection states, message events, etc.

// Subscribe to event connections  
try {
  await QB.chat.subscribeEventConnections(eventName, (data) {
    // Some logic                                 
  });
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

// Subscribe to event typing
try {
  await QB.chat.subscribeTyping(dialogId, eventName, (data) {
  	Map<String, Object> map = new Map<String, dynamic>.from(data);
    Map<String, Object> payload = new Map<String,dynamic>.from(map["payload"]);
  });
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

// Subscribe to event message status
try {
  await QB.chat.subscribeMessageStatus(dialogId, eventName, (data) {
    // Some logic 
  });
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

Pay attention

Messages from group & public chat dialogs will be received in this callback only after you join the dialogs.

1-1 dialog

To send a message to 1-1 dialog use the code snippet below.

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

dialogId

ID of dialog.

messageBody

(optional) Body of a message.

attachments

(optional) List of attachments.

properties

(optional) List of properties.

markable

(optional) Markable status of a message.

dateSent

(optional) Date sent message.

saveToHistory

(optional) save to history message.

Group/public dialog

Join group/public dialog

Before you start chatting in a group/public dialog, you need to join it by calling join() method.

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

Send a message to group/public dialog

To send/receive messages to the group/public dialog use the following code snippet:

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

Note

Use the same code snippet to send/receive messages for 1-1 dialog, group dialog, and public dialog.

Leave group/public dialog

You can leave the group/public dialog by calling leaveDialog() method.

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

Updated 10 days ago


What's Next

Advanced

Chat


Suggested Edits are limited on API Reference Pages

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