Your server can call this API to triger Event, query Channel, and so forth.

Authorization Mechanism

The authentication of all the requests uses HTTP Basic Authentication. username is App ID and password is Secret. You can go to [Application] -> [Settings]-> [Secret] on our website to view them.

Frequently-used Response Status Code

  • 200 OK: Requested successfully. The response content is decided by the real API.

  • 400 Bad Request: Requested incorrectly or parameter absent. The detailed parameter name and the corresponding error information lie in the response body.

  • 401 Unauthorized: Authentication failed or the user has no permission to the request item.

  • 403 Forbidden: Invocation exceeds the limit.

  • 404 Not Found: Request path error or the resource requested has been deleted.

  • 500 Internal Server Error: Server error. Please try later or contact us.

  • 503 Service Unavailable: Server is under maintenance. Please try later or contact us.

Pub/Sub Event 

Set of Events 

Trigger
/v2/open/engine/events

Trigger Event on one or more Channels by using this API.

Note that a successful return of this API only indicates we have accepted this request but doesn't mean all the clients have received this `Event`, and the real transmission process is asynchronous.
  • Request
  • Headers
    Content-Type: application/json
    Body
    {
        // Required, String, Event Name
        "name": "comment-added",
        // Optional, of Object type, Event data, up to 10KB
        "data": {
            "postId": 123,
            "commentId": 456
        },
        // Required, Array, to trigger this Event on which Channels, up to 10
        "channels": ["comments"],
        // Optional, String, this `Event` will not be received on the specified client, usually used to exclude the trigger of the `Event` 
        "excludedSocketId": "0qI6JEP7NODMzvhBANvO"
    }
  • Response  200

Pub/Sub Channel 

One Channel 

Get
/v2/open/engine/channels/{channelName}

This interface returns the detailed information of the Channel according to names:

  • occupied: Whether this Channel is being used.

  • subscriptionCount: Number of subscriptions.

  • userCount: Number of users, only limited to Presence Channel, duplicate user only counted once.

  • Parameters
  • channelName
    String (required) 

    The name of the Channel to be obtained

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
      "occupied": true,
      "subscriptionCount": 100,
      "userCount": 96
    }

Presence Channel User ID 

Get List
/v2/open/engine/channels/{channelName}/userIds

The userId of all the users on Presence Channel can be obtained, using this interface for non Presence Channel will return the 404 error.

userId comes from the return value of the callback of authenticated users. For more details, see Authenticated Users

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
      "1122",
      "1123"
    ]

ChatUser 

ChatUser 

New
/v2/open/engine/chat/users

If userId is duplicate, please update the user information.

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
        // Required
        "userId": "1111",
        // Opitonal, user nickname, used to show offline notifications on mobile devices; if not provided, userId will be used instead
        "nickname": "tuisongbao",
        // Optional, language, the value is either zh-cn or en-us, used to show offline notifications on mobile devices; if not provided, Chinese (zh-cn) will be used instead
        "language": "zh-cn"
    }
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
        // Indicates whether a new user is created (There is no this userId before)
        "isNew": false
    }

Conversations 

Get
/v2/open/engine/chat/users/{userId}/conversations{?conversationId,target,type,lastActiveAt,active}

Precedence Rules of Parameters:

  1. If there is conversationId, query according to the conversationId, otherwise, go to next step;

  2. Filter the query according to other options; if no, return all the conversations.

  • Parameters
  • userId
    string (required) 

    The unique ID of a user.

    conversationId
    string (optional) 

    The unique ID of a conversation.

    target
    string (optional) 

    userId or groupId。

    type
    string (optional) 

    singleChat or groupChat

    lastActiveAt
    string (optional) 

    Last updated, indicating only to choose the conversations with new dinamics after this date, using the ISO 8061 specification, such as 2015-01-25T07:47:09.678Z.

    active
    string (optional) Default: true 

    true or false. true is to return the conversations that have not been deleted, and false is to return the conversations that have been deleted.

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [{
        "conversationId": "5469baa02a4da5300fb24220"
        // Conversation type, singleChat(single chat) or groupChat (group chat)
        "type": "singleChat",
        // With whom,userId or groupId
        "target": "1111",
        // Number of unread messages
        "unreadMessageCount": 7,
        // Return the last message. If no, this field does not exist
        "lastMessage": {
            "messageId": 300,
            "type": "singleChat",
            "from": "1111",
            "to": "1112",
            "content": {
                "type": "text",
                "text": "Hello World!"
                "extra": {}
            },
            "createdAt": "2015-01-25T07:47:09.678Z"
        },
        // Additional information of Object type. Used to implement custom business logic of the application
        "extra": {},
        // Last activity time
        "lastActiveAt": "2015-01-25T07:48:09.678Z"
    }]

Groups 

Get List
/v2/open/engine/chat/users/{userId}/groups{?groupId,lastActiveAt}
  • Parameters
  • groupId
    string (optional) 

    The unique group ID.

    lastActiveAt
    string (optional) 

    Last updated, indicating only to choose the conversations with new dinamics after this date, using the ISO 8061 specification, such as 2015-01-25T07:47:09.678Z. If specified by groupId, this condition will be ignored.

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [{
        "groupId": "54c4951f50c5e752c0a512a1",
        // Create userId
        "owner": "1111",
        // Whether a group is public (true: The request for joining a group from any user will be directly passed without verification; false: Need the administrator to verify) 
        "isPublic": true,
        // Except the creator (owner), whether other group users can send invitations to join the group (true: allowed; false: not allowed)
        "userCanInvite": true,
        // Number of group users at present
        "userCount": 100,
        // Upper limit of group users
        "userCountLimit": 1000,
        // Wheter a group is deleted, used to delete local cache, a result that is returned only when lastActive is contained in a request
        // When lastActive is not contained, the result that is returned does not contained the group deleted
        "isRemoved": true,
        // Last activity time
        "lastActiveAt": "2015-01-25T07:47:09.678Z"
    }]

ChatConversation 

ChatConversation 

New or Update
/v2/open/engine/chat/conversations
  • Request
  • Headers
    Content-Type: application/json
    Body
    {
        // Conversation type, singleChat(single chat) or groupChat(group chat)
        "type": "groupChat",
        // For single chat, two userId for peers, in no particular order; for group chat, the first is userId, and the second is groupId
        "peers": ["1111", "54c4951f50c5e752c0a512a1"],
        // Additional information of Object type, optional. Used to implement custom business logic of the applicaiton. If specified, an overriding will be performed, and if not, it indicates the last settings will be kept 
        "extra": {},
        // Optional, valid only when a conversation is initially created. If developers make sure this WebHook will not be changed, this option is suggested; if there is any change later, please use the Open API of the WebHook to modify
        "webHook": {
            // Notifications need to be called back for which events; cannot be Null
            "eventTypes": ["messsage_new"],
            "url": "",
            // State of use, enabled by default
            "status": "enabled"
        }
    }
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
         "conversationId": "5469baa02a4da5300fb24220",
         // The WebHook related information will be returned when WebHook is created successfully, otherwiser, not returned
         "webHook": {
            // conversationId
            "target": "5469baa02a4da5300fb24220",
            "eventTypes": ["messsage_new"],
            "url": "",
            "status": "enabled"
        }
    }
Delete
/v2/open/engine/chat/conversations
  • Request
  • Headers
    Content-Type: application/json
    Body
    {
        // Conversation type, singleChat(single chat) or groupChat(group chat)
        "type": "groupChat",
        // The first is userId, indicating a certain conversation of this user will be deleted; the sencond is target, indicating the conversation with whom will be deleted. For single chat, userId is required, and for group chat, groupId is required
        "peers": ["1111", "54c4951f50c5e752c0a512a1"]
    }
  • Response  200

Messages 

Get conversation list, and for the details on parameter description, see here.

Get List
/v2/open/engine/chat/conversations/{conversationId}/messages{?startMessageId,endMessageId,limit}
  • Parameters
  • conversationId
    string (required) 

    The unique ID of a conversation.

    startMessageId
    int (optional) 

    Start messageId.

    endMessageId
    int (optional) 

    End messageId.

    limit
    int (optional) Default: 20; Max: 100 

    Number of messages.

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [{
        // The increment ID of this Conversation
        "messageId": 300,
        // Conversation type, singleChat(single chat) or groupChat(group chat)
        "type": "singleChat",
        // From whom, userId
        "from": "1111",
        // To whom, userId or groupId
        "to": "1112",
        "content": {
            // Content of text message
            "type": "text",
            "text": "Hello World!"
            // Additional information of Object type. Used to implement custom business logic of the application
            "extra": {}
        },
        "createdAt": "2015-01-25T07:47:09.678Z"
    }]

WebHook 

For more details and the use guide on WebHook, see Realtime Engine Guide-WebHook

Get
/v2/open/engine/chat/conversations/{conversationId}/webHook
  • Parameters
  • conversationId
    string (required) 

    The unique ID of a conversation.

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
        // conversationId
        "target": "5469baa02a4da5300fb24220",
        "eventTypes": ["message_new"],
        "url": "",
        "status": "enabled"
    }
Update
/v2/open/engine/chat/conversations/{conversationId}/webHook

Override will be performed to the settings of all fields. It indicates that the last settings will be kept if not specified.

  • Parameters
  • conversationId
    string (required) 

    The unique ID of a conversation.

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
        // Notifications need to be called back for which events; cannot be Null
        "eventTypes": ["message_offline"],
        // Optional
        "url": "",
        // Optional, state of use; to disable, use disabled; to enable, use enabled
        "status": "disabled"
    }
  • Response  200
Delete
/v2/open/engine/chat/conversations/{conversationId}/webHook
  • Parameters
  • conversationId
    string (required) 

    The unique ID of a conversation.

  • Response  200

ChatMessage 

ChatMessage 

New
/v2/open/engine/chat/messages
  • Request
  • Headers
    Content-Type: application/json
    Body
    {
        // Conversation type, singleChat(single chat) or groupChat(group chat)
        "type": "singleChat",
        // From whom, userId
        "from": "1111",
        // To whom, userId or groupId
        "to": "1112",
        // Can only specify messages of one type, such as `text`, `image`, `voice`, `video` or `location`. For the details on the message structure of each type, please refer to the following example. If no special remark, all the fields are optional
        "content": {
            // Content of text message
            "type": "text",
            "text": "Hello World!",
    
            // Content of image message
            "type": "image",
            "file": {
                "name": '1156473951.jpg',
                "size": '62655',
                "etag": 'FuVXerYLy1fB8yCwyt6lzoCICoBG',
                "mimeType": 'image/jpeg',
                "width": 540,
                "height": 960,
                // Required, URL of origianl files
                "url": ""// URL of thumbnail, the width of the image is less than or equal to 100px
                "thumbUrl": ""
            },
    
            // Content of voice message
            "type": "voice",
            "file": {
                "name": 'blob',
                "size": '71724',
                "etag": 'FpVRuykW1lwqHeH37uyGJJ5_Dqzh',
                "mimeType": 'audio/x-wav',
                "duration": 3.251089,
                // Required, URL of origianl files
                "url": ""
            },
    
            // Content of video message
            "type": "video",
            "file": {
                "name": 'blob',
                "size": '1271724',
                "etag": 'FpVRuykW1lwqHeH37uyGJJ5_Dqzh',
                "mimeType": 'video/mp4',
                "width": 540,
                "height": 960,
                "duration": 15.251089,
                // Required, URL of origianl files
                "url": ""// URL of thumbnail, the width of the image is less than or equal to 100px
                "thumbUrl": ""
            },
    
            // Content of location data message
            "type": "location",
            "location": {
                // Required, latitude
                "lat": 31.211977,
                // Required, longitude
                "lng": 121.604338,
                // Point of interest, obtained through API of Baidu Maps (overseas location not supported) if not submitted by clients
                "poi": "Building #30, Pudong Software Park, Shanghai "
            },
    
            // Optional, additional information of Ojbect type. a common field, used to implement custom business logic of the application
            "extra": {}
        }
    }
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
      "messageId": 300
    }

ChatGroup 

ChatGroup 

New
/v2/open/engine/chat/groups
  • Request
  • Headers
    Content-Type: application/json
    Body
    {
        // The creator(owner)
        "owner": "1111",
        // Invite these users to join the group
        "inviteUserIds": ["2222"],
        // Optional, valid only when a group is initially created. If developers make sure this WebHook will not be changed, this option is suggested; if there is any change later, please use the Open API of the WebHook to modify
        "webHook": {
            // Notifications need to be called back for which events; cannot be Null
            "eventTypes": ["user_presence"],
            "url": "",
            // enabled by default
            "status": "enabled"
        }
    }
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
        "groupId": "54c4951f50c5e752c0a512a1",
        // The WebHook related information will be returned when WebHook is created successfully, otherwiser, not to be returned
        "webHook": {
            // groupId
            "target": "54c4951f50c5e752c0a512a1",
            "eventTypes": ["user_presence"],
            "url": "",
            "status": "enabled"
        }
    }

Users 

Get
/v2/open/engine/chat/groups/{groupId}/users
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [{
        "userId": "1111",
        // Online state, online or offline
        "presence": "online"
    }]
Add
/v2/open/engine/chat/groups/{groupId}/users
  • Request
  • Headers
    Content-Type: application/json
    Body
    {
        // Invite these users to join the group
        "userIds": ["2222"]
    }
  • Response  200
Remove
/v2/open/engine/chat/groups/{groupId}/users
  • Request
  • Headers
    Content-Type: application/json
    Body
    {
        // Remove these users
        "userIds": ["2222"]
    }
  • Response  200

WebHook 

For more details and the use guide on WebHook, see Realtime Engine Guide-WebHook

Get
/v2/open/engine/chat/groups/{groupId}/webHook
  • Parameters
  • groupId
    string (required) 

    The unique ID of a group

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
        // groupId
        "target": "54c4951f50c5e752c0a512a1",
        "eventTypes": ["user_presence"],
        "url": "",
        "status": "disabled"
    }
Update
/v2/open/engine/chat/groups/{groupId}/webHook

Override will be performed to the settings of all fields. It indicates that the last settings will be kept if not specified.

  • Parameters
  • groupId
    string (required) 

    The unique ID of a group

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
        // Notifications need to be called back for which events; cannot be Null
        "eventTypes": ["user_presence"],
        // Optional
        "url": "",
        // Optional, state of use; to disable, use disabled; to enable, use enabled
        "status": "disabled"
    }
  • Response  200
Remove
/v2/open/engine/chat/groups/{groupId}/webHook
  • Parameters
  • groupId
    string (required) 

    The unique ID of a group

  • Response  200
  Back To Top