Room
Create or Update Room
Update and/or delete contacts.
The xcRoomID
is used to identify an existing room. If it does not exist yet, the room will be saved as a new room. If it already exist, the room type must also match the existing room's type.
The following room type values are allowed:
Values
Description
2
Group Chat
4
Transaction Room
Notes:
The parameter tags
will override existing room's tags.
The parameter participantXCUserIDs
will be ignored when updating an already existing room.
The parameter participantUserRoles
will override existing room's participant user role codes.
Parameters
xcRoomID
string
(101) The room ID from customer's server.
Size range: 1..50
type
integer
(102) The room type
name
string
(103) The room name
photoThumbnailURL (optional)
string
(104) The room's thumbnail picture image URL
photoFullsizeURL (optional)
string
(105) The room's fullsize picture image URL
tags (optional)
string[]
(106) The room's tags
participantXCUserIDs (optional)
string[]
(107) The list of participants, for new room only
participantUserRoles (optional)
string[]
(108) The list of user roles to be considered as participants
Success 200
room
object
The room's details.
roomID
string
Room ID.
xcRoomID
string
The room ID from customer's server.
name
string
The room's name.
type
integer
The room type.
imageURL
object
The room's picture image URL.
thumbnail
string
Image URL for thumbnail picture.
fullsize
string
Image URL for fullsize picture.
color
string
The room's color code, in hex.
isLocked
boolean
If the room was locked.
lockedTime
long
The time the room was locked, in Unix milliseconds.
deleted
long
The room's deleted time, in Unix milliseconds.
isDeleted
boolean
If the room was deleted.
participants
object[]
The list of participants.
userID
string
The user ID.
xcUserID
string
The user ID from customer's server.
fullname
string
The user's full name.
string
The email address.
isEmailVerified
boolean
If the email address is verified.
countryID
integer
The user's country ID.
countryCallingCode
string
The country calling code for phone number.
phone
string
The phone number.
phoneWithCode
string
The phone number with country calling code.
isPhoneVerified
boolean
If the phone number is verified.
username
string
The username.
imageURL
object
The user's picture image URL.
thumbnail
string
Image URL for thumbnail picture.
fullsize
string
Image URL for fullsize picture.
userRole
object
The user role.
code
string
The user role code.
name
string
The user role name.
iconURL
string
The user role's icon URL.
lastLogin
long
The user's last login, in Unix milliseconds.
lastActivity
long
The user's last activity, in Unix milliseconds.
isOnline
boolean
If the user is currently online.
created
long
The time the user was created, in Unix milliseconds.
updated
long
The time the user was last updated, in Unix milliseconds.
adminUserIDs
string[]
The list of admins' user IDs.
Error 4xx
Name
Description
ParamValidationFailed
The parameter validation failed.
HeaderValidationFailed
The request header validation failed.
Get Room Details
Get a chat room's details and participants.
Parameter
xcRoomID
string
(101) The room ID from customer's server.
Size range: 1..50
Success 200
room
object
The room's details.
roomID
string
Room ID.
xcRoomID
string
The room ID from customer's server.
name
string
The room's name.
type
integer
The room type.
imageURL
object
The room's picture image URL.
thumbnail
string
Image URL for thumbnail picture.
fullsize
string
Image URL for fullsize picture.
color
string
The room's color code, in hex.
isLocked
boolean
If the room was locked.
lockedTime
long
The time the room was locked, in Unix milliseconds.
deleted
long
The room's deleted time, in Unix milliseconds.
isDeleted
boolean
If the room was deleted.
participants
object[]
The list of participants.
userID
string
The user ID.
xcUserID
string
The user ID from customer's server.
fullname
string
The user's full name.
string
The email address.
isEmailVerified
boolean
If the email address is verified.
countryID
integer
The user's country ID.
countryCallingCode
string
The country calling code for phone number.
phone
string
The phone number.
phoneWithCode
string
The phone number with country calling code.
isPhoneVerified
boolean
If the phone number is verified.
username
string
The username.
imageURL
object
The user's picture image URL.
thumbnail
string
Image URL for thumbnail picture.
fullsize
string
Image URL for fullsize picture.
userRole
object
The user role.
code
string
The user role code.
name
string
The user role name.
iconURL
string
The user role's icon URL.
lastLogin
long
The user's last login, in Unix milliseconds.
lastActivity
long
The user's last activity, in Unix milliseconds.
isOnline
boolean
If the user is currently online.
created
long
The time the user was created, in Unix milliseconds.
updated
long
The time the user was last updated, in Unix milliseconds.
adminUserIDs
string[]
The list of admins' user IDs.
Error 4xx
Name
Description
ParamValidationFailed
The parameter validation failed.
HeaderValidationFailed
The request header validation failed.
RoomNotFound
The room is not found
Add Participants
Add participants to a chat room.
Parameters
xcRoomID
string
(101) The room ID from customer's server.
Size range: 1..50
participantXCUserIDs
string[]
(107) The list of participants.
Success 200
room
object
The room's details.
roomID
string
Room ID.
xcRoomID
string
The room ID from customer's server.
name
string
The room's name.
type
integer
The room type.
imageURL
object
The room's picture image URL.
thumbnail
string
Image URL for thumbnail picture.
fullsize
string
Image URL for fullsize picture.
color
string
The room's color code, in hex.
isLocked
boolean
If the room was locked.
lockedTime
long
The time the room was locked, in Unix milliseconds.
deleted
long
The room's deleted time, in Unix milliseconds.
isDeleted
boolean
If the room was deleted.
participants
object[]
The list of participants.
userID
string
The user ID.
xcUserID
string
The user ID from customer's server.
fullname
string
The user's full name.
string
The email address.
isEmailVerified
boolean
If the email address is verified.
countryID
integer
The user's country ID.
countryCallingCode
string
The country calling code for phone number.
phone
string
The phone number.
phoneWithCode
string
The phone number with country calling code.
isPhoneVerified
boolean
If the phone number is verified.
username
string
The username.
imageURL
object
The user's picture image URL.
thumbnail
string
Image URL for thumbnail picture.
fullsize
string
Image URL for fullsize picture.
userRole
object
The user role.
code
string
The user role code.
name
string
The user role name.
iconURL
string
The user role's icon URL.
lastLogin
long
The user's last login, in Unix milliseconds.
lastActivity
long
The user's last activity, in Unix milliseconds.
isOnline
boolean
If the user is currently online.
created
long
The time the user was created, in Unix milliseconds.
updated
long
The time the user was last updated, in Unix milliseconds.
Error 4xx
Name
Description
ParamValidationFailed
The parameter validation failed.
HeaderValidationFailed
The request header validation failed.
RoomNotFound
The room is not found
Remove Participants
Remove users from a chat room's participants.
Parameters
xcRoomID
string
The room ID from customer's server.
Size Range: 1..50
participantXCUserIDs
string[]
The list of participant IDs to be removed.
Success 200
room
object
The room's details.
roomID
string
Room ID.
xcRoomID
string
The room ID from customer's server.
name
string
The room's name.
type
integer
The room type.
imageURL
object
The room's picture image URL.
thumbnail
string
Image URL for thumbnail picture.
fullsize
string
Image URL for fullsize picture.
color
string
The room's color code, in hex.
isLocked
boolean
If the room was locked.
lockedTime
long
The time the room was locked, in Unix milliseconds.
deleted
long
The room's deleted time, in Unix milliseconds.
isDeleted
boolean
If the room was deleted.
participants
object[]
The list of participants.
userID
string
The user ID.
xcUserID
string
The user ID from customer's server.
fullname
string
The user's full name.
string
The email address.
isEmailVerified
boolean
If the email address is verified.
countryID
integer
The user's country ID.
countryCallingCode
string
The country calling code for phone number.
phone
string
The phone number.
phoneWithCode
string
The phone number with country calling code.
isPhoneVerified
boolean
If the phone number is verified.
username
string
The username.
imageURL
object
The user's picture image URL.
thumbnail
string
Image URL for thumbnail picture.
fullsize
string
Image URL for fullsize picture.
userRole
object
The user role.
code
string
The user role code.
name
string
The user role name.
iconURL
string
The user role's icon URL.
lastLogin
long
The user's last login, in Unix milliseconds.
lastActivity
long
The user's last activity, in Unix milliseconds.
isOnline
boolean
If the user is currently online.
created
long
The time the user was created, in Unix milliseconds.
updated
long
The time the user was last updated, in Unix milliseconds.
Error 4xx
Name
Description
ParamValidationFailed
The parameter validation failed.
HeaderValidationFailed
The request header validation failed.
RoomNotFound
The room is not found
Get List by User
Parameters
xcUserID
string
The user ID from customer's server whose rooms are to be retrieved.
xcRoomIDs (optional)
string[]
The room IDs from customer's server.
Success 200
rooms
object[]
The room list.
lastMessage
object
The last message in the room.
messageID
string
The message ID from server side.
localID
string
The message ID from client side.
type
integer
The message type.
body
string
The content of the message.
data
string
The actual data payload for custom message type, in JSON string.
filterID
string
The filter ID.
isHidden
boolean
If the message should be hidden.
quote
object
Quoted message.
title
string
The quoted message's title.
content
string
The quoted message's content.
imageURL
string
Quoted image URL, if any.
fileID
string
Quoted file ID, if any.
fileType
string
Quoted file type, if any.
replyTo
object
Info of the replied source message.
userID
string
User ID of the replied message's sender.
xcUserID
string
The user ID from customer's server.
fullname
string
Full name of the replied message's sender.
messageID
string
The replied message ID.
localID
string
The replied message's local ID.
messageType
integer
The replied message type.
forwardFrom
object
Info of the forwarded source message.
userID
string
User ID of the original message's sender.
xcUserID
string
The User ID from customer's server.
fullname
string
Full name of the original message's sender.
messageID
string
The original message ID.
localID
string
The original message's local ID.
room
object
The room's details.
roomID
string
Room ID.
xcRoomID
string
The room ID from customer's server.
name
string
The room's name (chat partner's full name for personal chat, or group name for group chat).
type
integer
The room type.
imageURL
object
The room's picture image URL.
thumbnail
string
Image URL for thumbnail picture.
fullsize
string
Image URL for fullsize picture.
color
string
The room's color code, in hex.
isLocked
boolean
If the room was locked.
lockedTime
long
The time the room was locked, in Unix milliseconds.
deleted
long
The room's deleted time, in Unix milliseconds.
isDeleted
boolean
If the room was deleted.
user
object
The sender user's profile.
userID
string
The user ID.
xcUserID
string
The user ID from customer's server.
fullname
string
The user's full name.
username
string
The username.
imageURL
object
The user's picture image URL.
thumbnail
string
Image URL for thumbnail picture.
fullsize
string
Image URL for fullsize picture.
userRole
object
The user role.
code
string
The user role code.
name
string
The user role name.
iconURL
string
The user role's icon URL.
lastLogin
long
The user's last login, in Unix milliseconds.
lastActivity
long
The user's last activity, in Unix milliseconds.
created
long
The time the user was created, in Unix milliseconds.
updated
long
The time the user was last updated, in Unix milliseconds.
deleted
long
The time the user was deleted, in Unix milliseconds.
recipientID
string
The recipient's user ID or group ID, depending on the room type.
action
string
The action for system message.
target
object
The target of the action for system message.
targetType
string
The target type (e.g.: "user").
targetID
string
The target's ID (user ID for target type "user").
targetXCID
string
The target's XC ID.
targetName
string
The target's name.
isSending
boolean
FALSE if the message was successfully sent to server, else TRUE.
isDelivered
boolean
If the message has been delivered to the recipient.
isRead
boolean
If the message has been read by the recipient.
isDeleted
boolean
If the message was deleted.
created
long
The message's created time.
updated
long
The message's last updated time.
deleted
long
The message's deleted time.
unreadCount
integer
Number of unread messages in the room.
Error 4xx
ParamValidationFailed
The parameter validation failed.
HeaderValidationFailed
The request header validation failed.
Lock Room
Parameters
xcRoomID
string
(101) The room ID from customer's server.
Size range: 1..50
xcUserID
string
(109) The XC user ID of the user locking the room.
Success 200
success
boolean
If the room is locked successfully.
message
string
The message.
Error 4xx
ParamValidationFailed
The parameter validation failed.
RoomNotFound
The XC room ID is not found.
HeaderValidationFailed
The request header validation failed.