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

{% hint style="warning" %}
**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.
{% endhint %}

{% tabs %}
{% tab title="POST" %}

```php
BASE_URL/v1/server/room/create_or_update
```

{% endtab %}
{% endtabs %}

**Parameters**

| Field                                      | Type      | Description                                                                           |
| ------------------------------------------ | --------- | ------------------------------------------------------------------------------------- |
| xcRoomID                                   | string    | <p>(101) The room ID from customer's server.</p><p>Size range: <code>1..50</code></p> |
| type                                       | integer   | (102) The room type                                                                   |
| name                                       | string    | (103) The room name                                                                   |
| <p>photoThumbnailURL<br>(optional)</p>     | string    | (104) The room's thumbnail picture image URL                                          |
| <p>photoFullsizeURL<br>(optional)</p>      | string    | (105) The room's fullsize picture image URL                                           |
| <p>tags<br>(optional)</p>                  | string\[] | (106) The room's tags                                                                 |
| <p>participantXCUserIDs<br>(optional)</p>  | string\[] | (107) The list of participants, for new room only                                     |
| <p>participantUserRoles <br>(optional)</p> | string\[] | (108) The list of user roles to be considered as participants                         |

{% tabs %}
{% tab title="Request Example" %}

```javascript
{
    "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"
    ]
}
```

{% endtab %}
{% endtabs %}

**Success 200**

<table><thead><tr><th width="190.3175965665236">Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>room</td><td>object</td><td>The room's details.</td></tr><tr><td>  roomID</td><td>string</td><td>Room ID.</td></tr><tr><td>  xcRoomID</td><td>string</td><td>The room ID from customer's server.</td></tr><tr><td>  name</td><td>string</td><td>The room's name.</td></tr><tr><td>  type</td><td>integer</td><td>The room type.</td></tr><tr><td>  imageURL</td><td>object</td><td>The room's picture image URL.</td></tr><tr><td>    thumbnail</td><td>string</td><td>Image URL for thumbnail picture.</td></tr><tr><td>    fullsize</td><td>string</td><td>Image URL for fullsize picture.</td></tr><tr><td>  color</td><td>string</td><td>The room's color code, in hex.</td></tr><tr><td>  isLocked</td><td>boolean</td><td>If the room was locked.</td></tr><tr><td>  lockedTime</td><td>long</td><td>The time the room was locked, in Unix milliseconds.</td></tr><tr><td>  deleted</td><td>long</td><td>The room's deleted time, in Unix milliseconds.</td></tr><tr><td>  isDeleted</td><td>boolean</td><td>If the room was deleted.</td></tr><tr><td>participants</td><td>object[]</td><td>The list of participants.</td></tr><tr><td>  userID</td><td>string</td><td>The user ID.</td></tr><tr><td>  xcUserID</td><td>string</td><td>The user ID from customer's server.</td></tr><tr><td>  fullname</td><td>string</td><td>The user's full name.</td></tr><tr><td>  email</td><td>string</td><td>The email address.</td></tr><tr><td>  isEmailVerified</td><td>boolean</td><td>If the email address is verified.</td></tr><tr><td>  countryID</td><td>integer</td><td>The user's country ID.</td></tr><tr><td>  countryCallingCode</td><td>string</td><td>The country calling code for phone number.</td></tr><tr><td>  phone</td><td>string</td><td>The phone number.</td></tr><tr><td>  phoneWithCode</td><td>string</td><td>The phone number with country calling code.</td></tr><tr><td>  isPhoneVerified</td><td>boolean</td><td>If the phone number is verified.</td></tr><tr><td>  username</td><td>string</td><td>The username.</td></tr><tr><td>  imageURL</td><td>object</td><td>The user's picture image URL.</td></tr><tr><td>    thumbnail</td><td>string</td><td>Image URL for thumbnail picture.</td></tr><tr><td>    fullsize</td><td>string</td><td>Image URL for fullsize picture.</td></tr><tr><td>  userRole</td><td>object</td><td>The user role.</td></tr><tr><td>    code</td><td>string</td><td>The user role code.</td></tr><tr><td>    name</td><td>string</td><td>The user role name.</td></tr><tr><td>    iconURL</td><td>string</td><td>The user role's icon URL.</td></tr><tr><td>  lastLogin</td><td>long</td><td>The user's last login, in Unix milliseconds.</td></tr><tr><td>  lastActivity</td><td>long</td><td>The user's last activity, in Unix milliseconds.</td></tr><tr><td>  isOnline</td><td>boolean</td><td>If the user is currently online.</td></tr><tr><td>  created</td><td>long</td><td>The time the user was created, in Unix milliseconds.</td></tr><tr><td>  updated</td><td>long</td><td>The time the user was last updated, in Unix milliseconds.</td></tr><tr><td>adminUserIDs</td><td>string[]</td><td>The list of admins' user IDs.</td></tr></tbody></table>

{% tabs %}
{% tab title="Success Response" %}

```javascript
{
  "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
      },
      ...
    ]
  }
}
```

{% endtab %}
{% endtabs %}

**Error 4xx**

| **Name**               | **Description**                       |
| ---------------------- | ------------------------------------- |
| ParamValidationFailed  | The parameter validation failed.      |
| HeaderValidationFailed | The request header validation failed. |

{% tabs %}
{% tab title="ParamValidationFailed" %}

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

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="HeaderValidationFailed" %}

```javascript
{
  "status": 400,
  "error": {
    "code": "40001",
    "message": "Request headers are required (Server-Key)",
    "field": ""
  },
  "data": {}
}
```

{% endtab %}
{% endtabs %}

### Get Room Details

Get a chat room's details and participants.

{% tabs %}
{% tab title="POST" %}

```php
BASE_URL/v1/server/room/get
```

{% endtab %}
{% endtabs %}

**Parameter**

| Field    | Type   | Description                                                                               |
| -------- | ------ | ----------------------------------------------------------------------------------------- |
| xcRoomID | string | <p>(101) The room ID from customer's server.</p><p>Size range: <code>1..50</code><br></p> |

{% tabs %}
{% tab title="Request Example" %}

```javascript
{
    "xcRoomID": "6A02C41D"
}
```

{% endtab %}
{% endtabs %}

**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.                             |

{% tabs %}
{% tab title="Success Response" %}

```javascript
{
  "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
      },
      ...
    ]
  }
}
```

{% endtab %}
{% endtabs %}

**Error 4xx**

| **Name**               | **Description**                       |
| ---------------------- | ------------------------------------- |
| ParamValidationFailed  | The parameter validation failed.      |
| HeaderValidationFailed | The request header validation failed. |
| RoomNotFound           | The room is not found                 |

{% tabs %}
{% tab title="ParamValidationFailed" %}

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

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="HeaderValidationFailed" %}

```javascript
{
  "status": 400,
  "error": {
    "code": "40001",
    "message": "Request headers are required (Server-Key)",
    "field": ""
  },
  "data": {}
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="RoomNotFound" %}

```javascript
{
  "status": 404,
  "error": {
    "code": "40401",
    "message": "Room is not found",
    "field": ""
  },
  "data": {}
}
```

{% endtab %}
{% endtabs %}

### Add Participants&#x20;

Add participants to a chat room.

{% tabs %}
{% tab title="POST" %}

```php
BASE_URL/v1/server/room/participants/add
```

{% endtab %}
{% endtabs %}

**Parameters**

| Field                | Type      | Description                                                                           |
| -------------------- | --------- | ------------------------------------------------------------------------------------- |
| xcRoomID             | string    | <p>(101) The room ID from customer's server.</p><p>Size range: <code>1..50</code></p> |
| participantXCUserIDs | string\[] | (107) The list of participants.                                                       |

{% tabs %}
{% tab title="Request Example" %}

```javascript
{
    "xcRoomID": "6A02C41D",
    "participantXCUserIDs": [
        "6"
    ]
}
```

{% endtab %}
{% endtabs %}

**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. |

{% tabs %}
{% tab title="Success Response" %}

```javascript
{
  "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
      },
      ...
    ]
  }
}
```

{% endtab %}
{% endtabs %}

**Error 4xx**

| **Name**               | **Description**                       |
| ---------------------- | ------------------------------------- |
| ParamValidationFailed  | The parameter validation failed.      |
| HeaderValidationFailed | The request header validation failed. |
| RoomNotFound           | The room is not found                 |

{% tabs %}
{% tab title="ParamValidationFailed" %}

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

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="HeaderValidationFailed" %}

```javascript
{
  "status": 400,
  "error": {
    "code": "40001",
    "message": "Request headers are required (Server-Key)",
    "field": ""
  },
  "data": {}
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="RoomNotFound" %}

```javascript
{
  "status": 404,
  "error": {
    "code": "40401",
    "message": "Room is not found",
    "field": ""
  },
  "data": {}
}
```

{% endtab %}
{% endtabs %}

### Remove Participants

Remove users from a chat room's participants.

{% tabs %}
{% tab title="POST" %}

```
BASE_URL/v1/server/room/participants/remove
```

{% endtab %}
{% endtabs %}

**Parameters**

| Field                | Type      | Description                                                                  |
| -------------------- | --------- | ---------------------------------------------------------------------------- |
| xcRoomID             | string    | <p>The room ID from customer's server.<br>Size Range: <code>1..50</code></p> |
| participantXCUserIDs | string\[] | The list of participant IDs to be removed.                                   |

{% tabs %}
{% tab title="Request Example" %}

```json
{
    "xcRoomID": "6A02C41D",
    "participantXCUserIDs": [
        "6"
    ]
}
```

{% endtab %}
{% endtabs %}

**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. |

{% tabs %}
{% tab title="Success Response" %}

```json
{
  "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
      },
      ...
    ]
  }
}
```

{% endtab %}
{% endtabs %}

**Error 4xx**

| **Name**               | **Description**                       |
| ---------------------- | ------------------------------------- |
| ParamValidationFailed  | The parameter validation failed.      |
| HeaderValidationFailed | The request header validation failed. |
| RoomNotFound           | The room is not found                 |

{% tabs %}
{% tab title="ParamValidationFailed" %}

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

{% endtab %}

{% tab title="HeaderValidationFailed" %}

```json
{
  "status": 400,
  "error": {
    "code": "40001",
    "message": "Request headers are required (Server-Key)",
    "field": ""
  },
  "data": {}
}
```

{% endtab %}

{% tab title="RoomNotFound" %}

```json
{
  "status": 404,
  "error": {
    "code": "40401",
    "message": "Room is not found",
    "field": ""
  },
  "data": {}
}
```

{% endtab %}
{% endtabs %}

### Get List by User

```http
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.                                |

{% tabs %}
{% tab title="Request Sample" %}

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

{% endtab %}
{% endtabs %}

**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.                                                      |

{% tabs %}
{% tab title="Response Sample" %}

```c
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
      }
    ]
  }
}
```

{% endtab %}
{% endtabs %}

**Error 4xx**

| Name                   | Description                           |
| ---------------------- | ------------------------------------- |
| ParamValidationFailed  | The parameter validation failed.      |
| HeaderValidationFailed | The request header validation failed. |

{% tabs %}
{% tab title="ParamValidationFailed" %}

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

{% endtab %}

{% tab title="HeaderValidationFailed	" %}

```c
HTTP/1.1 200 OK
{
  "status": 400,
  "error": {
    "code": "40001",
    "message": "Request headers are required (Server-Key)",
    "field": ""
  },
  "data": {}
}
```

{% endtab %}
{% endtabs %}

### Lock Room

```http
BASE_URL/v1/server/room/lock
```

**Parameters**

<table><thead><tr><th width="206.66666666666666">Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>xcRoomID</td><td>string</td><td><p>(101) The room ID from customer's server.</p><p>Size range: <code>1..50</code></p></td></tr><tr><td>xcUserID</td><td>string</td><td>(109) The XC user ID of the user locking the room.</td></tr></tbody></table>

{% tabs %}
{% tab title="Request Sample" %}

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

{% endtab %}
{% endtabs %}

**Success 200**

| Field   | Type    | Description                         |
| ------- | ------- | ----------------------------------- |
| success | boolean | If the room is locked successfully. |
| message | string  | The message.                        |

{% tabs %}
{% tab title="Success Response:" %}

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

```

{% endtab %}

{% tab title="Already Locked:	" %}

```c
HTTP/1.1 200 OK
{
  "status": 200,
  "error": {
    "code": "",
    "message": "",
    "field": ""
  },
  "data": {
    "success": false,
    "message": "The room is already locked"
  }
}

```

{% endtab %}
{% endtabs %}

**Error 4xx**

| Name                   | Description                           |
| ---------------------- | ------------------------------------- |
| ParamValidationFailed  | The parameter validation failed.      |
| RoomNotFound           | The XC room ID is not found.          |
| HeaderValidationFailed | The request header validation failed. |

{% tabs %}
{% tab title="ParamValidationFailed" %}

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

{% endtab %}

{% tab title="RoomNotFound" %}

```json
HTTP/1.1 200 OK
{
  "status": 404,
  "error": {
    "code": "40401",
    "message": "Room is not found",
    "field": ""
  },
  "data": {}
}
```

{% endtab %}

{% tab title="HeaderValidationFailed	" %}

```c
HTTP/1.1 200 OK
{
  "status": 400,
  "error": {
    "code": "40001",
    "message": "Request headers are required (Server-Key)",
    "field": ""
  },
  "data": {}
}
```

{% endtab %}
{% endtabs %}

### **Unl**ock Room

```http
BASE_URL/v1/server/room/unlock
```

**Parameters**

<table><thead><tr><th width="206.66666666666666">Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>xcRoomID</td><td>string</td><td><p>(101) The room ID from customer's server.</p><p>Size range: <code>1..50</code></p></td></tr><tr><td>xcUserID</td><td>string</td><td>(109) The XC user ID of the user unlocking the room.</td></tr></tbody></table>

{% tabs %}
{% tab title="Request Sample" %}

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

{% endtab %}
{% endtabs %}

**Success 200**

| Field   | Type    | Description                         |
| ------- | ------- | ----------------------------------- |
| success | boolean | If the room is locked successfully. |
| message | string  | The message.                        |

{% tabs %}
{% tab title="Success Response:" %}

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

```

{% endtab %}

{% tab title="Already Unlocked:	" %}

```c
HTTP/1.1 200 OK
{
  "status": 200,
  "error": {
    "code": "",
    "message": "",
    "field": ""
  },
  "data": {
    "success": false,
    "message": "The room is already unlocked"
  }
}

```

{% endtab %}
{% endtabs %}

**Error 4xx**

| Name                   | Description                           |
| ---------------------- | ------------------------------------- |
| ParamValidationFailed  | The parameter validation failed.      |
| RoomNotFound           | The XC room ID is not found.          |
| HeaderValidationFailed | The request header validation failed. |

{% tabs %}
{% tab title="ParamValidationFailed" %}

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

{% endtab %}

{% tab title="RoomNotFound" %}

```json
HTTP/1.1 200 OK
{
  "status": 404,
  "error": {
    "code": "40401",
    "message": "Room is not found",
    "field": ""
  },
  "data": {}
}
```

{% endtab %}

{% tab title="HeaderValidationFailed	" %}

```c
HTTP/1.1 200 OK
{
  "status": 400,
  "error": {
    "code": "40001",
    "message": "Request headers are required (Server-Key)",
    "field": ""
  },
  "data": {}
}
```

{% endtab %}
{% endtabs %}