Advanced

Message statuses

Every message has statuses as sent, delivered and read. Thus, in the message model, you can find IDs of users who have read the message (status read) or who have received the message but it still unread (status delivered). There is no field for a sent status in the message model.

Sent status

If you want to definitely know that your message has been delivered to the server, you should enable stream management. In order to use the feature you need to enable it when passing within the config class to QuickBlox.init() method. See this section to learn how to enable stream management.

To handle the message sent event, the onSentMessageCallback() is used.

QB.chat.onSentMessageCallback = function (messageLost, messageSent) {
    
};

📘

To receive callbacks when your message becomes sent, use QB.chat.onMessageListener. Follow Subscribe to receive messages to learn how to add the listener.

🚧

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.

Delivered status

To handle the message delivered event, the onDeliveredStatusListener() callback is used.

QB.chat.onDeliveredStatusListener = function(messageId, dialogId, userId){
    
}

📘

To receive callbacks when your message becomes delivered, use QB.chat.onMessageListener. Follow Subscribe to receive messages to learn how to add the listener.

The SDK sends a notification about the delivered status automatically when the message is received by the recipient. This is controlled by the markable parameter when you send a message.

var message = {
  type: "chat",
  body: "How are you today?",
  extension: {
    save_to_history: 1,
    dialog_id: "5356c64ab35c12bd3b108a41"
  },
  markable: 1
};

var opponentId = 78;
message.id = QB.chat.send(opponentId, message);

// ...

If markable is false or omitted, then you can send a notification about the delivered status by using the sendDeliveredStatus() method.

var params = {
  messageId: "557f1f22bcf86cd784439022",
  userId: 21,
  dialogId: "5356c64ab35c12bd3b108a41"
};

QB.chat.sendDeliveredStatus(params);

Read status

To handle the message read event, the onReadStatusListener() callback is used.

QB.chat.onReadStatusListener = function(messageId, dialogId, userId) {
};

📘

To receive callbacks when your message becomes read, use QB.chat.onMessageListener. Follow Subscribe to receive messages to learn how to add the listener.

To send a notification about the read status, use the sendReadStatus() method.

var params = {
  messageId: "557f1f22bcf86cd784439022",
  userId: 21,
  dialogId: "5356c64ab35c12bd3b108a41"
};

QB.chat.sendReadStatus(params);

Is typing status

The following notifications are 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 handle the message typing or stopped typing event, the onMessageTypingListenerr() callback is used.

QB.chat.onMessageTypingListener = function(isTyping, userId, dialogId) {
  if (isTyping) {
        // the user(userId) is typing in the chat(dialogId)
  } else {
        // the user stopped typing
  }
};

📘

To receive callbacks about the typing/stopped typing message status, use QB.chat.onMessageListener. Follow Subscribe to receive messages to learn how to add the listener.

Send a notification about the typing status to the private or group dialog using the sendIsTypingStatus() method.

QB.chat.sendIsTypingStatus(currentDialog.jidOrUserId);

Send a notification about the stopped typing status to the private or group dialog using the sendIsStopTypingStatus() method.

QB.chat.sendIsStopTypingStatus(currentDialog.jidOrUserId);

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.

var message = {
  type: 'groupchat',
  body: "How are you today?",
  extension: {
    save_to_history: 1,
    customParam1: "book",
    customParam2: "21"
  }
};

QB.chat.send(jidOrUserId, message);

Set the following fields of the message:

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.

// for example, a file from HTML form input field
var inputFile = $("input[type=file]")[0].files[0];

var fileParams = {
  name: inputFile.name,
  file: inputFile,
  type: inputFile.type,
  size: inputFile.size,
  public: false
};
QB.content.createAndUpload(fileParams, function(error, result) {
  if (!error) {
    // prepare a message
    var message = {
      type: dialog.type === 3 ? "chat" : "groupchat",
      body: "[attachment]",
      extension: {
        save_to_history: 1,
        dialog_id: dialog._id,
        attachments: [{ id: result.uid, type: "image" }]
      }
    };

    // send the message
    // ...
  }
});

If you are running Node.js environment, the following code snippet can be used to access a file.

const fs = require("fs");

var imagePath = __dirname + "/dog.jpg";

fs.stat(imagePath, function(statError, stats) {
  if (statError) {
    throw statError;
  }
  fs.readFile(imagePath, function(readError, data) {
    if (readError) {
      throw readError;
    }
    var fileParams = {
      file: data,
      name: "image.jpg",
      type: "image/jpeg",
      size: stats.size
    };

    // upload
    // ...
  });
});

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.

QB.chat.onMessageListener = function(userId, message) {
  if (message.extension.hasOwnProperty("attachments")) {
    if (message.extension.attachments.length > 0) {
      var fileUID = message.extension.attachments[0].uid;
      var fileUrl = QB.content.privateUrl(fileUID);
      var imageHTML = "<img src='" + fileUrl + "' alt='photo'/>";
    }
  }
};

Update message

Update the message text using the update() method.

var messageId = '5f3a7fd75799727266000001';
var updateParams = {
  chat_dialog_id: '5f3166c4a0eb47592eab07aa',
  message: 'Message updated!'
};
QB.chat.message.update(messageId, updateParams, function (error) {
  // if error occurred - error will be returned
});

Delete message

The owner of the dialog can completely remove messages from all users' histories. This is achieved by setting the force=1. However, it is not the same for dialog participants. They can remove messages only from current user history, without affecting the histories of other users.

var params = {
    force: 1 // remove message from all users' histories
};
QB.chat.message.delete(["55fd42369575c12c2e234c64"], params, function(error, result) {}
);

Set the following fields of the params:

Offline messaging

When you send a chat message and the recipient/recipients is offline, then automatic push notification will be fired. To receive push notifications you need to subscribe for them. Please refer to Push Notifications guide.

To configure push template that users receive, go to Dashboard => YOUR_APP => Chat => Offline messaging.

🚧

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

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 are handled over a separate channel and are not be mixed up with regular chat messages. Thus, they are handled by the onSystemMessageListener callback.

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.

var message = {
  body: "Notification message",
  extension: {
    param1: "value1",
    param2: "value2",
  },
};

var opponentId = 34;

QB.chat.sendSystemMessage(opponentId, message);
// or message.id = QB.chat.sendSystemMessage(opponentId, message) if message ID is needed

//...

QB.chat.onSystemMessageListener = function (receivedMessage) {};

Set the following fields of the message:

Check if a user is online

You can request online users via a group dialog.

var dialogId = "...";
var dialogJid = QB.chat.helpers.getRoomJidFromDialogId(dialogId);
 
QB.chat.muc.listOnlineUsers(dialogJid, function(users) {
 
});

Contact list

The Contact List API is rather straightforward. User A sends a request to become "friends" with user B. User B accepts the friend request. And now user A and B appear in each other's roster.

Access contact list

You can access the contact list on your login to chat. The contact list object will be returned in callback. Also, the following function gives you an access to contact list.

QB.chat.roster.get(function(contactlist) {
    
});

Add user to your contact list

To add a user to the contact list, use the add() method.

var userId = 34;
QB.chat.roster.add(userId, function() {
    
});

📘

Maximum number of contacts is 300.

Another user will receive a request to be added to the contact list. The onSubscribeListener callback will be called.

QB.chat.onSubscribeListener = function(userId) {
    
};

Confirm the contact request

To confirm the request, use the confirm() method.

QB.chat.roster.confirm(userId, function() {
    
});

A user will be informed that you have accepted the contact request by the onConfirmSubscribeListener callback.

QB.chat.onConfirmSubscribeListener = function(userId) {
    
};

Reject the contact request

To reject the request, use the reject() method.

QB.chat.roster.reject(userId, function() {
    
});

A user will be informed that you have declined the contact request by onRejectSubscribeListener callback.

QB.chat.onRejectSubscribeListener = function(userId) {
    
};

Remove user from the contact list

To remove a previously added user from the contact list, use the following method.

QB.chat.roster.remove(userId, function() {
    
});

Contact list updates

You can also track contact list updates in real-time by using delegates.

QB.chat.onContactListListener = function(userId, type) {
  // type - if a user left the chat, type will be 'unavailable'.
  // Otherwise - 'available'.
};

Privacy (black) list

Privacy list API allows enabling or disabling communication with other users in a chat. You can create, modify, or delete privacy lists, define a default list.

📘

The user can have multiple privacy lists, but only one can be active.

Create privacy list

A privacy list must have at least one element in order to be created. You can choose a type of blocked logic. There are 2 types:

• Block in one way. When you blocked a user, but you can send messages to them.
• Block in two ways. When you blocked a user, but you can't send messages to them.

var users = [
  { user_id: 34, action: "deny" },
  { user_id: 48, action: "deny", mutualBlock: true }, // it means you can't write to user
  { user_id: 18, action: "allow" }
];
var list = { name: "myList", items: users };

QB.chat.privacylist.create(list, function(error) {});

📘

In order to be used the privacy list should be not only set but also activated (set as default).

Activate privacy list

In order to activate rules from a privacy list you should set it as default.

QB.chat.privacylist.setAsDefault("myList", function(error) {
    
});

Update privacy list

There is a rule you should follow to update a privacy list: if you want to update or set a new privacy list instead of the current one, you should decline the current default list first.

QB.chat.privacylist.getNames(function(error, result) {
  if (!error) {
    var names = result.names;
  }
});

Retrieve privacy lists

To get a list of all your privacy lists names, use the following request.

QB.chat.privacylist.setAsDefault(null, function(error) {
  if (!error) {
    var users = [{ user_id: 34, action: "allow" }];
    var list = { name: "myList", items: users };

    QB.chat.privacylist.update(list, function(error) {
      if (!error) {
        QB.chat.privacylist.setAsDefault("myList", function(error) {});
      }
    });
  }
});

Retrieve privacy list by name

To get the privacy list by name, you should use the following method.

QB.chat.privacylist.getList("myList", function(error, result) {
  if (!error) {
    var name = result.name;
    var items = result.items;
  }
});

Remove privacy list

To delete a list, you can call a method below or you can edit a list and set items to nil.

QB.chat.privacylist.delete("myList", function(error) {
    
});

Blocked user attempts to communicate with user

A user can be blocked in 1-1 dialog and group dialog. In this case, the blocked user receives an error when trying to send a message in a 1-1 dialog and receives nothing when trying to send a message in group dialog.

QB.chat.onMessageErrorListener = function (messageId, error){
    
}