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.

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

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

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

{
  "status": 400,
  "error": {
    "code": "40002",
    "message": "Param 'xcRoomID' is required",
    "field": "101"
  },
  "data": {}
}
{
  "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.

BASE_URL/v1/server/room/get

Parameter

Field
Type
Description

xcRoomID

string

(101) The room ID from customer's server.

Size range: 1..50

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

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

{
  "status": 400,
  "error": {
    "code": "40002",
    "message": "Param 'xcRoomID' is required",
    "field": "101"
  },
  "data": {}
}
{
  "status": 400,
  "error": {
    "code": "40001",
    "message": "Request headers are required (Server-Key)",
    "field": ""
  },
  "data": {}
}
{
  "status": 404,
  "error": {
    "code": "40401",
    "message": "Room is not found",
    "field": ""
  },
  "data": {}
}

Add Participants

Add participants to a chat room.

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.

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

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

{
  "status": 400,
  "error": {
    "code": "40002",
    "message": "Param 'xcRoomID' is required",
    "field": "101"
  },
  "data": {}
}
{
  "status": 400,
  "error": {
    "code": "40001",
    "message": "Request headers are required (Server-Key)",
    "field": ""
  },
  "data": {}
}
{
  "status": 404,
  "error": {
    "code": "40401",
    "message": "Room is not found",
    "field": ""
  },
  "data": {}
}

Remove Participants

Remove users from a chat room's participants.

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.

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

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

{
  "status": 400,
  "error": {
    "code": "40002",
    "message": "Param 'xcRoomID' is required",
    "field": "101"
  },
  "data": {}
}

Get List by User

BASE_URL/v1/server/room/get_list_by_user

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.

{
    "xcUserID": "6",
    "xcRoomIDs": [
        "6A02C41D"
    ]
}

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.

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.

HTTP/1.1 200 OK
{
  "status": 200,
  "error": {
    "code": "",
    "message": "",
    "field": ""
  },
  "data": {
    "rooms": [
      {
        "lastMessage": {
          "messageID": "1854919",
          "localID": "UW3nQh7XNwC9q2WVj9h7_xW4fIPEyqxa",
          "type": 1001,
          "body": "2UKeB3vSZJ0xkpSXzBpoEUrA==",
          "data": "",
          "filterID": "",
          "isHidden": false,
          "quote": {
            "title": "",
            "content": "",
            "imageURL": "",
            "fileID": "",
            "fileType": ""
          },
          "replyTo": {
            "userID": "0",
            "xcUserID": "",
            "fullname": "",
            "messageID": "0",
            "localID": "",
            "messageType": 0
          },
          "forwardFrom": {
            "userID": "0",
            "xcUserID": "",
            "fullname": "",
            "messageID": "0",
            "localID": ""
          },
          "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
          },
          "user": {
            "userID": "6",
            "xcUserID": "6",
            "fullname": "Jony Lim",
            "email": "jony@moselo.com",
            "isEmailVerified": false,
            "countryID": 0,
            "countryCallingCode": "",
            "phone": "628992816351",
            "phoneWithCode": "",
            "isPhoneVerified": false,
            "username": "jony",
            "imageURL": {
              "thumbnail": "https://s3-ap-southeast-1.amazonaws.com/taptalk-dev/images/jony_1542363733889t.jpg",
              "fullsize": "https://s3-ap-southeast-1.amazonaws.com/taptalk-dev/images/jony_1542363733889f.jpg"
            },
            "userRole": {
              "code": "developer",
              "name": "",
              "iconURL": ""
            },
            "lastLogin": 1592720960000,
            "lastActivity": 1593016069000,
            "isOnline": false,
            "created": 1537965673709,
            "updated": 1592717884647
          },
          "recipientID": "0",
          "action": "",
          "target": {
            "targetType": "",
            "targetID": "0",
            "targetXCID": "",
            "targetName": ""
          },
          "isSending": false,
          "isDelivered": false,
          "isRead": false,
          "isDeleted": false,
          "created": 1593062073595,
          "updated": 1593062073595
        },
        "unreadCount": 3
      }
    ]
  }
}

Error 4xx

Name
Description

ParamValidationFailed

The parameter validation failed.

HeaderValidationFailed

The request header validation failed.

HTTP/1.1 200 OK
{
  "status": 400,
  "error": {
    "code": "40002",
    "message": "Param 'xcUserID' is required",
    "field": "xcUserID"
  },
  "data": {}
}

Lock Room

BASE_URL/v1/server/room/lock

Parameters

Field
Type
Description

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.

{
    "xcRoomID": "6A02C41D",
    "xcUserID": "6"
}

Success 200

Field
Type
Description

success

boolean

If the room is locked successfully.

message

string

The message.

HTTP/1.1 200 OK
{
  "status": 200,
  "error": {
    "code": "",
    "message": "",
    "field": ""
  },
  "data": {
    "success": true,
    "message": "The room has been locked succesfully"
  }
}

Error 4xx

Name
Description

ParamValidationFailed

The parameter validation failed.

RoomNotFound

The XC room ID is not found.

HeaderValidationFailed

The request header validation failed.

HTTP/1.1 200 OK
{
  "status": 400,
  "error": {
    "code": "40002",
    "message": "Param 'xcUserID' is required",
    "field": "xcUserID"
  },
  "data": {}
}