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.
POST
BASE_URL/v1/server/room/create_or_update
Parameters
Field
Type
Description
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
Request Example
{
"xcRoomID": "6A02C41D",
"type": 2,
"name": "Order #6A02C41D",
"photoThumbnailURL": "http://www.example.com/photo/thumb/6a02c41d6.jpg",
"photoFullsizeURL": "http://www.example.com/photo/full/6a02c41d6.jpg",
"participantXCUserIDs": [
"6"
],
"participantUserRoles": [
"agent:1"
],
"tags": [
"category:1"
]
}
Success 200
Field
Type
Description
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.
email
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.
Success Response
{
"status": 200,
"error": {
"code": "",
"message": "",
"field": ""
},
"data": {
"room": {
"roomID": "g456",
"xcRoomID": "6A02C41D",
"name": "Order #6A02C41D",
"type": 2,
"imageURL": {
"thumbnail": "http://www.example.com/photo/thumb/6a02c41d6.jpg",
"fullsize": "http://www.example.com/photo/full/6a02c41d6.jpg",
},
"color": "",
"isLocked": false,
"lockedTime": 0,
"deleted": 0,
"isDeleted": false
},,
"participants": [
{
"userID": "6",
"xcUserID": "6",
"fullname": "Jony Lim",
"email": "",
"isEmailVerified": false,
"countryID": 1,
"countryCallingCode": "",
"phone": "",
"phoneWithCode": "",
"isPhoneVerified": false,
"username": "jony",
"imageURL": {
"thumbnail": "",
"fullsize": ""
},
"userRole": {
"code": "",
"name": "",
"iconURL": ""
},
"lastLogin": 1538303501000,
"lastActivity": 1538308225000,
"isOnline": false,
"created": 1537965673709,
"updated": 1538304466005
},
...
]
}
}
Error 4xx
Name
Description
ParamValidationFailed
The parameter validation failed.
HeaderValidationFailed
The request header validation failed.
ParamValidationFailed
{
"status": 400,
"error": {
"code": "40002",
"message": "Param 'xcRoomID' is required",
"field": "101"
},
"data": {}
}
HeaderValidationFailed
{
"status": 400,
"error": {
"code": "40001",
"message": "Request headers are required (Server-Key)",
"field": ""
},
"data": {}
}

Get Room Details

Get a chat room's details and participants.
POST
BASE_URL/v1/server/room/get
Parameter
Field
Type
Description
xcRoomID
string
(101) The room ID from customer's server.
Size range: 1..50
Request Example
{
"xcRoomID": "6A02C41D"
}
Success 200
Field
Type
Description
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.
email
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.
Success Response
{
"status": 200,
"error": {
"code": "",
"message": "",
"field": ""
},
"data": {
"room": {
"roomID": "g456",
"xcRoomID": "6A02C41D",
"name": "Order #6A02C41D",
"type": 2,
"imageURL": {
"thumbnail": "http://www.example.com/photo/thumb/6a02c41d6.jpg",
"fullsize": "http://www.example.com/photo/full/6a02c41d6.jpg",
},
"color": "",
"isLocked": false,
"lockedTime": 0,
"deleted": 0,
"isDeleted": false
},,
"participants": [
{
"userID": "6",
"xcUserID": "6",
"fullname": "Jony Lim",
"email": "",
"isEmailVerified": false,
"countryID": 1,
"countryCallingCode": "",
"phone": "",
"phoneWithCode": "",
"isPhoneVerified": false,
"username": "jony",
"imageURL": {
"thumbnail": "",
"fullsize": ""
},
"userRole": {
"code": "",
"name": "",
"iconURL": ""
},
"lastLogin": 1538303501000,
"lastActivity": 1538308225000,
"isOnline": false,
"created": 1537965673709,
"updated": 1538304466005
},
...
]
}
}
Error 4xx
Name
Description
ParamValidationFailed
The parameter validation failed.
HeaderValidationFailed
The request header validation failed.
RoomNotFound
The room is not found
ParamValidationFailed
{
"status": 400,
"error": {
"code": "40002",
"message": "Param 'xcRoomID' is required",
"field": "101"
},
"data": {}
}
HeaderValidationFailed
{
"status": 400,
"error": {
"code": "40001",
"message": "Request headers are required (Server-Key)",
"field": ""
},
"data": {}
}
RoomNotFound
{
"status": 404,
"error": {
"code": "40401",
"message": "Room is not found",
"field": ""
},
"data": {}
}

Add Participants

Add participants to a chat room.
POST
BASE_URL/v1/server/room/participants/add
Parameters
Field
Type
Description
xcRoomID
string
(101) The room ID from customer's server.
Size range: 1..50
participantXCUserIDs
string[]
(107) The list of participants.
Request Example
{
"xcRoomID": "6A02C41D",
"participantXCUserIDs": [
"6"
]
}
Success 200
Field
Type
Description
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.
email
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.
Success Response
{
"status": 200,
"error": {
"code": "",
"message": "",
"field": ""
},
"data": {
"room": {
"roomID": "g456",
"xcRoomID": "6A02C41D",
"name": "Order #6A02C41D",
"type": 2,
"imageURL": {
"thumbnail": "http://www.example.com/photo/thumb/6a02c41d6.jpg",
"fullsize": "http://www.example.com/photo/full/6a02c41d6.jpg",
},
"color": "",
"isLocked": false,
"lockedTime": 0,
"deleted": 0,
"isDeleted": false
},,
"participants": [
{
"userID": "6",
"xcUserID": "6",
"fullname": "Jony Lim",
"email": "",
"isEmailVerified": false,
"countryID": 1,
"countryCallingCode": "",
"phone": "",
"phoneWithCode": "",
"isPhoneVerified": false,
"username": "jony",
"imageURL": {
"thumbnail": "",
"fullsize": ""
},
"userRole": {
"code": "",
"name": "",
"iconURL": ""
},
"lastLogin": 1538303501000,
"lastActivity": 1538308225000,
"isOnline": false,
"created": 1537965673709,
"updated": 1538304466005
},
...
]
}
}
Error 4xx
Name
Description
ParamValidationFailed
The parameter validation failed.
HeaderValidationFailed
The request header validation failed.
RoomNotFound
The room is not found
ParamValidationFailed
{
"status": 400,
"error": {
"code": "40002",
"message": "Param 'xcRoomID' is required",
"field": "101"
},
"data": {}
}
HeaderValidationFailed
{
"status": 400,
"error": {
"code": "40001",
"message": "Request headers are required (Server-Key)",
"field": ""
},
"data": {}
}
RoomNotFound
{
"status": 404,
"error": {
"code": "40401",
"message": "Room is not found",
"field": ""
},
"data": {}
}

Remove Participants

Remove users from a chat room's participants.
POST
BASE_URL/v1/server/room/participants/remove
Parameters
Field
Type
Description
xcRoomID
string
The room ID from customer's server. Size Range: 1..50
participantXCUserIDs
string[]
The list of participant IDs to be removed.
Request Example
{
"xcRoomID": "6A02C41D",
"participantXCUserIDs": [
"6"
]
}
Success 200
Field
Type
Description
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.
email
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.