Chat

Ask tech team
From QuickBlox Developers (API docs, code samples, SDK)
Jump to: navigation, search

Contents

Introduction

QuickBlox Chat is a quick and reliable chat solution which combines benefits of scalable cloud hosted XMPP chat server, seamless Single Sign-On authorization via Users, incoming IM / chat alerts via Push Notifications and file attachments via Content.

SDKs and code samples are available for iOS, Android, Windows Phone, BlackBerry 5-7 and BB10, also Web (including Facebook and Wordpress) and desktop – QuickBlox Chat is the best and most comprehensive solution so far to have your users communicate cross-platform.

Features

Robust, quick, ‘keep-alive’ connection. Unlimited concurrent connections thanks to QuickBlox auto-scalable AWS powered cloud chat servers infrastructure.

  • 1:1 chat (private user to user chat / IM)
  • Group chat (unlimited chat rooms)
  • Incoming chat alerts (push notifications) for offline users (via Messages)
  • File attachments - cloud hosted via Content so both users don’t have to be online for the transfer to take place. XMPP p2p file transfers are also supported. Allow users to send photos, videos and other files.
  • Location based chat – integrated with Location, have your users chat over map (Google Map, Apple maps, Bing) and see distance to each other, hide or share their location, see internal or Facebook check-ins of other users, manage POIs
  • Photos / Avatars – have users’ Facebook, Linkedin or custom profile photos next to their chat messages
  • Quoting – display citations in chat room replies
  • AR chat – chat in Augmented Reality view
  • Voice chat / call – enable 1:1 voice calls in your app
  • Video chat / call – best video chat SDK for your app
  • Video chat recording – record your video calling session
  • NAT traversal – our TURN server and optimization system take care of NAT traversal and traffic compression making sure your chat, voice and video traffic reaches all users across networks with different configurations
  • 1:1 chat history (Chat-to-CustomObjects plugin)

XMPP features supported

All standard XMPP libraries are supported (please check the list here http://xmpp.org/xmpp-software/libraries/). All standard XEPs and the following additional ones (below) are supported:


XEP-0095 & XEP-0096 are not supported, instead QuickBlox own TURN server takes care of NAT traversal for voice and video traffic streaming.

Connecting to server

Note: these settings are already integrated into iOS/Android/Web SDKs and code samples so you may ignore this section if you’re iOS/Android/Web developer.

Server

Main server: chat.quickblox.com.

MUC (Multi Users Chat): muc.chat.quickblox.com. Important: users registration, authentication and removal must be done via Users API (and not XMPP). 


Login / ID

Each user gets a JID (Jabber ID) in the following format:


<user_id>-<app_id>@chat.quickblox.com

Note: JID is assigned automatically provided users has authenticated at least once in the context of this application. Also note that users will have different JIDs for different apps. For example, user freddy (user_id = 128) chats in both Gunslinger (application_id = 44) and Shoot-a-Zombie (application_id = 78), he will get the following JIDs: 128-44@chat.quickblox.com, 128-78@chat.quickblox.com.

Password

Your user’s password for XMPP connection depends on what type of user authentication via Users you have applied for this particular user:

  • standard login+password authentication: use same password
  • Facebook/Twitter authentication: use session token as password:
QBUUser *user = [QBUUser user];
user.ID = 47892;
user.password = [QBBaseModule sharedModule].token;
QBUser user = new QBUser();
user.setId(47892);
try {
    user.setPassword(BaseService.getBaseService().getToken());
}catch(BaseServiceException e) {
    e.printStackTrace();  
    // means you have not created a session before 
}

Server-side chat history

Chat introduces a very simple server-side chat history functionality. This features is useful for many cases such as moderation, restoring messages on a new device via REST, making chat logs be easily downloadable, etc. We (Quickblox) are not able to read your messages - only you, as the account owner, have access to them.

Just by adding a few custom parameters to your XMPP messages, the messages will be stored on the server (in a Custom Objects like format).

Note: By using Chat 2.0, you are not automatically storing your messages. Also a dialog entity won't be created/updated without saving a message to history.

See below for how to enable server-side chat history in the iOS and Android SDK.

QBChatMessage *message = [QBChatMessage message];
...
[message setCustomParameters:@{@"save_to_history": @YES}];
...
QBChatMessage chatMessage = new QBChatMessage();
...
chatMessage.setProperty("save_to_history", "1");
...
QB.chat.send(jid, {
...
  extension: {save_to_history: 1}
...
});

The correctly formatted XML message will look something like this:

<message id="1114269126" to="11492_53fc460b515c128132016675@muc.chat.quickblox.com" type="groupchat">
	<body xmlns="jabber:client">This is the message text!</body>
	<extraParams xmlns="jabber:client">
		<save_to_history>1</save_to_history>
		<date_sent>1409146118</date_sent>
	</extraParams>
</message>

It doesn't matter what is the value of save_to_history parameter. Chat server just checks a presence of it.

You'll notice there's also a date_sent field in the extra parameters. This is optional - if you don't supply it, the server will automatically add it when it receives the message. But if for example, you need to "resend" a message that failed, you can use this field to specify the correct time. It is in a unix timestamp format.

You can then view this history in the dashboard, or you can retrieve messages via the REST API.

REST API

Chat REST API provides an access to Chat history. We operate with 2 models: Chat Dialog and Chat Message.

Dialog model

Chat Dialog model describes a dialog entity between users (1-1 chat or group chat). Dialog can have custom parameters (described here)

Fields:

Field name Type Description Value Example
_id ObjectID ID of dialog. Generated automatically by server after dialog creation 53a1be95e4b08a80c999dccd
type Enum Type of dialog. Possible values: 1(PUBLIC_GROUP), 2(GROUP), 3(PRIVATE) 2
name String Name of a group chat. Make sense if type=1(PUBLIC_GROUP) or 2(GROUP) Chat with Bob, Sam, Garry
photo String Photo of a group chat. Make sense if type=1(PUBLIC_GROUP) or 2(GROUP). Can contain a link to a file in Content module, Custom Objects module or just a web link 454533
xmpp_room_jid String JID of XMPP room for group chat to connect. Nil if type=3(PRIVATE). Generated automatically by server after dialog creation 92_53a1bdaf535c12eae7000dd1
@muc.chat.quickblox.com
occupants_ids Array of UInteger Array of users' IDs - dialog occupants. Does not make sense if type=1(PUBLIC_GROUP) 44,7893,4567
last_message String Last sent message in this dialog Is anybody here?
last_message_date_sent Timestamp Timestamp of last sent message in this dialog 1403174078
last_message_user_id UInteger ID of user who sent last message in this dialog 45643
unread_messages_count Integer Number of unread messages in this dialog for current user. 12

Message model

Chat Message model describes a chat message in a dialog

Fields:

Field name Type Description Value Example
_id ObjectID ID of message. Generated automatically by server after message creation 43a1be9554b08a87c999d8cd
chat_dialog_id ObjectID ID of dialog to which current message is connected. Generated automatically by server after message creation 63a18e95e4308a80c993dccd
message String Message body Is anybody here?
date_sent Timestamp Message date sent 1403174078
sender_id UInteger Message sender ID 564444
recipient_id UInteger Message recipient ID 39572
read Boolean Flag which indicates was this message read or not by opponent. Will be always 0 for the group chat. 1
attachments Array of attachments objects Each attachment object contains 3 keys:type(audio/video/image), id(link to file ID in QuickBlox), url(link to file in Internet) [{"type":"video","id":"12312"},{"type":"audio","url":"http://mysite.com/audio.wav"}]
Custom parameters Key-value Chat message can contain any other user custom parameters age=25

API requests

URL HTTP Verb Action Description Success HTTP Status Code
/chat/Dialog GET Retrieve dialogs 200
/chat/Dialog POST Create dialog 201
/chat/Dialog/{id} PUT Update dialog 200
/chat/Dialog/{id} DELETE Delete dialog 200
/chat/Message GET Retrieve messages 200
/chat/Message POST Create message 201
/chat/Message/{id1},{id2},{id3}...?chat_dialog_id={id} PUT Update message 200
/chat/Message/{id1},{id2},{id3}... DELETE Delete message 200

Retrieve dialogs

Get all dialogs associated with current user. Server will return all dialogs where current user id is in occupants_ids field OR if type=1(PUBLIC_GROUP). To detect current user id server uses session token.
Search also available for custom parameters (described here).

Parameters

Operator Applied fields Description Usage example
{field_name} all except unread_messages_count Search records with field which contains exactly specified value type=2
{field_name}[{search_operator}] all except unread_messages_count Search record with field which contains value according to specified value and operator.

Possible filters: lt (Less Than operator), lte (Less Than or Equal to operator), gt (Greater Than operator), gte (Greater Than or Equal to operator), ne (Not Equal to operator), in (Contained IN array operator), nin (Not contained IN array), all (ALL contained IN array), or (OR operator), ctn (Contains substring operator)
type[in]=1,2
limit standalone operator Limit search results to N records. Useful for pagination. Default value - 100 limit=50
skip standalone operator Skip N records in search results. Useful for pagination. Default (if not specified): 0 skip=50
count standalone operator Count search results. Response will contain only count of records found count=1
sort_desc/sort_asc type,last_message_date_sent Search results will be sorted by specified field in ascending/descending order sort_desc=last_message_date_sent

Request

curl -X GET -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" https://api.quickblox.com/chat/Dialog
curl -X GET -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" https://api.quickblox.com/chat/Dialog.json
QB.chat.dialog.list({limit: 50}, onDialogs);

Response

<?xml version="1.0" encoding="UTF-8"?>
<chat_dialogs type="array">
  <chat_dialog>
    <_id>53a2bd40e4b0ffe278f44a66</_id>
    <last_message>Is anybody here?</last_message>
    <last_message_date_sent type="integer">1403606412</last_message_date_sent>
    <last_message_user_id type="integer">299</last_message_user_id>
    <name nil="true"/>
    <photo nil="true"/>
    <occupants_ids type="array">
      <occupants_id type="integer">298</occupants_id>
      <occupants_id type="integer">299</occupants_id>
    </occupants_ids>
    <type type="integer">3</type>
    <xmpp_room_jid nil="true"/>
    <unread_messages_count type="integer">0</unread_messages_count>
  </chat_dialog>
  <chat_dialog>
    <_id>53a1be95e4b08a80c999dccd</_id>
    <last_message>Hey guys!</last_message>
    <last_message_date_sent type="integer">1403550532</last_message_date_sent>
    <last_message_user_id type="integer">299</last_message_user_id>
    <name>Chat with Sam, Bob, Garry</name>
    <photo>567681</photo>
    <occupants_ids type="array">
      <occupants_id type="integer">299</occupants_id>
      <occupants_id type="integer">3105</occupants_id>
      <occupants_id type="integer">290</occupants_id>
    </occupants_ids>
    <type type="integer">2</type>
    <xmpp_room_jid>92_53a970c5535c123fed00053b@muc.chat.quickblox.com</xmpp_room_jid>
    <unread_messages_count type="integer">5</unread_messages_count>
  </chat_dialog>
</chat_dialogs>
{ 
    "limit" : 100,
    "skip" : 0
    "items" : [ 
     { 
         "_id" : "53a2bd40e4b0ffe278f44a66",
         "last_message" : "Is anybody here?",
         "last_message_date_sent" : 1403606412,
         "last_message_user_id" : 299,
         "name" : null,
         "photo" : null,
         "occupants_ids" : [ 
            298,
            299
         ],
         "type" : 3,
         "unread_messages_count" : 0,
         "xmpp_room_jid" : null
      },
      { "_id" : "53a970c5535c123fed00053b",
        "last_message" : "Hey guys!",
        "last_message_date_sent" : "1403550532",
        "last_message_user_id" : 299,
        "name" : "Chat with Sam, Bob, Garry",
        "photo" : "567681",
        "occupants_ids" : [ 
            290,
            299,
            3105
         ],
        "type" : 2,
        "unread_messages_count" : 5,
        "xmpp_room_jid" : "92_53a970c5535c123fed00053b@muc.chat.quickblox.com"
      }
    ]
}
var onDialogs = function(err, res) {
  // callback function
};

Create dialog

Use type=1(PUBLIC_GROUP) to create a public group dialog. All the users from your application will be able to join it. Server will create a public group chat and return a detailed information about newly created dialog. Field xmpp_room_jid will contain a Chat room JID to which you should connect to start chatting.

Use type=2(GROUP) to create a group dialog only for specific users provided in occupants_ids. Server will create an only members group chat and return a detailed information about newly created dialog. Field xmpp_room_jid will contain a Chat room JID to which you should connect to start chatting.

Use type=3(PRIVATE) to create a private dialog between 2 users. Server will return a detailed information about newly created dialog. If user sends a chat message to some user and private dialog wasn't created - it will be created automatically with 1st chat message.

Parameters

Parameter Required Description Usage example
type Yes Type of new dialog. Possible values:
  • 1 (PUBLIC_GROUP)
  • 2 (GROUP)
  • 3 (PRIVATE)
type=2
occupants_ids Yes if type=2(GROUP) or 3(PRIVATE) IDs of dialog occupants - users, who will be able to chat in this dialog. Don't need to pass current user ID - it will be added automatically occupants_ids=56,558,12334
name Yes (except when type=3 (PRIVATE) Name of a new dialog. Ignored when type=3(PRIVATE) name=Chat with Bob, Sam, Garry
photo No Photo of a new dialog. Ignored when type=3(PRIVATE) photo=67834

Request

curl -X POST \
-H "QB-Token: eddf864695d72d33b959eec2ae6c640d817dfada" \
-d "type=2&name=Chat with Bob, Sam, Garry&occupants_ids=55,678,22" \
https://api.quickblox.com/chat/Dialog
curl -X POST \
-H "Content-Type: application/json" \
-H "QB-Token: eddf864695d72d33b959eec2ae6c640d817dfada" \
-d '{"type": 2, "name": "Chat with Bob, Sam, Garry", "occupants_ids": "55,678,22"}' \
https://api.quickblox.com/chat/Dialog.json
QB.chat.dialog.create({type: 2, occupants_ids: '56,558,12334', name: 'Chat with Bob, Sam, Garry'}, onDialogCreated);

Response

<?xml version="1.0" encoding="UTF-8"?>
<chat_dialog>
  <_id>53aaa06f535c12cea9007496</_id>
  <last_message nil="true"/>
  <last_message_date_sent nil="true"/>
  <last_message_user_id nil="true"/>
  <name>Chat with Bob, Sam, Garry</name>
  <photo nil="true"/>
  <occupants_ids type="array">
    <occupants_id type="integer">55</occupants_id>
    <occupants_id type="integer">678</occupants_id>
    <occupants_id type="integer">22</occupants_id>
  </occupants_ids>
  <type type="integer">2</type>
  <xmpp_room_jid>92_53aaa06f535c12cea9007496@muc.chat.quickblox.com</xmpp_room_jid>
  <unread_messages_count type="integer">0</unread_messages_count>
</chat_dialog>
{
  "_id": "53aaa06f535c12cea9007496",
  "last_message": null,
  "last_message_date_sent": null,
  "last_message_user_id": null,
  "name": "Chat with Bob, Sam, Garry",
  "photo": null,
  "occupants_ids": [
    55,
    678,
    22
  ],
  "type": 2,
  "xmpp_room_jid": "92_53aaa06f535c12cea9007496@muc.chat.quickblox.com",
  "unread_messages_count": 0
}
var onDialogCreated = function(err, res) {
  // callback function
};

Custom parameters

Dialogs can store additional parameters. These parameters can be used to store an additional data. Also these parameters can be used in dialogs retrieval requests.

To start use additional parameters it needs to create an additional schema of your parameters. This is a CustomObjects class. Just create an empty class with all needed fields. These fields will be your dialog additional parameters.

Next, to set additional parameters to a dialog use next additional parameters in a creation request:

  1. data[class_name] - should contain CustomObjects class name created above
  2. data[field1]
  3. data[...]
  4. data[fieldN]


Set custom parameters

For example, we have class "CoolDialog" with string field "category". Next request will create a dialog with the custom parameter category and the value friends:

curl -X POST \
-H "QB-Token: eddf864695d72d33b959eec2ae6c640d817dfada" \
-d "type=2&name=Chat with Bob, Sam, Garry&occupants_ids=55,678,22&data[class_name]=CoolDialog&data[category]=friends" \
https://api.quickblox.com/chat/Dialog
curl -X POST \
-H "Content-Type: application/json" \
-H "QB-Token: eddf864695d72d33b959eec2ae6c640d817dfada" \
-d '{"type": 2, "name": "Chat with Bob, Sam, Garry", "occupants_ids": "55,678,22", "data" : { "class_name" : "CoolDialog", "category" : "friends" }' \
https://api.quickblox.com/chat/Dialog.json


Filter dialogs by custom parameters

Dialogs can be filtered through custom parameters. For example, request for dialogs with parameter category=friends:

curl -X GET -d "data[class_name]=CoolDialog&data[category]=friends" -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" https://api.quickblox.com/chat/Dialog
curl -X GET -d "data[class_name]=CoolDialog&data[category]=friends" -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" https://api.quickblox.com/chat/Dialog.json

Update dialog

Update a dialog. Works only if type=1(PUBLIC_GROUP) or 2(GROUP).

Users who are in occupants_ids can update a dialog with type=2(GROUP). If type=1(PUBLIC_GROUP) - only dialog’s owner can update it.

Fields to update

Field Available operators Description Usage example
occupants_ids pull_all,push_all Update dialog occupants.

Use push_all operator to add new occupants.
Use pull_all to remove occupants
push_all[occupants_ids][]=55,56

pull_all[occupants_ids][]=22,23
name Name of a new dialog name=Chat with Garry and John

Request

curl -X PUT \
-H "QB-Token: eddf864695d72d33b959eec2ae6c640d817dfada" \
-d "name=Chat with Garry and John, Garry&pull_all[occupants_ids][]=22" \
https://api.quickblox.com/chat/Dialog/53aac0cd535c12b50600962c
curl -X PUT \
-H "Content-Type: application/json" \
-H "QB-Token: eddf864695d72d33b959eec2ae6c640d817dfada" \
-d '{"name": "Chat with Garry and John", "pull_all": {"occupants_ids": [22]}}' \
https://api.quickblox.com/chat/Dialog/53aac0cd535c12b50600962c.json
var dialog_id = '53aac0cd535c12b50600962c';
QB.chat.dialog.update(dialog_id, {name: 'Chat with Garry and John', pull_all: {occupants_ids: [22]}}, onDialogUpdated);

Response

<?xml version="1.0" encoding="UTF-8"?>
<chat_dialog>
  <_id>53aac0cd535c12b50600962c</_id>
  <last_message nil="true"/>
  <last_message_date_sent nil="true"/>
  <last_message_user_id nil="true"/>
  <name>Chat with Bob, Sam, Garry</name>
  <photo nil="true"/>
  <occupants_ids type="array">
    <occupants_id type="integer">55</occupants_id>
    <occupants_id type="integer">678</occupants_id>
  </occupants_ids>
  <type type="integer">2</type>
  <xmpp_room_jid>92_53aac0cd535c12b50600962c@muc.chat.quickblox.com</xmpp_room_jid>
  <unread_messages_count type="integer">0</unread_messages_count>
</chat_dialog>
{
  "_id": "53aac0cd535c12b50600962c",
  "last_message": null,
  "last_message_date_sent": null,
  "last_message_user_id": null,
  "name": "Chat with Bob, Sam, Garry",
  "photo": null,
  "occupants_ids": [
    55,
    678,
  ],
  "type": 2,
  "xmpp_room_jid": "92_53aac0cd535c12b50600962c@muc.chat.quickblox.com",
  "unread_messages_count": 0
}
var onDialogUpdated = function(err, res) {
  // callback function
};

Delete dialog

Delete chat dialog.

Each user from dialog’s occupant_ids field can remove the dialog. This doesn’t mean that this dialog will be removed completely for all the users in this dialog. It will be removed only for current user.

Request

curl -X DELETE \
-H "QB-Token: eddf864695d72d33b959eec2ae6c640d817dfada" \
https://api.quickblox.com/chat/Dialog/53aabe15e4b077ddd43e7fd6.xml
curl -X DELETE \
-H "Content-Type: application/json" \
-H "QB-Token: eddf864695d72d33b959eec2ae6c640d817dfada" \
https://api.quickblox.com/chat/Dialog/53aabe15e4b077ddd43e7fd6.json

Response

Status 200 OK
Status 200 OK


Retrieve messages

Retrieve all chat messages within particular dialog. It's only possible to read chat messages in dialog if current user id is in occupants_ids field or if dialog's type=1(PUBLIC_GROUP). Server will return dialog's chat messages sorted ascending by date_sent field.

All retrieved chat messages will be marked as read after request.

Parameters

Operator Applied fields Description Usage example
{field_name} all + subfields for attachments: attachments.type, attachments.id, attachments.url, Search records with field which contains exactly specified value sender_id=2960
{field_name}[{search_operator}] all except chat_dialog_id, attachments Search record with field which contains value according to specified value and operator.

Possible filters: lt (Less Than operator), lte (Less Than or Equal to operator), gt (Greater Than operator), gte (Greater Than or Equal to operator), ne (Not Equal to operator), in (Contained IN array operator), nin (Not contained IN array), all (ALL contained IN array), or (OR operator), ctn (Contains substring operator)
sender_id[in]=134,2566
limit standalone operator Limit search results to N records. Useful for pagination. Default value - 100 limit=50
skip standalone operator Skip N records in search results. Useful for pagination. Default (if not specified): 0 skip=50
count standalone operator Count search results. Response will contain only count of records found count=1
sort_desc/sort_asc date_sent Search results will be sorted by specified field in ascending/descending order sort_desc=date_sent

Request

curl -X GET -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" \
https://api.quickblox.com/chat/Message?chat_dialog_id=53aadc78535c127f15009b6c
curl -X GET -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" \
https://api.quickblox.com/chat/Message.json?chat_dialog_id=53aadc78535c127f15009b6c
QB.chat.message.list({chat_dialog_id: '53aadc78535c127f15009b6c'}, onMessages);

Response

<?xml version="1.0" encoding="UTF-8"?>
<chat_messages type="array">
  <chat_message>
    <_id>53aadcc7e4b077ddd43e804d</_id>
    <attachments type="array"/>
    <chat_dialog_id>53aadc78535c127f15009b6c</chat_dialog_id>
    <date_sent type="integer">1403706567</date_sent>
    <message nil="true"/>
    <recipient_id nil="true"/>
    <sender_id type="integer">298</sender_id>
    <read type="integer">1</read>
  </chat_message>
  <chat_message>
    <_id>53aadcc8e4b077ddd43e804f</_id>
    <attachments type="array"/>
    <chat_dialog_id>53aadc78535c127f15009b6c</chat_dialog_id>
    <date_sent type="integer">1403706568</date_sent>
    <message nil="true"/>
    <recipient_id nil="true"/>
    <sender_id type="integer">298</sender_id>
    <read type="integer">1</read>
  </chat_message>
  <chat_message>
    <_id>53aadcd0e4b077ddd43e8051</_id>
    <attachments type="array"/>
    <chat_dialog_id>53aadc78535c127f15009b6c</chat_dialog_id>
    <date_sent type="integer">1403706577</date_sent>
    <message nil="true"/>
    <recipient_id nil="true"/>
    <sender_id type="integer">298</sender_id>
    <read type="integer">1</read>
  </chat_message>
</chat_messages>
{
  "skip": 0,
  "limit": 100,
  "items": [
    {
      "_id": "53aadcc7e4b077ddd43e804d",
      "attachments": [
 
      ],
      "chat_dialog_id": "53aadc78535c127f15009b6c",
      "date_sent": 1403706567,
      "message": null,
      "recipient_id": null,
      "sender_id": 298,
      "read": 1
    },
    {
      "_id": "53aadcc8e4b077ddd43e804f",
      "attachments": [
 
      ],
      "chat_dialog_id": "53aadc78535c127f15009b6c",
      "date_sent": 1403706568,
      "message": null,
      "recipient_id": null,
      "sender_id": 298,
      "read": 1
    },
    {
      "_id": "53aadcd0e4b077ddd43e8051",
      "attachments": [
 
      ],
      "chat_dialog_id": "53aadc78535c127f15009b6c",
      "date_sent": 1403706577,
      "message": null,
      "recipient_id": null,
      "sender_id": 298,
      "read": 1
    }
  ]
}
var onMessages = function(err, res) {
  // callback function
};

Create message

Create a chat message. It’s possible to inject a new chat message to the chat history. In this case this new message won't be delivered to the recipient(s) by XMPP real time transport, it will be just added to the history. If you wont to initiates a real 'send to chat' - pass send_to_chat=1 parameter.


Fields to set

Parameter Required Description Usage example
chat_dialog_id yes if the recipient_id key is not specified ID of a dialog to which this messages will be added chat_dialog_id=53db8798535c125e8e000902
message no text of the message (CGI-escaped) message=hello!
recipient_id yes if the chat_dialog_id key is not specified ID of a recipient. Useful only when dialog's type=3(PRIVATE) recipient_id=4124234
attachments[n][type/id/url] no Array of attachments objects. Each attachment object contains 3 keys:type(audio/video/image/...), id(link to file ID in QuickBlox), url(link to file in Internet) attachments[0][id]=47863&attachments[0][type]=image&attachments[1][url]=www.mysite.com/image.png&attachments[1][type]=image
Custom parameters no Key-value parameters. Chat message can contain any other custom parameters age=25
send_to_chat no Sends a message to chat send_to_chat=1
markable no Mark the messages to support read/delivered statuses markable=1

Request

curl -X POST \
-H "QB-Token: eddf864695d72d33b959eec2ae6c640d817dfada" \
-d "chat_dialog_id=53a99a7be4b094c7c6d31b41&message=hello!&recipient_id=343&attachments[0][id]=47863&attachments[0][type]=image&age=25" \
https://api.quickblox.com/chat/Message.xml
curl -X POST \
-H "Content-Type: application/json" \
-H "QB-Token: eddf864695d72d33b959eec2ae6c640d817dfada" \
-d '{"chat_dialog_id": "53a99a7be4b094c7c6d31b41", "message": "hello!", "recipient_id": 343,"attachments": {"0": {"type": "image", "id": "47863"}, "1": {"type": "image", "id": "47863"} }, "age": "25"}' \
https://api.quickblox.com/chat/Message.json

Response

<chat_message>
  <_id>53e89d53535c127839025970</_id>
  <age>25</age>
  <attachments type="array">
    <attachment>
      <id>47863</id>
      <type>image</type>
    </attachment>
  </attachments>
  <chat_dialog_id>53a99a7be4b094c7c6d31b41</chat_dialog_id>
  <date_sent type="integer">1407753555</date_sent>
  <message>hello!</message>
  <recipient_id type="integer">343</recipient_id>
  <sender_id type="integer">1279282</sender_id>
</chat_message>
{
    "_id":"53e8a3a4535c1242aa0270b9",
    "age":"25",
    "attachments":[{"id":"47863","type":"image"}],
    "chat_dialog_id":"53db8798535c125e8e000902",
    "date_sent":1407755172,
    "message":"hello!",
    "recipient_id":343,
    "sender_id":1279282
}

Update message

Update chat message. It’s possible only to mark messages as read. Update other fields isn’t possible at this stage.


Fields to update

Field Description Usage example
read Mark message as read read=1

Request

curl -X PUT \
-H "QB-Token: eddf864695d72d33b959eec2ae6c640d817dfada" \
-d "read=1&chat_dialog_id=53a99a7be4b094c7c6d31b41" \
https://api.quickblox.com/chat/Message/53aabe15e4b077ddd43e7fd3.xml
curl -X PUT \
-H "Content-Type: application/json" \
-H "QB-Token: eddf864695d72d33b959eec2ae6c640d817dfada" \
-d '{"read": "1", "chat_dialog_id": "53a99a7be4b094c7c6d31b41"}' \
https://api.quickblox.com/chat/Message/53aabe15e4b077ddd43e7fd3.json

Response

Status 200 OK
Status 200 OK

Delete message

Removes a chat message for the current user

Any user in the dialog’s occupant_ids is able to remove a message from the dialog. The message will only be removed for the current user - the message will still be viewable and in the chat history for all other users in the dialog.

You may be wondering why this request only deletes the message for the current user. It is to allow deletion functionality within your app and ensuring the message does not reappear in their chat history, but without affecting the history of other users.

Request

curl -X DELETE \
-H "QB-Token: eddf864695d72d33b959eec2ae6c640d817dfada" \
https://api.quickblox.com/chat/Message/53aabe15e4b077ddd43e7fd3,53aabe15e4b077ddd43e7fd6.xml
curl -X DELETE \
-H "Content-Type: application/json" \
-H "QB-Token: eddf864695d72d33b959eec2ae6c640d817dfada" \
https://api.quickblox.com/chat/Message/53aabe15e4b077ddd43e7fd3,53aabe15e4b077ddd43e7fd6.json
var message_id = '53aabe15e4b077ddd43e7fd3';
QB.chat.message.delete(message_id, onMessageDeleted);

Response

Status 200 OK
Status 200 OK
var onMessageDeleted = function(res) {
  // callback function
};


Stream management

Stream management (XEP-0198) defines an XMPP protocol extension for active management of an XML stream between two XMPP entities, including features for stanza acknowledgements and stream resumption.

The basic concept behind stream management is that the initiating entity (either a client or a server) and the receiving entity (a server) can exchange "commands" for active management of the stream. The following stream management features are of particular interest because they are expected to improve network reliability and the end-user experience:

  • Stanza Acknowledgements -- the ability to know if a stanza or series of stanzas has been received by one's peer.
  • Stream Resumption -- the ability to quickly resume a stream that has been terminated.


The main interesting part here is Stanza Acknowledgements because it allows to achieve 100% reliability. To better understand how it works we prepared next picture:

XEP-0198 QuickBlox Chat.png

QuickBlox Chat server does support stream management, both Stanza Acknowledgements and Stream Resumption. More info how it works you can check in xep-0198 extention page.

Use SDKs sections to check platform support.


XML formats

Send/Receive a message

Send message format:

<message id="54789d5e6df5e6f921b7acda" type="groupchat" to="92_54789d40535c12b1a5001172@muc.chat.quickblox.com">
    <body>Nice to met you!</body>
    <extraParams xmlns="jabber:client">
        <save_to_history>1</save_to_history>
    </extraParams>
</message>

Receive message format:

<message xmlns="jabber:client" from="92_54789d40535c12b1a5001172@muc.chat.quickblox.com/1501966" to="1501966-92@chat.quickblox.com/0C1E1229-6B3C-47F3-BFDC-D1CFD351D274" type="groupchat" id="54789d5e6df5e6f921b7acda">
    <body>Nice to met you!</body>
    <extraParams xmlns="jabber:client">
        <save_to_history>1</save_to_history>
        <message_id>54789d5e6df5e6f921b7acda</message_id>
        <dialog_id>54789d40535c12b1a5001172</dialog_id>
    </extraParams>
</message>

As you can see, server automatically adds the message_id and dialog_id of a message from history, so a recipient knows this data.

File attachments

Each attachment should be included into extraParams part of a message.

Each attachment contains next attributes:

  • type - type of the attachment. Could be any. Recommended values: video, audio, photo
  • id (optional)- link to a file, for example ID of a file in Content or Custom Objects modules
  • url (optional) - url to a file in the Internet
<message id="546dbf438c54ad2aded63b25" type="groupchat" to="2_546d14c19c29532398000496@muc.chat.quickblox.com">
    <body>Nice to met you!</body>
    <extraParams xmlns="jabber:client">
        <save_to_history>1</save_to_history>
        <attachment type="video" id="47863"></attachment>
        <attachment type="photo" url="..."></attachment>
    </extraParams>
</message>


Dashboard

Chat 2.0 provides a really powerful way to manage Chat history in Dashboard. Go to admin panel, Chat module. There are 2 new tabs: Dialogs and Alerts.

Dialogs

Dialogs tab contains all dialogs in your application, with next columns:

  • id - ID of a dialog
  • type - Type of a dialog: PRIVATE, GROUP or PUBLIC GROUP
  • name - Name of a dialog
  • occupants ids - Users IDs who chat in this dialog
  • last message - Latest sent message in this dialog
  • last message user id - ID of User who sent latest message in this dialog
  • room_jid - JID of XMPP room for group chat to connect. Empty if type is PRIVATE
  • last message date sent - Timestamp of latest sent message in this dialog
  • history - link to chat history for this dialog


Chat2.0 dialogs.png

You can create new dialog here or update existing one. To edit dialog just click on dialog's ID - popup with dialog's info will appear. To create a new dialog click on New Dialog button, New Dialog popup will appear:

Chat2.0 dialogs new.png

Enter name, choose type and set occupants for this group. Then click Create button - newly created dialog will be added to the dialogs list.

History

By clicking history link in each dialog you can view chat messages in this dialog:

Chat2.0 messages.png


There are next columns:

  • message - chat message body
  • Sender Id - User who sent message
  • Recipient Id - User who received message
  • Attachments - Information about message attachments
  • Custom parameters - Message custom parameters
  • Date sent - Date sent of message


You can use Search box to filter messages.

Alerts

Alerts tab allows you to setup automatic push notifications for offline user. It means if your opponent is offline while you writing a message - he can automatically receive push notification.

Offline pushes only work if you use save_to_history=1 key when send messages.

Chat2.0 alerts.png


There are the following settings:

  • Alert text - text of your push notification
  • Environment - set Push Notifications environment here
  • Templates - set push notification template here. Use template variables to engage your push message
  • Badge counter - set badge counter to include a counter info into your push message. Useful to include unread counter - number of unread messages user has
  • Sound - set push notification sound (for iOS only)
  • Category - describes "actions" that should be presented in app notification in various views (for iOS only)
  • Content Available - provide this key with a value of 1 to indicate that new content is available (for iOS only)

Pushes work automatically, one thing that you need is to subscribe users to pushes using SDKs.

Payload

Here are examples of push notification payload. There are 2 additional parameters which are added automatically to each push:

  • user_id - the message sender's ID
  • dialog_id - the ID of a dialog in which message was sent

Other parameters are standart or configured via Dashboard:


iOS

{
    aps =     {
        alert = "Garry Bones: Hey Sam, how things are going on?",
        badge = 10,
        sound = 1,
    },
    "dialog_id" = 55351e7fefa357af64000006,
    "user_id" = 1529813
}

Android

{
    user_id=1529813, 
    from=761750217637, 
    badge=10, 
    message=Garry Bones: Hey Sam, how things are going on?, 
    dialog_id=55351e7fefa357af64000006, 
    android.support.content.wakelockid=4, 
    collapse_key=event2191
}


Use cases

All typical use cases you can find in iOS/Android chat samples:

Datetime issue

All the users in conversation have to have same date_sent value for chat messages. In additional, the same value should be stored to chat history.

To resolve this issue we recommend a flow when each user sets by himself a date_sent value when sending a message:

QBChatMessage *message = [QBChatMessage message];
...
NSMutableDictionary *params = [NSMutableDictionary dictionary];
params[@"date_sent"] = @((int)[[NSDate date] timeIntervalSince1970];
...
[message setCustomParameters:params];
QBChatMessage chatMessage = new QBChatMessage();
...
long time = System.currentTimeMillis()/1000;
chatMessage.setProperty("date_sent", time + "");
...

Chat server validates this value (check a difference between client's and server's timestamps - it should not be more than 5 seconds). If a difference is less then 5 seconds - server will use client's value, otherwise - ignore client's value and use own.