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 beta version of QuickBlox React Native SDK. Please contact our Customer Support Team to provide your feedback, suggestions, and requests to improve this page.

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. We send a message to the server and if no error is returned, then it is considered as sent (by default).

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 Chat. See this section to learn how to enable stream management.

Then, we send a message to the server and if no error is returned, then it is considered as sent (by default).

QB.chat
  .sendMessage(message)
  .then(function () { /* message sent */ })
  .catch(function (e) { /* message is not sent */ });

šŸš§

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 track the event when your message becomes delivered, use the event listener.

import { NativeEventEmitter } from 'react-native'
import QB from 'quickblox-react-native-sdk'

const emitter = new NativeEventEmitter(QB.chat)

function messageDelivered (event) {
  const {
    type, // name of the event (the one you've subscribed for)
    payload, // event data
  } = event
  const {
    dialogId, // in dialog with id specified
    messageId, // message with id specified
    userId // was delivered to user with id specified
  } = payload
  // handle as necessary
}

emitter.addListener(
  QB.chat.EVENT_TYPE.MESSAGE_DELIVERED,
  messageDelivered
);

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.

const message = {
  dialogId: 'dsfsd934329hjhkda98793j2',
  body: 'Hello!',
  markable: true
};

QB.chat
  .sendMessage(message)
  .then(function () { /* message sent */ })
  .catch(function (e) { /* message is not sent */ });

If markable is false or omitted, then a notification about the delivered status is sent using the markMessageDelivered() method.

const param = {
    message: {
        id: 'ghtsd934679hjhkda98793t4',
        dialogId: 'dsfsd934329hjhkda98793j2',
        senderId: 12345
    }
};
QB.chat
  .markMessageDelivered(param)
  .then(function () { /* marked as "delivered" successfully */ })
  .catch(function (e) { /* handle error */ })

Read status

To track the event when your message becomes read, use the event listener.

import { NativeEventEmitter } from 'react-native'
import QB from 'quickblox-react-native-sdk'

const emitter = new NativeEventEmitter(QB.chat)

function messageRead (event) {
  const {
    type, // name of the event (the one you've subscribed for)
    payload, // event data
  } = event
  const {
    dialogId, // in dialog with id specified
    messageId, // message with id specified
    userId // was delivered to user with id specified
  } = payload
  // handle as necessary
}

emitter.addListener(
  QB.chat.EVENT_TYPE.MESSAGE_READ,
  messageRead
);

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

const param = {
    message: {
        id: 'ghtsd934679hjhkda98793t4',
        dialogId: 'dsfsd934329hjhkda98793j2',
        senderId: 12345
    }
};
QB.chat
  .markMessageRead(param)
  .then(function () { /* marked as "read" successfully */ })
  .catch(function (e) { /* handle error */ })

Is typing status

The following typing 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 track the typing message event, use the event listener.

import { NativeEventEmitter } from 'react-native'
import QB from 'quickblox-react-native-sdk'

const emitter = new NativeEventEmitter(QB.chat)

function userTypingHandler(event) {
  const {
    type, // name of the event (the one you've subscribed for)
    payload, // event data
  } = event
  const {
    dialogId, // in dialog with id specified
    userId // user with id specified is typing
  } = payload
  // handle as necessary
}

emitter.addListener(
  QB.chat.EVENT_TYPE.USER_IS_TYPING, userTypingHandler
);

To track the stopped typing message event, use the event listener.

import { NativeEventEmitter } from 'react-native'
import QB from 'quickblox-react-native-sdk'

const emitter = new NativeEventEmitter(QB.chat)

function userStoppedTypingHandler(event) {
  const {
    type, // name of the event (the one you've subscribed for)
    payload, // event data
  } = event
  const {
    dialogId, // in dialog with id specified
    userId // user with id specified stopped typing
  } = payload
  // handle as necessary
}

emitter.addListener(
  QB.chat.EVENT_TYPE.USER_STOPPED_TYPING, userStoppedTypingHandler
);

To send a notification about the typing status, use the sendIsTyping() method.

const param = { dialogId: 'dsfsd934329hjhkda98793j2' };
ā€‹
QB.chat
  .sendIsTyping(param)
  .then(function () { /* sent successfully */ })
  .catch(function (e) { /* handle error */ })

To send a notifcation about the stopped typing status, use the sendStoppedTyping() method.

const param = { dialogId: 'dsfsd934329hjhkda98793j2' };
ā€‹
QB.chat
  .sendStoppedTyping(param)
  .then(function () { /* sent successfully */ })
  .catch(function (e) { /* handle error */ })

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.

const message = {
  dialogId: 'dsfsd934329hjhkda98793j2',
  body: 'How are you today!',
  properties: {
    customParam1: "book",
    customParam2: "21"
  },
  saveToHistory: true
};

QB.chat
  .sendMessage(message)
  .then(function () { /* send successfully */ })
  .catch(function (e) { /* handle error */ })

Argument

Required

Description

message

yes

Specifies message fields that should be set.

Set the following fields of the message:

Field

Required

Description

dialogId

yes

ID of a dialog.

body

no

A message text.

properties

no

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

saveToHistory

no

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

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.

const url = '...' // path to file in local file system
QB.content
  .upload({ url, public: false })
  .then(function (file) {
    // create a message
    const message = {
      attachments: [],
      dialogId: 'dsfsd934329hjhkda98793j2',
      body: 'Hey there!',
      saveToHistory: true
    };
    // attach file
    message.attachments.push({
      id: file.uid,
      type: file.contentType.includes('image') ? 'image' : 'file'
    });
    // send a message
  })
  .catch(function (e) { /* handle file upload error */ });

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.

// received message
const { attachments } = message
const [attachment] = attachments
QB.content
  .getPrivateURL({ uid: attachment.id })
  .then(function (url) { /* you download file using obtained url */ })
  .catch(function (e) { /* handle error */ });

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=true when sending messages to apply offline pushes. Review this section for more 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 are handled 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 QB.chat.EVENT_TYPE.RECEIVED_SYSTEM_MESSAGE event. See this section to learn how to subscribe to this event.

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.

const systemMessage = {
  recipientId: 1234567,
  properties: {
    notification_type: '1',
    dialog_id: '5d75393ba28f9a17e1cb0f9e'
  }
};
QB.chat.sendSystemMessage(systemMessage);

Parameters

Description

systemMessage

Specifies system message fields that should be set.

Set the following fields of the systemMessage:

Fields

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. You can't specify any object, because it won't be passed as an argument.

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 2 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.