> For the complete documentation index, see [llms.txt](https://docs.taptalk.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.taptalk.io/powertalk-chat-sdk-documentation/powertalk-server-api/room.md).

# 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@taptalk.io",
            "isEmailVerified": false,
            "countryID": 0,
            "countryCallingCode": "",
            "phone": "628123456789",
            "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 %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.taptalk.io/powertalk-chat-sdk-documentation/powertalk-server-api/room.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.