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);
Argument | Required | Description |
---|---|---|
userId | yes | ID of the opponent. Pass opponet ID for |
jid | yes | Room JID. JID (Jabber ID) of XMPP room in the XMPP server. Pass room JID for You can get JID from the dialog ID. The JID format is the following: <app_id>-<dialog_id>@muc.chat.quickblox.com |
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);
Argument | Required | Description |
---|---|---|
jidOrUserId | yes | User ID or Room JID. JID (Jabber ID) of XMPP room in the XMPP server. Empty for a privatΠ΅ dialog. Generated automatically by the server after dialog creation. You can get JID from the dialog ID. The JID format is the following: <app_id>-<dialog_id>@muc.chat.quickblox.com. |
message | yes | Specifies message fields that should be set. |
Set the following fields of the message
:
Field | Required | Description |
---|---|---|
type | no | Message type. Possible values: |
body | no | A message text. |
extension | no | Extra data. Specify any key-value pairs. In each pair, the key and value are both string values. Set |
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
});
Parameters | Required | Description |
---|---|---|
messageId | yes | ID of the message being updated. |
updateParams | yes | Specifies key-value fields that should be updated. |
function | yes | Specifies the callback function which receives the response from the QuickBlox server for the updating request. |
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
:
Field | Required | Description |
---|---|---|
force | no | Delete message for everyone. Set |
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) {};
Parameters | Description |
---|---|
opponentId | ID of the opponent. |
message | Specifies system message fields that should be updated. |
Set the following fields of the message
:
Fields | Required | Description |
---|---|---|
body | no | A system notification text. |
extension | no | Extra data. Specify one or more key-value pairs. In each pair, the key and value are both string values. |
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){
}
Updated 29 days ago
What's Next
Video Calling |