Chat Room
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_roomHeaders:
"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_targetHeaders:
"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_channelHeaders:
"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:
x
{ "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_infoHeaders:
"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_roomHeaders:
"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_roomsHeaders:
"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_countHeaders:
"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_participantsHeaders:
"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_participantsHeaders:
"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_participantsHeaders:
"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}Was this page helpful?