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 and devices. Check out our detailed guides to make integration easy and fast.

Chat

Learn how to enable chat functionality for your app.

🚧

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

To receive events about connections, you have to subscribe to such events using subscribeEventConnections.

//Chat Connections
//QBChatEvents.CONNECTED
//QBChatEvents.CONNECTION_CLOSED
//QBChatEvents.RECONNECTION_FAILED
//QBChatEvents.RECONNECTION_SUCCESSFUL

try {
  await QB.chat.subscribeEventConnections(eventName);
    String type = data["type"];
} on PlatformException catch (e) {
  // Some error occured, look at the exception message for more details
}

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
}

Autoreconnect to Chat

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.

class _SomeScreenState extends State<SomeScreen> with WidgetsBindingObserver {
  
//...

@override
initState() {
  super.initState();
  WidgetsBinding.instance.addObserver(this);
}

@override
void dispose() {
  WidgetsBinding.instance.removeObserver(this);
  super.dispose();
}
  
@override
void didChangeAppLifecycleState(AppLifecycleState state) {
  switch (state) {
    case AppLifecycleState.resumed:
      try {
        await QB.chat.connect(userId, userPassword);
        } on PlatformException catch (e) {
        // Some error occured, look at the exception message for more details
        }
      break;
    case AppLifecycleState.paused:
      print("app in paused");
      try {
        await QB.chat.disconnect();
      } on PlatformException catch (e) {
        // Some error occured, look at the exception message for more details
        }
      break;
}
  
//...
ParametersDescription
userIdThe ID of a user.
userPasswordThe password of the user.

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
}
ParametersDescription
occupantIdsIDs of opponents.
dialogNameThe name of the dialog.
dialogType(optional) A 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
}
ParametersDescription
occupantIdsA list of opponents.
dialogNameThe name of the dialog.
dialogType(optional) A type of the dialog. By default, the 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
}
ParametersDescription
occupantIdsA list of opponents.
dialogNameThe name of the dialog.
dialogType(optional) A type of the dialog. By default, the 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
}
ParametersDescription
sort(optional) A parameter for sorting dialogs.
filter(optional) A parameter for filtering dialogs.
limit(optional) A limit load dialog quantity.
skip(optional) A quantity of 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
}
ParametersDescription
dialogIdThe ID of the dialog.
addUsers(optional) A list of users that will be added.
removeUser(optional) A list of users that will be removed.
dialogName(optional) A name of the dialog.

❗️

Important note

Only group dialog owner 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
}
ParametersDescription
dialogIdThe ID of the dialog.
sort(optional) A parameter for sorting messages.
filter(optional) A parameter for filtering messages.
limit(optional) A limit of load messages.
skip(optional) A quantity of skipped dialogs.
markAsRead(optional) A 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
}

🚧

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
}
ParametersDescription
dialogIdThe ID of a dialog.
messageBody(optional) A body of a message.
attachments(optional) A list of attachments.
properties(optional) A list of properties.
markable(optional) A markable status of a message.
dateSent(optional) The date the message was sent.
saveToHistory(optional) Save the message to the history.

📘

Note

Make sure to pass the saveToHistory: true to the sendmessage() method. The field is read by the server, and, consequently, the message is stored in the history. If the saveToHistory field is not specified, the message is no longer saved on the server.

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.

📘

Note

Make sure to pass the saveToHistory: true to the sendmessage() method. The field is read by the server, and, consequently, the message is stored in the history. If the saveToHistory field is not specified, the message is no longer saved on the server.

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 17 days ago


What's Next

Advanced

Chat


Learn how to enable chat functionality for your app.

Suggested Edits are limited on API Reference Pages

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