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
1
BASE_URL/v1/server/room/create_or_update
Copied!
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
1
{
2
"xcRoomID": "6A02C41D",
3
"type": 2,
4
"name": "Order #6A02C41D",
5
"photoThumbnailURL": "http://www.example.com/photo/thumb/6a02c41d6.jpg",
6
"photoFullsizeURL": "http://www.example.com/photo/full/6a02c41d6.jpg",
7
"participantXCUserIDs": [
8
"6"
9
],
10
"participantUserRoles": [
11
"agent:1"
12
],
13
"tags": [
14
"category:1"
15
]
16
}
Copied!
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.
Success Response
1
{
2
"status": 200,
3
"error": {
4
"code": "",
5
"message": "",
6
"field": ""
7
},
8
"data": {
9
"room": {
10
"roomID": "g456",
11
"xcRoomID": "6A02C41D",
12
"name": "Order #6A02C41D",
13
"type": 2,
14
"imageURL": {
15
"thumbnail": "http://www.example.com/photo/thumb/6a02c41d6.jpg",
16
"fullsize": "http://www.example.com/photo/full/6a02c41d6.jpg",
17
},
18
"color": "",
19
"isLocked": false,
20
"lockedTime": 0,
21
"deleted": 0,
22
"isDeleted": false
23
},,
24
"participants": [
25
{
26
"userID": "6",
27
"xcUserID": "6",
28
"fullname": "Jony Lim",
29
"email": "",
30
"isEmailVerified": false,
31
"countryID": 1,
32
"countryCallingCode": "",
33
"phone": "",
34
"phoneWithCode": "",
35
"isPhoneVerified": false,
36
"username": "jony",
37
"imageURL": {
38
"thumbnail": "",
39
"fullsize": ""
40
},
41
"userRole": {
42
"code": "",
43
"name": "",
44
"iconURL": ""
45
},
46
"lastLogin": 1538303501000,
47
"lastActivity": 1538308225000,
48
"isOnline": false,
49
"created": 1537965673709,
50
"updated": 1538304466005
51
},
52
...
53
]
54
}
55
}
Copied!
Error 4xx
Name
Description
ParamValidationFailed
The parameter validation failed.
HeaderValidationFailed
The request header validation failed.
ParamValidationFailed
1
{
2
"status": 400,
3
"error": {
4
"code": "40002",
5
"message": "Param 'xcRoomID' is required",
6
"field": "101"
7
},
8
"data": {}
9
}
Copied!
HeaderValidationFailed
1
{
2
"status": 400,
3
"error": {
4
"code": "40001",
5
"message": "Request headers are required (Server-Key)",
6
"field": ""
7
},
8
"data": {}
9
}
Copied!

Get Room Details

Get a chat room's details and participants.
POST
1
BASE_URL/v1/server/room/get
Copied!
Parameter
Field
Type
Description
xcRoomID
string
(101) The room ID from customer's server.
Size range: 1..50
Request Example
1
{
2
"xcRoomID": "6A02C41D"
3
}
Copied!
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.
Success Response
1
{
2
"status": 200,
3
"error": {
4
"code": "",
5
"message": "",
6
"field": ""
7
},
8
"data": {
9
"room": {
10
"roomID": "g456",
11
"xcRoomID": "6A02C41D",
12
"name": "Order #6A02C41D",
13
"type": 2,
14
"imageURL": {
15
"thumbnail": "http://www.example.com/photo/thumb/6a02c41d6.jpg",
16
"fullsize": "http://www.example.com/photo/full/6a02c41d6.jpg",
17
},
18
"color": "",
19
"isLocked": false,
20
"lockedTime": 0,
21
"deleted": 0,
22
"isDeleted": false
23
},,
24
"participants": [
25
{
26
"userID": "6",
27
"xcUserID": "6",
28
"fullname": "Jony Lim",
29
"email": "",
30
"isEmailVerified": false,
31
"countryID": 1,
32
"countryCallingCode": "",
33
"phone": "",
34
"phoneWithCode": "",
35
"isPhoneVerified": false,
36
"username": "jony",
37
"imageURL": {
38
"thumbnail": "",
39
"fullsize": ""
40
},
41
"userRole": {
42
"code": "",
43
"name": "",
44
"iconURL": ""
45
},
46
"lastLogin": 1538303501000,
47
"lastActivity": 1538308225000,
48
"isOnline": false,
49
"created": 1537965673709,
50
"updated": 1538304466005
51
},
52
...
53
]
54
}
55
}
Copied!
Error 4xx
Name
Description
ParamValidationFailed
The parameter validation failed.
HeaderValidationFailed
The request header validation failed.
RoomNotFound
The room is not found
ParamValidationFailed
1
{
2
"status": 400,
3
"error": {
4
"code": "40002",
5
"message": "Param 'xcRoomID' is required",
6
"field": "101"
7
},
8
"data": {}
9
}
Copied!
HeaderValidationFailed
1
{
2
"status": 400,
3
"error": {
4
"code": "40001",
5
"message": "Request headers are required (Server-Key)",
6
"field": ""
7
},
8
"data": {}
9
}
Copied!
RoomNotFound
1
{
2
"status": 404,
3
"error": {
4
"code": "40401",
5
"message": "Room is not found",
6
"field": ""
7
},
8
"data": {}
9
}
Copied!

Add Participants

Add participants to a chat room.
POST
1
BASE_URL/v1/server/room/participants/add
Copied!
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
1
{
2
"xcRoomID": "6A02C41D",
3
"participantXCUserIDs": [
4
"6"
5
]
6
}
Copied!
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.
Success Response
1
{
2
"status": 200,
3
"error": {
4
"code": "",
5
"message": "",
6
"field": ""
7
},
8
"data": {
9
"room": {
10
"roomID": "g456",
11
"xcRoomID": "6A02C41D",
12
"name": "Order #6A02C41D",
13
"type": 2,
14
"imageURL": {
15
"thumbnail": "http://www.example.com/photo/thumb/6a02c41d6.jpg",
16
"fullsize": "http://www.example.com/photo/full/6a02c41d6.jpg",
17
},
18
"color": "",
19
"isLocked": false,
20
"lockedTime": 0,
21
"deleted": 0,
22
"isDeleted": false
23
},,
24
"participants": [
25
{
26
"userID": "6",
27
"xcUserID": "6",
28
"fullname": "Jony Lim",
29
"email": "",
30
"isEmailVerified": false,
31
"countryID": 1,
32
"countryCallingCode": "",
33
"phone": "",
34
"phoneWithCode": "",
35
"isPhoneVerified": false,
36
"username": "jony",
37
"imageURL": {
38
"thumbnail": "",
39
"fullsize": ""
40
},
41
"userRole": {
42
"code": "",
43
"name": "",
44
"iconURL": ""
45
},
46
"lastLogin": 1538303501000,
47
"lastActivity": 1538308225000,
48
"isOnline": false,
49
"created": 1537965673709,
50
"updated": 1538304466005
51
},
52
...
53
]
54
}
55
}
Copied!
Error 4xx
Name
Description
ParamValidationFailed
The parameter validation failed.
HeaderValidationFailed
The request header validation failed.
RoomNotFound
The room is not found
ParamValidationFailed
1
{
2
"status": 400,
3
"error": {
4
"code": "40002",
5
"message": "Param 'xcRoomID' is required",
6
"field": "101"
7
},
8
"data": {}
9
}
Copied!
HeaderValidationFailed
1
{
2
"status": 400,
3
"error": {
4
"code": "40001",
5
"message": "Request headers are required (Server-Key)",
6
"field": ""
7
},
8
"data": {}
9
}
Copied!
RoomNotFound
1
{
2
"status": 404,
3
"error": {
4
"code": "40401",
5
"message": "Room is not found",
6
"field": ""
7
},
8
"data": {}
9
}
Copied!

Remove Participants

Remove users from a chat room's participants.
POST
1
BASE_URL/v1/server/room/participants/remove
Copied!
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
1
{
2
"xcRoomID": "6A02C41D",
3
"participantXCUserIDs": [
4
"6"
5
]
6
}
Copied!
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.
Success Response
1
{
2
"status": 200,
3
"error": {
4
"code": "",
5
"message": "",
6
"field": ""
7
},
8
"data": {
9
"room": {
10
"roomID": "g456",
11
"xcRoomID": "6A02C41D",
12
"name": "Order #6A02C41D",
13
"type": 2,
14
"imageURL": {
15
"thumbnail": "http://www.example.com/photo/thumb/6a02c41d6.jpg",
16
"fullsize": "http://www.example.com/photo/full/6a02c41d6.jpg",
17
},
18
"color": "",
19
"isLocked": false,
20
"lockedTime": 0,
21
"deleted": 0,
22
"isDeleted": false
23
},,
24
"participants": [
25
{
26
"userID": "6",
27
"xcUserID": "6",
28
"fullname": "Jony Lim",
29
"email": "",
30
"isEmailVerified": false,
31
"countryID": 1,
32
"countryCallingCode": "",
33
"phone": "",
34
"phoneWithCode": "",
35
"isPhoneVerified": false,
36
"username": "jony",
37
"imageURL": {
38
"thumbnail": "",
39
"fullsize": ""
40
},
41
"userRole": {
42
"code": "",
43
"name": "",
44
"iconURL": ""
45
},
46
"lastLogin": 1538303501000,
47
"lastActivity": 1538308225000,
48
"isOnline": false,
49
"created": 1537965673709,
50
"updated": 1538304466005
51
},
52
...
53
]
54
}
55
}
Copied!
Error 4xx
Name
Description
ParamValidationFailed
The parameter validation failed.
HeaderValidationFailed
The request header validation failed.
RoomNotFound
The room is not found
ParamValidationFailed
HeaderValidationFailed
RoomNotFound
1
{
2
"status": 400,
3
"error": {
4
"code": "40002",
5
"message": "Param 'xcRoomID' is required",
6
"field": "101"
7
},
8
"data": {}
9
}
Copied!
1
{
2
"status": 400,
3
"error": {
4
"code": "40001",
5
"message": "Request headers are required (Server-Key)",
6
"field": ""
7
},
8
"data": {}
9
}
Copied!
1
{
2
"status": 404,
3
"error": {
4
"code": "40401",
5
"message": "Room is not found",
6
"field": ""
7
},
8
"data": {}
9
}
Copied!

Get List by User

1
BASE_URL/v1/server/room/get_list_by_user
Copied!
Parameters
Field
Type
Description
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.
Request Sample
1
{
2
"xcUserID": "6",
3
"xcRoomIDs": [
4
"6A02C41D"
5
]
6
}
Copied!
Success 200
Field
Type
Description
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.
Response Sample
1
HTTP/1.1 200 OK
2
{
3
"status": 200,
4
"error": {
5
"code": "",
6
"message": "",
7
"field": ""
8
},
9
"data": {
10
"rooms": [
11
{
12
"lastMessage": {
13
"messageID": "1854919",
14
"localID": "UW3nQh7XNwC9q2WVj9h7_xW4fIPEyqxa",
15
"type": 1001,
16
"body": "2UKeB3vSZJ0xkpSXzBpoEUrA==",
17
"data": "",
18
"filterID": "",
19
"isHidden": false,
20
"quote": {
21
"title": "",
22
"content": "",
23
"imageURL": "",
24
"fileID": "",
25
"fileType": ""
26
},
27
"replyTo": {
28
"userID": "0",
29
"xcUserID": "",
30
"fullname": "",
31
"messageID": "0",
32
"localID": "",
33
"messageType": 0
34
},
35
"forwardFrom": {
36
"userID": "0",
37
"xcUserID": "",
38
"fullname": "",
39
"messageID": "0",
40
"localID": ""
41
},
42
"room": {
43
"roomID": "g456",
44
"xcRoomID": "6A02C41D",
45
"name": "Order #6A02C41D",
46
"type": 2,
47
"imageURL": {
48
"thumbnail": "http://www.example.com/photo/thumb/6a02c41d6.jpg",
49
"fullsize": "http://www.example.com/photo/full/6a02c41d6.jpg",
50
},
51
"color": "",
52
"isLocked": false,
53
"lockedTime": 0,
54
"deleted": 0,
55
"isDeleted": false
56
},
57
"user": {
58
"userID": "6",
59
"xcUserID": "6",
60
"fullname": "Jony Lim",
61
"email": "[email protected]",
62
"isEmailVerified": false,
63
"countryID": 0,
64
"countryCallingCode": "",
65
"phone": "628992816351",
66
"phoneWithCode": "",
67
"isPhoneVerified": false,
68
"username": "jony",
69
"imageURL": {
70
"thumbnail": "https://s3-ap-southeast-1.amazonaws.com/taptalk-dev/images/jony_1542363733889t.jpg",
71
"fullsize": "https://s3-ap-southeast-1.amazonaws.com/taptalk-dev/images/jony_1542363733889f.jpg"
72
},
73
"userRole": {
74
"code": "developer",
75
"name": "",
76
"iconURL": ""
77
},
78
"lastLogin": 1592720960000,
79
"lastActivity": 1593016069000,
80
"isOnline": false,
81
"created": 1537965673709,
82
"updated": 1592717884647
83
},
84
"recipientID": "0",
85
"action": "",
86
"target": {
87
"targetType": "",
88
"targetID": "0",
89
"targetXCID": "",
90
"targetName": ""
91
},
92
"isSending": false,
93
"isDelivered": false,
94
"isRead": false,
95
"isDeleted": false,
96
"created": 1593062073595,
97
"updated": 1593062073595
98
},
99
"unreadCount": 3
100
}
101
]
102
}
103
}
Copied!
Error 4xx
Name
Description
ParamValidationFailed
The parameter validation failed.
HeaderValidationFailed
The request header validation failed.
ParamValidationFailed
HeaderValidationFailed
1
HTTP/1.1 200 OK
2
{
3
"status": 400,
4
"error": {
5
"code": "40002",
6
"message": "Param 'xcUserID' is required",
7
"field": "xcUserID"
8
},
9
"data": {}
10
}
Copied!
1
HTTP/1.1 200 OK
2
{
3
"status": 400,
4
"error": {
5
"code": "40001",
6
"message": "Request headers are required (Server-Key)",
7
"field": ""
8
},
9
"data": {}