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": "
[email protected]",
"participants": ["
[email protected]", "
[email protected]"],
"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": ["
[email protected]", "
[email protected]"],
"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 |
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": ["
[email protected]", "
[email protected]"],
"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
}
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 |
room_unique_ids[] (optional) | string[] | Max: 100, array of room unique id |
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 |
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.
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 |
Example request:
curl -X GET \
'https://api.qiscus.com/api/v2.1/rest/
[email protected]&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 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": "
[email protected]",
"username": "default"
},
{
"avatar_url": "https://res.cloudinary.com/qiscus/image/upload/v1507272514/kiwari-prod_user_id_340/uvwlno1qkkgh9xwwjzgq.png",
"extras": {},
"user_id": "
[email protected]",
"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": ["
[email protected]"]
}'
Response:
{
"results": {
"participants_added": [
{
"avatar_url": "https://myimagebucket.com/image.jpg",
"user_id": "
[email protected]",
"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": ["
[email protected]"]
}'
Response:
{
"results": {
"participants_removed": [
{
"avatar_url": "https://d1edrlpyc25xu0.cloudfront.net/kiwari-prod/image/upload/0AlS8O2rr_/1507606591-Lina_icon.png",
"extras": {},
"user_id": "
[email protected]",
"username": "guest2"
}
]
},
"status": 200
}
