Real-time(XMPP) API
Real-time(XMPP) API is a quick and reliable solution which combines benefits of scalable cloud hosted XMPP chat server, seamless authorization and incoming IM / chat alerts. It’s robust, quick and auto-scalable AWS powered cloud servers infrastructure. It’s the best and most comprehensive solution so far to have your users communicate cross-platform.
The following ConnectyCube modules are built on top of real-time(XMPP) API:
- Text Chat (messaging) module
- Video Chat (calling) module
ConnectyCube real-time API is based on origin XMPP standards, but with slightly changes.
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:
- RFC-6120 - http://xmpp.org/rfcs/rfc6120.html - Core: SSL/TLS stream encryption, SASL authentication, Resource binding etc
- RFC-6121 - http://xmpp.org/rfcs/rfc6121.html - Instant Messaging and Presence
- XEP-0016 - http://xmpp.org/extensions/xep-0016.html - Privacy Lists
- XEP-0203 - http://xmpp.org/extensions/xep-0203.html - Offline Message Storage
- XEP-0280 - http://xmpp.org/extensions/xep-0280.html - Message Carbons
- XEP-0198 - http://xmpp.org/extensions/xep-0198.html - Stream Management
- XEP-0085 - http://xmpp.org/extensions/xep-0085.html - Chat State Notifications
- XEP-0079 - http://xmpp.org/extensions/xep-0079.html - Advanced Message Processing
- XEP-0045 - http://xmpp.org/extensions/xep-0045.html - Multi User Chat
- XEP-0333 - http://xmpp.org/extensions/xep-0333.html - Chat Markers
- XEP-0308 - http://xmpp.org/extensions/xep-0308.html - Last Message Correction
- XEP-0012 - http://xmpp.org/extensions/xep-0012.html - Last Activity
- XEP-0352 - http://xmpp.org/extensions/xep-0352.html - Client State Indication
Endpoint
All XMPP API access is over TLS, and accessed via the chat.connectycube.com:5223 domain.
For Web applications it’s also possible to use BOSH/WebSockets endpoints (https://chat.connectycube.com:5281 and wss://chat.connectycube.com:5291).
Authentication in Real-time API
In order to connect to Real-Time API, the following actions should be performed:
- create a user in ConnectyCube dashboard ConnectyCube dashboard or via Users REST API.
- authenticate user via Real-Time API.
- login - when user is authenticated via Real-Time API, he receives a JID (Jabber ID) in the following format:
Handshake / Login Flow
Use this documentation to understand what the typical stanzas used in the ConnectyCube XMPP handshake flow are.
SASL Authentication Handshake Begin
Client:
Server:
Server:
Client:
Server:
SASL Authentication Handshake End
Client:
Server:
Server:
Bind Resource Begin
Client:
Server:
Bind Resource End
Initial Presence Begin
Client:
Server:
Initial Presence End
Server-side chat history
Chat introduces a very simple server-side chat history functionality that allows to moderate, restore messages on a new device via REST, download the chat massages. Connectycube is not able to read the messages - only the account owner has access to them.
Messages with a parameter save_to_history
set to 1 will be saved to chat history.
Chat message format
A message’s type attribute can be chat or groupchat:
- chat is used for 1-1 messages.
- groupchat is used for group chats.
1-1 message:
group chat message:
By default, messages are not stored on the back-end. To store messages on server, save_to_history parameter should be added to XMPP messages.
There’s also a date_sent field in the extra parameters. It is optional - if it wasn’t supplied, server will automatically add it when it receives the message. In case if the failed message should be re-sent, ‘date_sent’ field can be used to specify the correct time. Parameter uses a unix timestamp format.
silent message:
By default, back-end create push notification (chat alert) for offline recipients.
You can prevent creating push notification by silent parameter set to 1
.
receive message format:
Referring to the response above, server automatically adds a dialog_id extra parameter, so a recipient knows which chat dialog this message is related to.
Chat message statuses
Adding statuses to the chat allows to monitor when the opponent is typing, when message is delivered on the device and read.
1. ‘Is typing’ status
`is typing’ status can be added in 1-1 or group chats.
composing:
paused:
2. ‘Delivered’ status
’delivered’ status is available for 1-1 chat only, so you send ‘delivered’ status directly to users.
3. ‘Read’ status
’read’ status is available for 1-1 chat only, so you send ‘read’ status directly to users.
Delete message
Edit message
Self-destroy message
File attachments
To send attachments as messages in chat, attachment should be included into extraParams part of a message.
Each attachment contains the following attributes:
- type - type of the attachment. Recommended types: image, video, audio, location.
- id (optional)- a link to a file, for example ID of a file in Content or Custom Objects modules
- url (optional) - an url to file in the Internet
- data (optional) - an attachment’s data. For example, used for location attachments to pass latitude & longitude.
- size (optional) - file size in bytes
- width (optional) - if attachment is an image - an image’s width
- height (optional) - if attachment is an image - an image’s height
- duration (optional) - if attachment is an audio/video - duration of an audio/video file
- content-type (optional) - an attachment’s content type
- name (optional) - an attachment’s name
format:
System messages
There is a special channel for any system notifications. The end user can use it to split regular chat messages and other system events.
All such messages should contain extraParams.moduleIdentifier=SystemNotifications and use type=headline.
You can send system messages directly to user only (group chat is not supported).
format:
Stream management
Stream management (XEP-0198) defines an XMPP protocol extension for active management of a stream between two users, including features for stanza acknowledgements and stream resumption. This protocol aims to resolve the issue with lost messages in a case of very poor Internet connection.
The basic concept behind stream management is that the initiating entity (a client) 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.
Active/Inactive client state
It is common for IM clients to be logged in and ‘online’ even while the user is not interacting with the application. This protocol allows the client to indicate to the server when the user is not actively using the client, allowing the server know that a user wants to receive push notifications while still is connected to chat.
Client:
Server: