Skip to content

Chat API

ConnectyCube Chat (messaging) API consists of 2 parts: REST API and Real-Time (XMPP) API. This document describes the REST API part. To get an info about Real-Time (XMPP) API - please refer to Real-Time (XMPP) API documentation page.

Features

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

  • 1:1 chat (private user to user chat)
  • Group chat (unlimited chat rooms)
  • Incoming chat alerts (push notifications) for offline users
  • File attachments - cloud hosted, so both users don’t have to be online to receive messages. Allow users to send photos, videos and other files.
  • Voice chat / call – enable 1:1 voice calls in the application
  • Video chat / call – enable video chats in the application
  • 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 the networks with different configurations

Chat dialog model

Chat Dialog model describes a dialog between users. Dialog can have custom parameters (if available).

Chat model structure:

Field nameDescription
_idID of dialog. Generated automatically by server after dialog is created
user_idID of dialog’s owner
created_atUnix timestamp. Date & time when record was created. System creates this parameter automatically
descriptionDialog description
updated_atUnix timestamp. Date & time when record was updated. System creates this parameter automatically
typeType of the dialog: type 1 - broadcast, type 2 - group chat, type 3 - private chat, type 4 - public chat
nameName of a group chat
photoImage of the chat. Can contain a link to a file in Connectycube storage, Custom Objects module or just a web link
xmpp_room_jidJaber identifier of XMPP room for group chat to connect. Not applicable for private chat (type 3). Generated automatically by server after dialog is created
occupants_idsList of users in the chat. Applicable for private and group chats only
occupants_countNumber of users in the public chat
admins_idsList of users who have admin rights
last_messageLast message sent in the chat dialog
last_message_idID of the last message in the chat dialog
last_message_user_idID of user who sent the last message in the chat dialog
last_message_date_sentDate & time when the last message in the chat dialog was sent
last_message_statusLast sent message state. Will be ‘null’ if last message is sent by other user (not you). Will be one of the ‘sent’, ‘delivered’, ‘read’ if last message is sent by you
unread_messages_countNumber of unread messages in the dialog for current user
pinned_messages_idsIDs of messages pinned in the chat dialog
extensionsObject of allows fields
permissionsObject with permissions props (allow_preview)

Message model

Chat Message model describes a chat message in a chat dialog.

Message model structure:

Field nameDescription
_idMessage ID. Generated automatically by server after message is created
created_atUnix timestamp. Created by system automatically
updated_atUnix timestamp. Created by system automatically and is updated when the message is updated or read
chat_dialog_idID of the dialog the current chat message is related to. Generated automatically by server after message is created
messageMessage body
date_sentDate when massage has been sent
sender_idID of a user who sent a message
recipient_idID of user who received a message
read_idsList of IDs of users who read the messages
delivered_idsList of users IDs a message was delivered to
views_countNumber of views of the messages. Available for broadcast (type 1) and public chats (type 1)
attachmentsList of attachments. Each attachment object contains 3 keys: type (audio / video / image), id (link to file in Connectycube storage), url (link to file in the Internet)
Custom parametersChat message can contain any other user custom parameters (additional metadata)
reactionsReactions object with total and own reactions

Roles and privileges

There are different roles of users in a chat dialog:

Regular user - user who can send and receive messages.

Admin - advanced user with moderation privileges.

Super admin - chat owner (creator) with all possible privileges.

RolesPrivate chatGroup chatPublic chatBroadcast
Regular user
  • send/receive messages
  • delete own message (one side/both sides)
  • delete chat dialog for themselves
  • send/receive messages
  • delete own message (one side/both sides)
  • delete chat dialog for themselves
  • add more users
  • change name, photo, description
  • send/receive messages
  • delete own message (one side/both sides)
  • delete chat dialog for themselves (or unsubscribe)
  • receive messages
  • delete chat dialog for themselves
  • Admin-
  • delete any messages for everyone
  • pin messages
  • add/remove users
  • regular user privileges
  • change name, description, photo
  • delete any messages for everyone
  • pin messages
  • block/unblock users
  • regular user privileges
  • change name, description, photo
  • delete any messages for everyone
  • pin messages
  • block/unblock users
  • Super admin-
  • add/remove admins
  • delete dialog for everyone
  • regular admin privileges
  • add/remove admins
  • delete dialog for everyone
  • regular admin privileges
  • add/remove admins
  • delete dialog for everyone
  • Retrieve chat dialogs

    Retrieve all the dialogs associated with the current user. Server returns all dialogs where the current user’s ID is in the list of ‘occupants_ids’ field (type 2, type 3) OR in the list of ‘occupants_count’ (type 4). Server identifies user ID with a session token. If there is a broadcast chat in the app, this chat will be retrieved for all users.

    Retrieving of chat dialogs is possible by specifying one or more custom parameter(s).

    Endpoint
    Terminal window
    GET https://api.connectycube.com/chat/Dialog
    Parameters
    OperatorApplied fieldsDescriptionValue example
    {field_name}_id, type, name, last_message_date_sent, created_at, updated_at, extensions[friend_id]Retrieve dialogs with the exact data specified in the requesttype=2
    {field_name}[{search_operator}]_id, type, name, last_message_date_sent, created_at, updated_at, extensions[friend_id]Retrieve dialogs with the exact data specified in the request with applying additional filters. Available 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), ctn (Contains substring operator)type[in]=2,3
    limitstandalone operatorSetting of limit for a number of search results to display. Default - 100limit=70
    skipstandalone operatorSkip the defined number of records in the search results. By default all records are shownskip=20
    countstandalone operatorCount search results. Response will contain only count of records found.count=1
    sort_desc/sort_asclast_message_date_sentSorting of query result set in ascending / descending ordersort_desc=date_sent
    Request Example
    Terminal window
    curl -X GET \
    -H "CB-Token: <TOKEN>" \
    https://api.connectycube.com/chat/Dialog
    Response
    {
    "total_entries": 4,
    "skip": 0,
    "limit": 100,
    "items": [
    {
    "_id": "5c094c0ce588ce6856f87422",
    "admins_ids": [29085],
    "created_at": "2018-12-06T16:19:24Z",
    "description": "Cute chat",
    "last_message": "nope?",
    "last_message_date_sent": 1544452627,
    "last_message_id": "5c0e7a13e588ce6b6f3ebf80",
    "last_message_user_id": 29086,
    "last_message_status": "sent",
    "name": "hello kitty",
    "occupants_ids": [
    29085,
    29086,
    29087
    ],
    "photo": null,
    "pinned_messages_ids": ["5c0e7a13e588ce6b6f3ebf80"],
    "type": 2,
    "updated_at": "2018-12-10T14:37:07Z",
    "user_id": 29085,
    "unread_messages_count": 1,
    "xmpp_room_jid": "105_5c094c0ce588ce6856f87422@muc.chatstage.connectycube.com",
    "extensions": null,
    "permissions": null
    },
    ...
    ]
    }

    Create a dialog

    There are four types of dialogs available to be created:

    • type=1 - broadcast - type of chat where a message is sent to all users within application at once. All the users from the application are able to join this group.

      Max users count - all chat users

      Roles: 1 Super Admin (chat creator) and up to 5 admins

    • type=2 - group chat - type of chat where one user creates chat with other users. More users can be added later. All messages in chat have read / delivered status

      Max users count - according to Plans

      Roles: 1 Super Admin (chat creator) and up to 5 admins

    • type=3 - private chat between 2 users. If user sends a chat message to some user and private dialog isn’t created - it will be created automatically with the first chat message. All messages in chat have read / delivered status

      Max users count - 2

      Roles: two regular users

    • type=4 - public chat - type of chat where any user can subscribe via public link.

      Max users count - according to Plans

      Roles: 1 Super Admin (chat creator) and up to 5 admins

    Endpoint
    POST https://api.connectycube.com/chat/Dialog
    Parameters
    ParameterRequiredDescription
    typeYesType of new dialog. Possible values: 1 - broadcast, 2 - group chat, 3 - private 1-to-1 chat, 4 - public chat
    occupants_idsYes, for group (type 2) and private (type 3) chatsList of users who are participants of the chat. The current user id will be added automatically. Example: occupants_ids=45,78
    admins_idsNoChat admins. Example: admins_ids=65,89
    nameYes, for broadcast (type 1), public (type 4) and group (type 2) chatsName of a dialog. Ignored for private chats (type 3)
    photoNoDialog image. Ignored for private chats (type 3)
    descriptionNoDialog description
    extensionsNoObject of allows fields
    permissionsNoObject with permissions props
    Dialog permissions
    • allow_preview - allow retrieve messages from dialog for user who is not a member of dialog
    Dialog extensions

    Dialog can have up to 3 custom sub-fields to store additional information. These parameters can be used as a value for retrieving dialogs.

    To start using extensions, allowed fields should be added first. Go to Admin > Chat > Custom Fields.

    Extensions object should contain allowed fields (others will be ignored) and values will be casted to string.

    If update list of custom fields in admin panel and some fields will be removed, that fields will be removed in all dialogs.

    Dialog extensions fields example

    Dialog Extensions fields example

    Create dialogs with extensions request example
    Terminal window
    curl -X POST \
    -H "Content-Type: application/json" \
    -H "CB-Token: <TOKEN>" \
    -d '{"type":2, "name":"Night party", "occupants_ids": [29085,29087], "extensions": { "friend_id": 1055, "status": "Fine XD", "unknown_field": "will be ignored" }, "permissions": { "allow_preview": true }}' \
    https://api.connectycube.com/chat/Dialog
    Response
    {
    "_id": "5c091060e588ce59fdf873dd",
    "admins_ids": [],
    "created_at": "2018-12-06T12:04:48Z",
    "description": null,
    "last_message": null,
    "last_message_date_sent": null,
    "last_message_id": null,
    "last_message_user_id": null,
    "last_message_status": null,
    "name": "Night party",
    "occupants_ids": [29085, 29087],
    "photo": null,
    "pinned_messages_ids": [],
    "type": 2,
    "updated_at": "2018-12-06T12:04:48Z",
    "user_id": 29085,
    "unread_messages_count": 0,
    "xmpp_room_jid": "105_5c091060e588ce59fdf873dd@muc.chatstage.connectycube.com",
    "extensions": {
    "friend_id": "1055",
    "status": "Fine XD",
    },
    "permissions": {
    "allow_preview": true
    }
    }
    Update dialogs with extensions request example
    Terminal window
    curl -X PUT \
    -H "Content-Type: application/json" \
    -H "CB-Token: <TOKEN>" \
    -d '{ "extensions": { "friend_id": 1078, "unknown_field": "will be ignored" }}' \
    https://api.connectycube.com/chat/Dialog/5c091060e588ce59fdf873dd
    Response
    {
    "_id": "5c091060e588ce59fdf873dd",
    "admins_ids": [],
    "created_at": "2018-12-06T12:04:48Z",
    "description": null,
    "last_message": null,
    "last_message_date_sent": null,
    "last_message_id": null,
    "last_message_user_id": null,
    "last_message_status": null,
    "name": "Night party",
    "occupants_ids": [29085, 29087],
    "photo": null,
    "pinned_messages_ids": [],
    "type": 2,
    "updated_at": "2018-12-06T12:04:48Z",
    "user_id": 29085,
    "unread_messages_count": 0,
    "xmpp_room_jid": "105_5c091060e588ce59fdf873dd@muc.chatstage.connectycube.com",
    "extensions": {
    "friend_id": "1078",
    },
    "permissions": {
    "allow_preview": true
    }
    }

    To reset extensions params in dialogs just set extensions to null

    Search dialogs by extensions request example
    Terminal window
    curl -X GET \
    -H "Content-Type: application/json" \
    -H "CB-Token: <TOKEN>" \
    -d 'extensions[friend_id][in][]=1078&extensions[friend_id][in][]=1080' \
    https://api.connectycube.com/chat/Dialog
    Response
    {
    "total_entries": 1,
    "skip": 0,
    "limit": 100,
    "items": [
    {
    "_id": "5c091060e588ce59fdf873dd",
    "admins_ids": [],
    "created_at": "2018-12-06T12:04:48Z",
    "description": null,
    "last_message": null,
    "last_message_date_sent": null,
    "last_message_id": null,
    "last_message_user_id": null,
    "last_message_status": null,
    "name": "Night party",
    "occupants_ids": [29085, 29087],
    "photo": null,
    "pinned_messages_ids": [],
    "type": 2,
    "updated_at": "2018-12-06T12:04:48Z",
    "user_id": 29085,
    "unread_messages_count": 0,
    "xmpp_room_jid": "105_5c091060e588ce59fdf873dd@muc.chatstage.connectycube.com",
    "extensions": {
    "friend_id": "1078",
    }
    }
    ]
    }
    Custom parameters (Deprecated)

    Dialogs can have additional (or custom) parameters to store additional information. These parameters can be used as a value for retrieving dialogs.

    To start using custom parameters, an additional schema of these parameters should be created first. This is a CustomObjects empty class with all needed fields. These fields will be additional parameters for a dialog.

    To set additional parameters to dialog, the following parameters should be used in the request of dialog creation:

    • data[class_name] - should contain CustomObjects class name created for additional parameters
    • data[field1]
    • data[…]
    • data[fieldN]
    CustomObject Class schema example

    Custom Dialog params CustomObjects Class example

    Request example
    Terminal window
    curl -X POST \
    -H "Content-Type: application/json" \
    -H "CB-Token: <TOKEN>" \
    -d '{"type":2,"name":"Friday party","occupants_ids":"29085,29086,29087", "data": { "class_name": "CUSTOM_DIALOG_PARAMS", "dialog_number": 101, "optional_name": "My first dialog with friends" }}' \
    https://api.connectycube.com/chat/Dialog
    Response
    {
    "_id": "5c091060e588ce59fdf873dc",
    "admins_ids": [],
    "created_at": "2018-12-06T12:04:48Z",
    "description": null,
    "last_message": null,
    "last_message_date_sent": null,
    "last_message_id": null,
    "last_message_user_id": null,
    "last_message_status": null,
    "name": "Friday party",
    "occupants_ids": [29085, 29086, 29087],
    "photo": null,
    "pinned_messages_ids": [],
    "type": 2,
    "updated_at": "2018-12-06T12:04:48Z",
    "user_id": 29085,
    "unread_messages_count": 0,
    "xmpp_room_jid": "105_5c091060e588ce59fdf873dc@muc.chatstage.connectycube.com",
    "data": {
    "class_name": "CUSTOM_DIALOG_PARAMS",
    "dialog_number": 101,
    "optional_name": "My first dialog with friends"
    }
    }

    Update a dialog

    Based on the roles and privileges, users with different roles can update different data.

    Endpoint
    PUT https://api.connectycube.com/chat/Dialog/{dialog_id}
    Parameters
    ParameterDescriptionValue example
    occupants_idsAdd / delete occupants in the dialog
  • {“push_all”: {“occupants_ids”: [“id_1”,“id_2”]}}
  • “pull_all”: {“occupants_ids”: [“id_1”,“id_2”]}
  • pinned_messages_idsMake messages pinned / unpinned in the chat history
  • {“push_all”: {“pinned_messages_ids”: [“pinned_message_id_1”, “pinned_message_id_2”]}}
  • {“pull_all”: {“pinned_messages_ids”: [“pinned_message_id_1”, “pinned_message_id_2”]}}
  • admins_idsAdd / delete admins in the dialog
  • {“push_all”: {“admins_ids”: [admin_id_1]}}
  • {“pull_all”: {“admins_ids”: [admin_id_1]}}
  • nameName of the dialog{“name”: “dialog_name”}
    photoPhoto of the dialog{“photo”: “image.jpg”}
    descriptionDescription of the dialog{“description”: “Chat for Java developers”}
    extensionsObject with allowed fields{“extensions”: {“status”: “CatSitter”}}
    permissionsPermissions object{“permissions”: {“allow_preview”: false}}
    Custom parameters

    To update additional parameters in a dialog use next parameters in a request:

    Request example
    Terminal window
    curl -X PUT \
    -H "Content-Type: application/json" \
    -H "CB-Token: <TOKEN>" \
    -d '{"name":"Crossfit2","push_all":{"occupants_ids":[29088],"pinned_messages_ids":["5c123fdce588ce064043f53a"]},"photo":"gym2.jpeg", "permissions": { "allow_preview": false }}' \
    https://api.connectycube.com/chat/Dialog/5c123f75e588ce063e43f541
    Response
    {
    "_id": "5c123f75e588ce063e43f541",
    "admins_ids": [],
    "created_at": "2018-12-13T11:16:05Z",
    "description": "strong man",
    "last_message": "cool",
    "last_message_date_sent": 1544699868,
    "last_message_id": "5c123fdce588ce064043f53a",
    "last_message_user_id": 29085,
    "last_message_status": "read",
    "name": "Crossfit2",
    "occupants_ids": [29085, 29086, 29087, 29088],
    "photo": "gym2.jpeg",
    "pinned_messages_ids": ["5c123fdce588ce064043f53a"],
    "type": 2,
    "updated_at": "2018-12-13T11:21:21Z",
    "user_id": 29085,
    "unread_messages_count": 0,
    "xmpp_room_jid": "105_5c123f75e588ce063e43f541@muc.chatstage.connectycube.com",
    "extensions": null,
    "permissions": {
    "allow_preview": false
    }
    }
    Request example with custom parameters
    Terminal window
    curl -X PUT \
    -H "Content-Type: application/json" \
    -H "CB-Token: <TOKEN>" \
    -d '{"name": "Top news", "data": { "class_name": "class_name": "CUSTOM_DIALOG_PARAMS", "dialog_number": 78 }}' \
    https://api.connectycube.com/chat/Dialog/5c091060e588ce59fdf873dcv
    Response
    {
    "_id": "5c091060e588ce59fdf873dc",
    "admins_ids": [],
    "created_at": "2018-12-06T12:04:48Z",
    "description": null,
    "last_message": null,
    "last_message_date_sent": null,
    "last_message_id": null,
    "last_message_user_id": null,
    "last_message_status": null,
    "name": "Top news",
    "occupants_ids": [29085, 29086, 29087],
    "photo": null,
    "pinned_messages_ids": [],
    "type": 2,
    "updated_at": "2018-12-06T12:04:48Z",
    "user_id": 29085,
    "unread_messages_count": 0,
    "xmpp_room_jid": "105_5c091060e588ce59fdf873dc@muc.chatstage.connectycube.com",
    "data": {
    "class_name": "CUSTOM_DIALOG_PARAMS",
    "dialog_number": 78,
    "optional_name": "My first dialog with friends"
    }
    }

    Delete dialog

    Each user from ‘occupant_ids’ can remove the dialog. Dialog will be removed for the current user only and will continue to be available for other users in the group.

    To remove a dialog completely, set force=1 parameter in the DELETE request. Only owner (in private dialog type=3 owner or admin) can do this.

    Delete single dialog

    Endpoint
    DELETE https://api.connectycube.com/chat/Dialog/{dialog_id}
    Request example
    Terminal window
    curl -X DELETE \
    -H "CB-Token: <TOKEN>" \
    https://api.connectycube.com/chat/Dialog/5c091060e588ce59fdf873dc
    Response
    200 OK

    Delete several dialogs

    Endpoint
    DELETE https://api.connectycube.com/chat/Dialog/{dialog1_id},{dialog2_id}
    Request example
    Terminal window
    curl -X DELETE \
    -H "CB-Token: <TOKEN>" \
    https://api.connectycube.com/chat/Dialog/23thnu15e4b077ddd43e7db7,499abe15e4b077ddd43e7b5h
    Response
    {
    "SuccessfullyDeleted": {
    "ids": ["23thnu15e4b077ddd43e7db7"]
    },
    "NotFound": {
    "ids": ["499abe15e4b077ddd43e7b5h"]
    },
    "WrongPermissions": {
    "ids": ["5e394e7bca8bf410bc8017b0"]
    }
    }

    Clear dialog history

    This request will clear all messages in the dialog for current user, but not for other users.

    To clear all messages for each user form dialog completely, set force=1 parameter in the DELETE request. Only owner (in private dialog type=3 owner or admin) can do this.

    Endpoint
    DELETE https://api.connectycube.com/chat/Dialog/clearHistory/{dialog_id}
    Request example
    Terminal window
    curl -X DELETE \
    -H "CB-Token: <TOKEN>" \
    https://api.connectycube.com/chat/Dialog/clearHistory/5c091060e588ce59fdf873dc
    Response
    200 OK

    Subscribe to public dialog

    Add user to the list of occupants. Applicable for public dialogs (type=4) only.

    Endpoint
    POST https://api.connectycube.com/chat/Dialog/{dialog_id}/subscribe
    Request example
    Terminal window
    curl -X POST \
    -H "Content-Type: application/json" \
    -H "CB-Token: <TOKEN>" \
    https://api.connectycube.com/chat/Dialog/5c091822e588ce6856f873de/subscribe
    Response
    {
    "_id": "5c091822e588ce6856f873de",
    "admins_ids": [],
    "created_at": "2018-12-06T12:37:54Z",
    "description": "good news",
    "last_message": null,
    "last_message_date_sent": null,
    "last_message_id": null,
    "last_message_user_id": null,
    "last_message_status": "read",
    "name": "Public chat",
    "occupants_count": 2,
    "occupants_ids": [],
    "photo": null,
    "pinned_messages_ids": [],
    "type": 4,
    "updated_at": "2018-12-06T12:40:03Z",
    "user_id": 28926,
    "unread_messages_count": null,
    "xmpp_room_jid": "105_5c091822e588ce6856f873de@muc.chatstage.connectycube.com",
    "extensions": null,
    "permissions": null
    }

    Unsubsribe from public dialog

    Remove user from the list of occupants. Applicable for public dialogs (type=4) only.

    Endpoint
    DELETE https://api.connectycube.com/chat/dialog/{dialog_id}/subscribe
    Request example
    Terminal window
    curl -X DELETE \
    -H "CB-Token: <TOKEN>" \
    https://api.connectycube.com/chat/dialog/5c091822e588ce6856f873de/subscribe
    Response
    200 OK

    Add / Remove admins

    Options to add or remove admins from the dialog can be done by Super admin (dialog’s creator) only. Options are supported in group chat, public or broadcast.

    Up to 5 admins can be added to chat.

    Endpoint
    PUT https://api.connectycube.com/chat/Dialog/{dialog_id}/admins
    Parameters
    ParameterDescriptionValue example
    push_all[admins_ids][]Add admin(s) to the chat. Several admin IDs can be specified separated by comma{“push_all”: {“admins_ids”:[admin_id_1]}}
    pull_all[admins_ids][]Remove admin(s) from the chat. Several admin IDs can be specified separated by comma{“pull_all”:{“admins_ids”: [admin_id_1]}}
    Request example
    Terminal window
    curl -X PUT \
    -H "Content-Type: application/json" \
    -H "CB-Token: <TOKEN>" \
    -d '{"push_all": {"admins_ids": [29087]}}' \
    https://api.connectycube.com/chat/Dialog/5c093376e588ce6856f873fe/admins
    Response
    {
    "_id": "5c093376e588ce6856f873fe",
    "admins_ids": [29087],
    "created_at": "2018-12-06T14:34:30Z",
    "description": "admins only",
    "last_message": null,
    "last_message_date_sent": null,
    "last_message_id": null,
    "last_message_user_id": null,
    "last_message_status": "delivered",
    "name": "Friday party",
    "occupants_ids": [29085, 29086, 29087],
    "photo": null,
    "pinned_messages_ids": [],
    "type": 2,
    "updated_at": "2018-12-06T14:42:25Z",
    "user_id": 29085,
    "unread_messages_count": null,
    "xmpp_room_jid": "105_5c093376e588ce6856f873fe@muc.chatstage.connectycube.com",
    "extensions": null,
    "permissions": null
    }

    Update notifications settings

    User can turn on/off push notifications for offline messages in a dialog. By default push notification are turned ON, so offline user receives push notifications for new messages in a chat if notifications setting wasn’t changed.

    Endpoint
    PUT https://api.connectycube.com/chat/Dialog/{dialog_id}/notifications
    Parameters
    ParameterValueDescription
    enabled0 or 1Enable/ Disable notifications
    Request example
    Terminal window
    curl -X PUT \
    -H "Content-Type: application/json" \
    -H "CB-Token: <TOKEN>" \
    -d '{"enabled":"0"}'
    https://api.connectycube.com/chat/Dialog/5c093376e588ce6856f873fe/notifications
    Response
    {
    "notifications": {
    "enabled": 0
    }
    }

    Get notifications settings

    Check a status of notifications setting - either it is ON or OFF for a particular chat.

    Available responses: 1 - enabled, 0 - disabled.

    Endpoint
    GET https://api.connectycube.com/chat/Dialog/{dialog_id}/notifications
    Request example
    Terminal window
    curl -X GET \
    -H "CB-Token: <TOKEN>" \
    https://api.connectycube.com/chat/Dialog/5c093376e588ce6856f873fe/notifications
    Response
    {
    "notifications": {
    "enabled": 0
    }
    }

    Retrieve public dialog occupants

    A public chat dialog can have many occupants. There is a separated API to retrieve a list of public dialog occupants.

    Endpoint
    GET https://api.connectycube.com/chat/Dialog/{dialog_id}/occupants
    Parameters
    OperatorDescriptionValue example
    limitSetting of limit for a number of search results to display. Default - 100limit=70
    skipSkip the defined number of records in the search results. By default all records are shownskip=20
    Request example
    Terminal window
    curl -X GET \
    -H "CB-Token: <TOKEN>" \
    https://api.connectycube.com/chat/Dialog/5c093376e588ce6856f873fe/occupants
    Response
    {
    "items": [
    {
    "id": 51941,
    "full_name": "Dacia Kail",
    "email": "dacia_k@domain.com",
    "login": "Dacia",
    "phone": "+6110797757",
    "website": null,
    "created_at": "2018-12-06T09:16:26Z",
    "updated_at": "2018-12-06T09:16:26Z",
    "last_request_at": null,
    "external_user_id": 52691165,
    "facebook_id": "91234409",
    "twitter_id": "83510562734",
    "blob_id": null,
    "custom_data": null,
    "avatar": null,
    "user_tags": null
    },
    {
    "id": 51946,
    "full_name": "Gabrielle Corcoran",
    "email": "gabrielle.corcoran@domain.com",
    "login": "gabby",
    "phone": "+6192622155",
    "website": "http://gabby.com",
    "created_at": "2018-12-06T09:29:57Z",
    "updated_at": "2018-12-06T09:29:57Z",
    "last_request_at": null,
    "external_user_id": null,
    "facebook_id": "95610574",
    "twitter_id": null,
    "blob_id": null,
    "custom_data": "Responsible for signing documents",
    "avatar": null,
    "user_tags": "vip,accountant"
    }
    ...
    ]
    }
    Response
    {
    "notifications": {
    "enabled": 1
    }
    }

    Retrieve messages

    Retrieve all chat messages within a particular dialog. For broadcast chat (type=1) all users within the app can see messages from the dialog. To retrieve chat messages from group chat (type=2) and privat chat (type=3) user’s IDs should be in occupants_ids field, whereas for public chat (type=4) user’s IDs should belong to occupants_count field. Server will return dialog’s chat messages sorted ascending by date_sent field (default sort is applied and can be changed if required).

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

    Endpoint
    GET https://api.connectycube.com/chat/Message
    Parameters
    OperatorApplied fieldsDescriptionValue example
    {field_name}_id, message, date_sent, sender_id, recipient_id, attachments.type, updated_atRetrieve messages with the exact data specified in the requestrecipient_id=546
    {field_name}[{search_operator}]_id, message, date_sent, sender_id, recipient_id, attachments.type, updated_atRetrieve messages with the exact data specified in the request with applying additional filters. Available 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), ctn (Contains substring operator)sender_id[lt]=132
    limitstandalone operatorSet limit for a number of search results. Default - 100limit=50
    skipstandalone operatorSkip the defined number of records in the search results. By default all records are shownskip=30
    sort_desc/sort_ascdate_sentSorting of query result set in ascending / descending ordersort_asc=date_sent
    mark_as_readstandalone operatorDo not mark the received messages as read. To do not mark retrieved messages as read, mark_as_read parameter should be set to 0mark_as_read=0
    previewstandalone operatorYou can retrieve last 20 message if you not chat member (occupants_ids), only for dialogs with permissions prop allow_preview = true, parameters skip, limit, sort_desc, sort_asc will be ignoredpreview=1
    Request example
    Terminal window
    curl -X GET \
    -H "CB-Token: <TOKEN>" \
    -d 'chat_dialog_id=5c093376e588ce6856f873fe' \
    https://api.connectycube.com/chat/Message
    Response
    {
    "skip": 0,
    "limit": 1000,
    "items": [
    {
    "_id": "5c094682e588ce59fff87424",
    "attachments": [],
    "chat_dialog_id": "5c093376e588ce6856f873fe",
    "created_at": "2018-12-06T15:55:46Z",
    "date_sent": 1544111746,
    "delivered_ids": [29085, 29086],
    "message": "What's the price of it?",
    "read_ids": [29085, 29086],
    "recipient_id": 0,
    "sender_id": 29085,
    "updated_at": "2018-12-06T16:05:21Z",
    "reactions": null,
    "views_count": 0,
    "read": 0
    },
    {
    "_id": "5c094687e588ce59fff87425",
    "attachments": [],
    "chat_dialog_id": "5c093376e588ce6856f873fe",
    "created_at": "2018-12-06T15:55:51Z",
    "date_sent": 1544111751,
    "delivered_ids": [29085, 29086],
    "message": "Hello Daniel, how things are going on?",
    "read_ids": [29085, 29086],
    "recipient_id": 0,
    "sender_id": 29085,
    "updated_at": "2018-12-06T16:05:21Z",
    "reactions": { "own": ["👍", "👌"], "total": { "👍": 2, "👌": 1, "🚧": 5 } },
    "views_count": 0,
    "read": 0
    }
    ]
    }

    Retrieve unread messages count

    Retrieve the number of unread chat messages. The output is split across dialogs plus a total number value.

    Endpoint
    GET https://api.connectycube.com/chat/Message/unread
    Parameters
    OperatorDescriptionValue example
    chat_dialog_idsList of dialogs to retrieve the number of unread messages. Applied only for group chat (type=2) and privat chat (type=3). You can skip the parameter - in this case only total number of unread messages will be returned.chat_dialog_ids=id_1,id_2
    Request example
    Terminal window
    curl -X GET \
    -H "CB-Token: <TOKEN>" \
    -d 'chat_dialog_ids=5c093376e588ce6856f873fe,76ok0l3e989c12a0e45432a7' \
    https://api.connectycube.com/chat/Message/unread
    Response
    {
    "total": 5,
    "53aadc78535c127f15009b6c": 3,
    "76ok0l3e989c12a0e45432a7": 2
    }

    Create a message

    Create a chat message to add it to the chat history. Created message won’t be delivered to the recipient(s) by Real-Time (XMPP) transport and will be just added to the chat history.

    To initiate a real sending to the chat - pass send_to_chat=1 parameter.

    Endpoint
    POST https://api.connectycube.com/chat/Message
    Parameters
    ParameterRequiredDescriptionValue example
    chat_dialog_idyes, if the recipient_id key is not specifiedID of a dialog where a new message will be added{“chat_dialog_id”: “5bec0186e588ce7ff1c0ad0a”}
    messagenotext of the message (CGI-escaped){“message”: “Hi! How are you doing?“}
    recipient_idyes, if the ‘chat_dialog_id’ key is not specifiedID of a recipient. Useful for private chats only (type 3){“recipient_id”: “4377”}
    attachments[n][type/id/url]noList of attachments. Each attachment object contains 3 keys: type (audio/video/image/…), id (link to file ID in Connectycube), url (link to file in the Internet){“attachments”: {“0”: {“type”: “image”, “id”: “654645”}, “1”: {“type”: “video”, “id”: “654646”}}}
    Custom parametersnoKey-value parameters. Chat message can contain any other custom parameters{“country”: “USA”}
    send_to_chatnoSend message to chat. Should be set to 1 if message should be sent{“send_to_chat”: “1”}
    markablenoMark message to be processed as read / delivered statuses on a client side{“markable”: “1”}
    Request example
    Terminal window
    curl -X POST \
    -H "Content-Type: application/json" \
    -H "CB-Token: <TOKEN>" \
    -d '{"chat_dialog_id": "5c094c0ce588ce6856f87422", "message": "where are you?", "recipient_id": 29086, "attachments": {"3": {"type": "image", "id": "3004"}, "7": {"type": "image", "id": "24504"}}}' \
    https://api.connectycube.com/chat/Message
    Response
    {
    "_id": "5c094e30e588ce59fff87431",
    "attachments": [
    {
    "type": "image",
    "id": "3004"
    },
    {
    "type": "image",
    "id": "24504"
    }
    ],
    "chat_dialog_id": "5c094c0ce588ce6856f87422",
    "created_at": "2018-12-06T16:28:32Z",
    "date_sent": 1544113712,
    "delivered_ids": [29086],
    "message": "where are you?",
    "read_ids": [29086],
    "recipient_id": 29086,
    "sender_id": 29086,
    "updated_at": "2018-12-06T16:28:32Z",
    "views_count": 0,
    "read": 0
    }

    Update message

    Update of sent chat message. Message body and message status can be updated.

    It’s possible to mark all messages as read / delivered - just don’t pass a message id.

    Endpoint
    PUT https://api.connectycube.com/chat/Message/{message1_id},{message2_id}
    Parameters
    FieldDescriptionExample
    chat_dialog_idDialog’s id which message is updated{“chat_dialog_id”: “5b7411335bd08d0e5761bc96”}
    readMark message as read{“read”:“1”}
    deliveredMark message as delivered{“delivered”: “1}
    messageUpdated message body{“message”: “Morning”}
    Request example
    Terminal window
    curl -X PUT \
    -H "Content-Type: application/json" \
    -H "CB-Token: <TOKEN>" \
    -d '{"read": "1", "chat_dialog_id": "5c094c0ce588ce6856f87422"}'\
    https://api.connectycube.com/chat/Message/5c094e30e588ce59fff87431
    Response
    200 OK

    Delete message

    Remove of a chat message for the current user in a specified chat dialog.

    There are some rules for removing messages depending the type of the dialog:

    • For broadcast chat (type=1) only Super admin and admins are able to remove messages from the dialog. General users are readers only.

    • For group chat (type=2) 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 in the chat history for all other users in the dialog. To remove a message completely, force=1 parameter should be set. Super admin and admins can remove all messages from the dialog, whereas general users are able to remove only own message for all users with force=1 parameter, but other users messages can remove only for themselves.

    • For private chat (type=3) users are able remove their own messages from the history. Users can remove messages both, without affecting the history of other user, and, as well as completely remove a message. To remove message for both sides force=1 parameter should be set for own messages.

    • For public chat (type=4) any user in the dialog’s occupants_count 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 in the chat history for all other users in the dialog. To remove a message completely, force=1 parameter should be set. Super admin and admins can remove all messages from the dialog, whereas general users are able to remove only own message for all users with force=1 parameter, but other users messages can remove only for themselves.

    Deleting a message with the force=1 parameter is followed by sending a XMPP packet to the chat room with the request to immediately remove the message from other occupants history.

    Endpoint
    DELETE https://api.connectycube.com/chat/Message/{message1_id},{message2_id}
    Request example
    Terminal window
    curl -X DELETE \
    -H "CB-Token: <TOKEN>" \
    https://api.connectycube.com/chat/Message/5c094687e588ce59fff87425,5c094682e588ce59fff87424
    Response
    {
    "SuccessfullyDeleted": {
    "ids": ["5c094687e588ce59fff87425"]
    },
    "NotFound": {
    "ids": ["5c094682e588ce59fff87424"]
    },
    "WrongPermissions": {
    "ids": ["5c094682e588ce59fff87423"]
    }
    }

    Send system message

    Create a system message to send a signal. System message will be delivered to the recipient(s) by Real-Time (XMPP) transport.

    Endpoint
    POST https://api.connectycube.com/chat/Message/system
    Parameters
    FieldRequiredDescriptionValue example
    recipientIdYesrecipient user id{“recipientId”: 29086}
    [key string]Noany key value pain (string : string/object){“userExt”: { “name”: “Smith” }, “nickname”: “Awesome_smith”}
    Request example
    Terminal window
    curl -X POST \
    -H "Content-Type: application/json" \
    -H "CB-Token: <TOKEN>" \
    -d '{"recipientId": 29086, "needToUpdatePhotosStories": "1", "friendId": "90675", "userExt": { "name": "Smith" }, "nickname": "Awesome_smith"}' \
    https://api.connectycube.com/chat/Message/system
    Response
    {
    "messageId": "641307a86e010326b51594dc",
    "recipientId": 29086,
    "extensionParams": {
    "needToUpdatePhotosStories": "1",
    "friendId": "90675",
    "userExt": { "name": "Smith" },
    "nickname": "Awesome_smith"
    }
    }

    Message reactions

    User can add or remove reactions (string) and receive chat server message Message response reaction format

    Field nameDescription
    ownarray of user reactions (session user)
    totalobject where key is reaction type and value is count of reactions (including own)
    {
    ...
    "reactions": {
    "own": ["👌", "😐"],
    "total": {
    "👌": 5,
    "😐": 1
    }
    }
    ...
    }

    Add/Remove reactions

    User can has only one reaction type

    Endpoint
    PUT https://api.connectycube.com/chat/Message/{message_id}/reactions
    Request example
    Terminal window
    curl -X PUT \
    -H "CB-Token: <TOKEN>" \
    -d '{"add": "👍", "remove": "👎"}'\
    https://api.connectycube.com/chat/Message/5c094687e588ce59fff87425/reactions
    Response
    200 OK

    xmpp message will be sent to chat participants

    <message type="..." xmlns="jabber:client" to="..." id="..." from="...">
    <extraParams xmlns="jabber:client">
    <dialog_id>6304b6a59cf9db00200c1cf7</dialog_id>
    </extraParams>
    <reactions user_id="89209" message_id="5c094687e588ce59fff87425">
    <reaction add="true" type="👍"/>
    <reaction remove="true" type="👎"/>
    </reactions>
    </message>

    List reactions

    User get message reactions object where key is reactions type and value is array of user_ids

    Endpoint
    GET https://api.connectycube.com/chat/Message/{message_id}/reactions
    Request example
    Terminal window
    curl -X GET \
    -H "CB-Token: <TOKEN>" \
    https://api.connectycube.com/chat/Message/5c094687e588ce59fff87425/reactions
    Response
    {
    "👍": [67456, 5687],
    "👎": [67456, 5687, 9736],
    "🚀": [9736]
    }

    It helps to find some messages and chat dialogs.

    Endpoint
    GET https://api.connectycube.com/chat/search
    Parameters
    FieldRequiredDescriptionValue example
    search_textYesString. Should be longer than 4 symbols. Searches for the sub-string against chat message’s ‘message’ field and dialog’s ‘name’ field. Case sensitive.search_text=“lorem”
    chat_dialog_idsNoList of dialog ids separated by comas. Max cam include 10 items.chat_dialog_ids=5c49cb855368b57a05dc5872
    start_dateNoClosest date to Time.now. Uses lte comparison.start_date=2016-03-23T17:00:42Z
    end_dateYes, if start_date passedShouldn’t differ by more than 3 months from the start_date. Uses gte comparison.start_date=2016-01-23T17:00:42Z
    limitNoMaximum number of items returned from the server in the search results. Max value - 100limit=3
    Request example
    Terminal window
    curl -X GET \
    -H "Content-Type: application/json" \
    -H "CB-Token: <TOKEN>" \
    'https://api.connectycube.com/chat/search?search_text=lorem&limit=3'
    Response
    {
    "results": {
    "dialogs": [
    {
    "_id": "5c4867115368b52b3f5c6b16",
    "admins_ids": [],
    "created_at": "2019-01-23T13:07:29Z",
    "description": null,
    "last_message": null,
    "last_message_date_sent": null,
    "last_message_id": null,
    "last_message_user_id": null,
    "name": "lorem ipsum dolor",
    "occupants_ids": [23, 2172],
    "photo": null,
    "pinned_messages_ids": [],
    "type": 3,
    "updated_at": "2019-01-23T13:07:29Z",
    "user_id": 2172,
    "unread_messages_count": null,
    "xmpp_room_jid": null
    }
    ],
    "messages": [
    {
    "_id": "5c49ccef5368b57a05dc5877",
    "attachments": [],
    "chat_dialog_id": "5c49cb855368b57a05dc5872",
    "created_at": "2019-01-24T14:34:23Z",
    "date_sent": 1548340463,
    "delivered_ids": [2172],
    "message": "Ipsa lorem tempore vitae earum sequi aut velit qui.",
    "read_ids": [2172],
    "recipient_id": 0,
    "sender_id": 2172,
    "updated_at": "2019-01-24T14:34:23Z",
    "views_count": 0,
    "read": 0
    },
    {
    "_id": "5c49cd815368b57a05dc5882",
    "attachments": [],
    "chat_dialog_id": "5c49cb855368b57a05dc5872",
    "created_at": "2019-01-24T14:36:49Z",
    "date_sent": 1548340609,
    "delivered_ids": [2172],
    "message": "Incidunt maxime sapiente cum est dolor fugit lorem.",
    "read_ids": [2172],
    "recipient_id": 0,
    "sender_id": 2172,
    "updated_at": "2019-01-24T14:36:49Z",
    "views_count": 0,
    "read": 0
    }
    ],
    "users": []
    }
    }