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 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 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"