4 Chat Room Endpoint

In Chat Room you can add additional information called options that is automatically synchronized by each participant in the conversation. It is important that the amount of data stored in options is kept to a minimum to ensure the quickest synchronization possible. For further detail you can see this Chat Room Types section.

Create Group Chat Room

When you create Group Chat Room, the creator not automatically joined in the chat room that created by the creator itself, so you should add to participant key in the parameter for adding the creator.

Request:

https://api.qiscus.com/api/v2.1/rest_create_room

Headers:

"Content-Type":"application_json"
"QISCUS-SDK-APP-ID":"Your Qiscus App Id"
"QISCUS-SDK-SECRET":"Your Qiscus SDK Secret Key"

Endpoint:

[POST] /create_room

Params:

Key	Type	Description
room_name (required)	string	Name of group chat room
participants[] (required)	string[]	Array of userIds
creator (required)	string	User id for group chat room creator
room_avatar_url (optional)	string	Avatar of group chat room
room_options(optional)	json to string	You can define meta data

Example request:

curl -X POST \\
 http:__api.qiscus.com_api_v2.1_rest_create_room \\
 -H 'Content-Type: application_json' \\
 -H 'QISCUS-SDK-APP-ID: sdksample' \\
 -H 'QISCUS-SDK-SECRET: 2820ae9dfc5362f7f3a10381fb89afc7' \\
 -d '{
 "room_name": "Qiscus Demo Room",
 "creator": "guest@qiscus.com",
 "participants": ["guest@qiscus.com", "guest2@qiscus.com"],
 "room_avatar_url": "http:__placehold.it_20x20",
 "room_options": "{\\"background\\":\\"green\\"}"
}'

Response:

{
  "results": {
    "room" : {
        "room_id": "5037393",
        "room_name": "Qiscus Demo Room",
        "room_type": "group",
        "room_avatar_url": "http:__placehold.it_20x20",
        "room_options": "{\\"background\\":\\"green\\"}",
        "room_channel_id": ""
    }
  },
  "status": 200
}

Get or Create 1-on-1 Chat Room

The ideal creating 1-on-1 Chat Room is for use case that requires 2 users, for further information you can see this Chat Room types. After successfully creating a 1-on-1 Chat Room, the display name will be another userId.

Request:

https:__api.qiscus.com_api_v2.1_rest_get_or_create_room_with_target

Headers:

"Content-Type":"application_json"
"QISCUS-SDK-APP-ID":"Your Qiscus App Id"
"QISCUS-SDK-SECRET":"Your Qiscus SDK Secret Key"

Endpoint:

[POST] /get_or_create_room_with_target

Params:

Key	Type	Description
user_ids[] (required)	string[]	array of user id, the array must contains 2 user id
room_options (optional)	json to string	you can define your own metadata

Example request:

curl -X POST \\
  https:__api.qiscus.com_api_v2.1_rest_get_or_create_room_with_target \\
  -H 'Content-Type: application_json' 
  -H 'QISCUS-SDK-APP-ID: sdksample' \\
  -H 'QISCUS-SDK-SECRET: 2820ae9dfc5362f7f3a10381fb89afc7' \\
  -d '{
  "user_ids": ["guest@qiscus.com", "guest2@qiscus.com"],
  "room_options": "{\\"background\\":\\"red\\"}"
}'

Response:

{
    "results": {
        "room": {
            "room_avatar_url": "",
            "room_channel_id": "",
            "room_id": "42723",
            "room_name": "",
            "room_options": "{\\"background\\":\\"red\\"}",
            "room_type": "single"
        }
    },
    "status": 200
}

Get or Create Channel

You can create Channel or you can get channel if you already have in Qiscus Server.

Request:

https:__api.qiscus.com_api_v2.1_rest_get_or_create_channel

Headers:

"Content-Type":"application_json"
"QISCUS-SDK-APP-ID":"Your Qiscus App Id"
"QISCUS-SDK-SECRET":"Your Qiscus SDK Secret Key"

Endpoint:

[POST] /get_or_create_channel

Params:

Key	Type	Description
unique_id (required)	string	You need to define unique id for channel, cannot contains symbol # and +
participants[] (required)	string[]	Min: 1, array of user id for channel
room_name (optional)	string	Channel name
room_avatar_url (optional)	string	Channel avatar url
room_options (optional)	json to string	You can define your own metadata

Example request:

curl -X POST \\
  https:__api.qiscus.com_api_v2.1_rest_get_or_create_channel \\
  -H 'Content-Type: application_json' \\
  -H 'QISCUS-SDK-APP-ID: sdksample' \\
  -H 'QISCUS-SDK-SECRET: 2820ae9dfc5362f7f3a10381fb89afc7' \\
  -d '{
  "unique_id": "channel-1",
  "participants":  ["guest@qiscus.com", "guest2@qiscus.com"],
  "room_options": "{\\"background\\":\\"red\\"}"
}'

Response:

{

    "results": {
        "changed": true,
        "room": {
            "room_avatar_url": "",
            "room_channel_id": "channel-1",
            "room_id": "5037518",
            "room_name": "channel-1",
            "room_options": "{\\"background\\":\\"red\\"}",
            "room_type": "group"
        }
    },
    "status": 200
}

Get Chat Room Information

To get chat room information(data) by roomIds.

Request:

https:__api.qiscus.com_api_v2.1_rest_get_rooms_info

Headers:

"QISCUS-SDK-APP-ID":"Your Qiscus App Id"
"QISCUS-SDK-SECRET":"Your Qiscus SDK Secret Key"

Endpoint:

[GET] /get_rooms_info

Params:

Key	Type	Description
room_ids[] (required)	int[]	Max: 100, array of room id, it can optional if you set the room_channel_ids
room_channel ids[] (required)	string[]	Max: 100, array of room unique id, it can optional if you set the room_ids

Example request:

curl -X GET \\
  'https:__api.qiscus.com_api_v2.1_rest_get_rooms_info?room_ids[]=1375619,42723' \\
  -H 'Content-Type: application_json' \\
  -H 'QISCUS-SDK-APP-ID: sdksample' \\
  -H 'QISCUS-SDK-SECRET: 2820ae9dfc5362f7f3a10381fb89afc7'

Response:

{
    "results": {
        "rooms": [
            {
                "room_avatar_url": "",
                "room_channel_id": "",
                "room_id": "42723",
                "room_name": "",
                "room_options": "{\\"background\\": \\"red\\"}",
                "room_type": "single"
            },
            {
                "room_avatar_url": "http:__placehold.it_20x20",
                "room_channel_id": "",
                "room_id": "1375619",
                "room_name": "Qiscsu Demo Update Room",
                "room_options": "{}",
                "room_type": "group"
            }
        ]
    },
    "status": 200
}

Update Chat Room

To update Chat Room’s data.

Request:

https:__api.qiscus.com_api_v2.1_rest_update_room

Headers:

"Content-Type":"application_json"
"QISCUS-SDK-APP-ID":"Your Qiscus App Id"
"QISCUS-SDK-SECRET":"Your Qiscus SDK Secret Key"

Endpoint:

[POST] /update_room

Params:

Key	Type	Description
room_id (required)	string	id of Chat Room
room_channel_id (required)	string	unique id of Chat Room, required if the chat room type is channel
room_name (optional)	string	Chat Room name
room_avatar_url (optional)	string	Chat Room avatar url
room_options (optional)	json to string	You can define your own metadata

Example request:

curl -X POST \\
  https:__api.qiscus.com_api_v2.1_rest_update_room \\
  -H 'Content-Type: application_json' \\
  -H 'QISCUS-SDK-APP-ID: sdksample' \\
  -H 'QISCUS-SDK-SECRET: 2820ae9dfc5362f7f3a10381fb89afc7' \\
  -d '{
  "room_id": "1375619",
  "room_name" : "Qiscsu Demo Update Room",
  "room_options": "{\\"background\\":\\"red\\"}"
}'

Response:

{
  "results": {
    "changed": true,
    "room": {
        "room_id": "16",
        "room_name": "Group Room Renamed",
        "room_type": "group",
        "room_avatar_url": "https:__myimagebucket.com_image.jpg",
        "room_options": "{\\"option1\\":true,\\"string_option2\\":\\"value\\"}",
        "room_channel_id": "831dfb71-1e5b-42cd-bf81-f303e6e988eb",
    }
  },
  "status": 200
}

Get Chat Room List

To get list of chat rooms that userId has. These chat rooms are sorted by the latest message, means, whenever there’s the latest message in a chat room, the order of chat room list will change based on the latest to oldest one.

Request:

https:__api.qiscus.com_api_v2.1_rest_get_user_rooms

Headers:

"QISCUS-SDK-APP-ID":"Your Qiscus App Id"
"QISCUS-SDK-SECRET":"Your Qiscus SDK Secret Key"

Endpoint:

[GET] /get_user_rooms

Params:

Key	Type	Description
user_id (required)	string	userId
page (optional)	int	number of page, default: 1
limit (optional)	int	default: 20, max: 100, if the limit more than 100 then return 20
show_empty (optional)	boolean	should include room with no message in the response or not
room_type (optional)	single \| group \| channel (string)	filter room list based on type of room

Example request:

curl -X GET \\
  'https:__api.qiscus.com_api_v2.1_rest_get_user_rooms?user_id=guest@qiscus.com&page=1&limit=2' \\
  -H 'QISCUS-SDK-APP-ID: sdksample' \\
  -H 'QISCUS-SDK-SECRET: 2820ae9dfc5362f7f3a10381fb89afc7'

Response:

{
    "results": {
        "meta": {
            "current_page": 1,
            "total_room": 0 __ deprecated
        },
        "rooms": [
            {
                "room_avatar_url": "",
                "room_channel_id": "",
                "room_id": "41275",
                "room_name": "",
                "room_options": "{}",
                "room_type": "single"
            },
            {
                "room_avatar_url": "",
                "room_channel_id": "",
                "room_id": "2240763",
                "room_name": "",
                "room_options": "{}",
                "room_type": "single"
            }
        ]
    },
    "status": 200
}

Get Unread Count in Chat Rooms

To get unread count in each Chat Rooms that userId has.

Request:

https:__api.qiscus.com_api_v2.1_rest_get_unread_count

Headers:

"QISCUS-SDK-APP-ID":"Your Qiscus App Id"
"QISCUS-SDK-SECRET":"Your Qiscus SDK Secret Key"

Endpoint:

[GET] /get_unread_count

Params:

Key	Type	Description
user_id (required)	string	User Id
room_ids[] (required)	int	Array of room ids
room_channel_ids[] (optional)	string	Array of room channel ids

Example request:

curl -X GET \\
  'https:__api.qiscus.com_api_v2.1_rest_get_unread_count?user_id=guest@qiscus.com&room_ids[]=1375619' \\
  -H 'QISCUS-SDK-APP-ID: sdksample' \\
  -H 'QISCUS-SDK-SECRET: 2820ae9dfc5362f7f3a10381fb89afc7'

Response:

{
  "results": {
    "unread_counts": [
      {
        "room_id": "1375619",
        "unread_count": 10
      }
    ]
  },
  "status": 200
}

Get Participant List in Chat Room

To retrieve all participant in a Chat Room.

Request:

https:__api.qiscus.com_api_v2.1_rest_get_room_participants

Headers:

"QISCUS-SDK-APP-ID":"Your Qiscus App Id"
"QISCUS-SDK-SECRET":"Your Qiscus SDK Secret Key"

Endpoint:

[GET] /get_room_participants

Params:

Key	Type	Description
room_id (required)	int	Chat Room Id
page (optional)	int	Default: 1
limit (optional)	int	Show n data

Example request:

curl -X GET \\
  'https:__api.qiscus.com_api_v2.1_rest_get_room_participants?room_id=1375619&page=1&limit=10' \\
  -H 'QISCUS-SDK-APP-ID: sdksample' \\
  -H 'QISCUS_SDK_SECRET: 2820ae9dfc5362f7f3a10381fb89afc7'

Response:

{

    "results": {
        "participants": [
            {
                "avatar_url": "https:__d1edrlpyc25xu0.cloudfront.net_kiwari-prod_image_upload_75r6s_jOHa_1507541871-avatar-mine.png",
                "extras": {},
                "user_id": "guest3@qiscus.com",
                "username": "default"
            },
            {
                "avatar_url": "https:__res.cloudinary.com_qiscus_image_upload_v1507272514_kiwari-prod_user_id_340_uvwlno1qkkgh9xwwjzgq.png",
                "extras": {},
                "user_id": "guest@qiscus.com",
                "username": "Qiscus Demo"
            }
        ]
    },
    "status": 200
}

Add Participant in Chat Room

To add participant in a Chat Room.

Request:

https:__api.qiscus.com_api_v2.1_rest_add_room_participants

Headers:

"Content-Type":"application_json"
"QISCUS-SDK-APP-ID":"Your Qiscus App Id"
"QISCUS-SDK-SECRET":"Your Qiscus SDK Secret Key"

Endpoint:

[POST] /add_room_participants

Params:

Key	Type	Description
room_id (required)	string	Chat Room Id
user_ids[] (required)	string	Array of string user_ids

Example request:

curl -X POST \\
  https:__api.qiscus.com_api_v2.1_rest_add_room_participants \\
  -H 'Content-Type: application_json' \\
  -H 'QISCUS-SDK-APP-ID: sdksample' \\
  -H 'QISCUS-SDK-SECRET: 2820ae9dfc5362f7f3a10381fb89afc7' \\
  -d '{
  "room_id": "1375619",
  "user_ids": ["guest@qiscus.com"]
}'

Response:

{
  "results": {
    "participants_added": [
        {  
          "avatar_url": "https:__myimagebucket.com_image.jpg",
          "user_id": "guest@qiscus.com",
          "username": "Liu Kang"
        }
    ]
  },
  "status": 200
}

Remove Participant in Chat Room

To remove a participant in Chat Room.

Request:

https:__api.qiscus.com_api_v2.1_rest_remove_room_participants

Headers:

"Content-Type":"application_json"
"QISCUS-SDK-APP-ID":"Your Qiscus App Id"
"QISCUS-SDK-SECRET":"Your Qiscus SDK Secret Key"

Endpoint:

[POST] /remove_room_participants

Params:

Key	Type	Description
room_id (required)	string	Chat Room Id
user_ids[] (required)	string	Array of userIds

Example request:

curl -X POST \\
  https:__api.qiscus.com_api_v2.1_rest_remove_room_participants \\
  -H 'Content-Type: application_json' \\
  -H 'QISCUS-SDK-APP-ID: sdksample' \\
  -H 'QISCUS-SDK-SECRET: 2820ae9dfc5362f7f3a10381fb89afc7' \\
  -d '{
  "room_id": "1375619",
  "user_ids": ["guest2@qiscus.com"]
}'

Response:

{
    "results": {
        "participants_removed": [
            {
                "avatar_url": "https:__d1edrlpyc25xu0.cloudfront.net_kiwari-prod_image_upload_0AlS8O2rr__1507606591-Lina_icon.png",
                "extras": {},
                "user_id": "guest2@qiscus.com",
                "username": "guest2"
            }
        ]
    },
    "status": 200
}

Create Group Chat Room

Get or Create 1-on-1 Chat Room

Get or Create Channel

Get Chat Room Information

Update Chat Room

Get Chat Room List

Get Unread Count in Chat Rooms

Get Participant List in Chat Room

Add Participant in Chat Room

Remove Participant in Chat Room

Comments

Leave a Reply Cancel reply