You can use this API for managing various behaviour of message.
Send Message
After succeed creating Chat Room in Qiscus Server, now you can send message to the Chat Room. There are several type of message that you can post to a chat room, instead of text (default). Each message has different payload format (particularly in JSON/JSON string). You also you can build your own type using custom type in a message.
Request:
https://api.qiscus.com/api/v2.1/rest/post_comment
Headers:
"Content-Type":"application/json"
"QISCUS-SDK-APP-ID":"Your Qiscus App Id"
"QISCUS-SDK-SECRET":"Your Qiscus SDK Secret Key"
Endpoint:
[POST] /post_comment
Params:
Key | Type | Description<br> |
|---|
user_id (required) | string | User id in Qiscus Server |
room_id (required) | string | it can be room id or room unique id specified by client or auto generated by server |
message (required) | string | Max message content is 4000 chars |
type (optional) | string | <p>default: text, <br>and there are predefined that Qiscus provides</p><p>[account_linking|button_postback_response|buttons|card|carousel|contact_person| <span>custom|file_attachment|location|reply|text]</span></p> |
payload (optional) | json | payload for specified type |
extras (optional) | json | Meta data in message |
An example request of send a message with default type (text):
curl -X POST \
https://api.qiscus.com/api/v2.1/rest/post_comment \
-H 'Content-Type: application/json' \
-H 'QISCUS-SDK-APP-ID: sdksample' \
-H 'QISCUS-SDK-SECRET: 2820ae9dfc5362f7f3a10381fb89afc7' \
-d '{
"user_id": "
[email protected]",
"room_id": "1375619",
"message": "this is new message"
}'
And the response from above request will be:
{
"results": {
"comment": {
"message": "this is new message",
"payload": {},
"timestamp": "2019-11-03T14:45:33Z",
"type": "text",
"user": {
"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
}
Message type's payload and response:
The predefined message type have its payload, you can see for each message type's payload below:
Here's an example request payload:
{
"user_id": "
[email protected]",
"room_id": "457",
"type": "buttons",
"payload": {
"text": "silahkan pencet",
"buttons": [
{
"label": "button1",
"type": "postback",
"payload": {
"url": "http://somewhere.com/button1",
"method": "get",
"payload": null
}
},
{
"label": "button2",
"type": "link",
"payload": {
"url": "http://somewhere.com/button2?id=123"
}
}
]
}
}
Response with button's payload example :
{
"results": {
"comment": {
"message": "",
"payload": {
"text": "Silahkan pilih menu berikut:",
"buttons": [
{
"label": "button1",
"type": "postback",
"payload": {
"url": "http://somewhere.com/button1",
"method": "get",
"payload": null
}
},
{
"label": "button2",
"type": "link",
"payload": {
"url": "http://somewhere.com/button2?id=123"
}
}
]
},
"timestamp": "2018-03-12T08:11:37Z",
"type": "buttons",
"user": {
"avatar_url": "https://res.cloudinary.com/qiscus/image/fetch/http://myimage.com/image.jpg",
"user_id": "
[email protected]",
"username": "Qiscus Demo"
}
}
},
"status": 200
}
Here's an example request payload:
{
"user_id": "
[email protected]",
"room_id": "457",
"type": "card",
"payload": {
"text": "Special deal buat sista nih..",
"image": "http://url.com/gambar.jpg",
"title": "Atasan Blouse Tunik Wanita Baju Muslim Worie Longtop",
"description": "Oleh sippnshop\n96% (666 feedback)\nRp 49.000.00,-\nBUY 2 GET 1 FREE!!!",
"url": "http://url.com/baju?id=123&track_from_chat_room=123",
"buttons": [
{
"label": "button1",
"type": "postback",
"payload": {
"url": "http://somewhere.com/button1",
"method": "get",
"payload": null
}
},
{
"label": "button2",
"type": "link",
"payload": {
"url": "http://somewhere.com/button2?id=123",
"method": "get",
"payload": null
}
}
]
}
}
Response with card's palyoad example:
{
"results": {
"comment": {
"message": "Special deal buat sista nih..",
"payload": {
"buttons": [
{
"label": "button1",
"postback_text": "",
"type": "postback",
"payload": {
"url": "http://somewhere.com/button1",
"method": "get",
"payload": null
}
},
{
"label": "button2",
"postback_text": "",
"type": "link",
"payload": {
"url": "http://somewhere.com/button2?id=123",
"method": "get",
"payload": null
}
}
],
"description": "Oleh sippnshop\n96% (666 feedback)\nRp 49.000.00,-\nBUY 2 GET 1 FREE!!!",
"image": "http://url.com/gambar.jpg",
"text": "Special deal buat sista nih..",
"title": "Atasan Blouse Tunik Wanita Baju Muslim Worie Longtop",
"url": "http://url.com/baju?id=123&track_from_chat_room=123"
},
"timestamp": "2018-03-12T08:11:47Z",
"type": "card",
"user": {
"avatar_url": "https://res.cloudinary.com/qiscus/image/fetch/http://myimage.com/image.jpg",
"user_id": "
[email protected]",
"username": "Qiscus Demo"
}
}
},
"status": 200
}
Here's an example request payload:
{
"user_id": "
[email protected]",
"room_id": "457",
"type" : "carousel",
"payload": {
"cards": [
{
"image": "http://url.com/gambar.jpg",
"title": "Atasan Blouse Tunik Wanita Baju Muslim Worie Longtop",
"description": "Oleh sippnshop\n96% (666 feedback)\nRp 49.000.00,-\nBUY 2 GET 1 FREE!!!",
"default_action": {
"type": "postback",
"postback_text": "Load more",
"payload": {
"url": "http://url.com/baju?id=123&track_from_chat_room=123",
"method": "get",
"payload": null
}
},
"buttons": [
{
"label": "button1",
"type": "postback",
"postback_text": "Load more",
"payload": {
"url": "http://somewhere.com/button1",
"method": "get",
"payload": null
}
},
{
"label": "button2",
"type": "link",
"payload": {
"method": "get",
"url": "http://somewhere.com/button2?id=123"
}
}
]
}
]
}
}
Response with carousel's payload example:
{
"results": {
"comment": {
"message": "",
"payload": {
"cards": [
{
"image": "http://url.com/gambar.jpg",
"title": "Atasan Blouse Tunik Wanita Baju Muslim Worie Longtop",
"description": "Oleh sippnshop\n96% (666 feedback)\nRp 49.000.00,-\nBUY 2 GET 1 FREE!!!",
"default_action": {
"type": "postback",
"postback_text": "Load more",
"payload": {
"url": "http://url.com/baju?id=123&track_from_chat_room=123",
"method": "get",
"payload": null
}
},
"buttons": [
{
"label": "button1",
"postback_text": "Load more",
"type": "postback",
"payload": {
"url": "http://somewhere.com/button1",
"method": "get",
"payload": null
}
},
{
"label": "button2",
"postback_text": "",
"type": "link",
"payload": {
"url": "http://somewhere.com/button2?id=123",
"method": "get",
"payload": null
}
}
]
}
]
},
"timestamp": "2018-03-13T09:53:25Z",
"type": "carousel",
"user": {
"avatar_url": "https://res.cloudinary.com/qiscus/image/fetch/http://myimage.com/image.jpg",
"user_id": "
[email protected]",
"username": "guest"
}
}
},
"status": 200
}
Message text will be the caption. An request file_attachment payload:
{
"user_id": "
[email protected]",
"room_id": "457",
"type" : "file_attachment",
"payload": {
"url": "https://res.cloudinary.com/qiscus/image/upload/USWiylE7Go/ios-15049438515185.png",
"caption": "Ini gambar siapa?",
"file_name": "",
"size": 0,
"pages": 1
}
}
Response with file_attachment's payload example:
{
"results": {
"comment": {
"message": "[file] https://res.cloudinary.com/qiscus/image/upload/USWiylE7Go/ios-15049438515185.png [/file]",
"payload": {
"url": "https://res.cloudinary.com/qiscus/image/upload/USWiylE7Go/ios-15049438515185.png",
"caption": "Ini gambar siapa?",
"file_name": "",
"size": 0,
"pages": 1
},
"timestamp": "2018-03-12T08:12:19Z",
"type": "file_attachment",
"user": {
"avatar_url": "http://myimage.com/image.jpg",
"user_id": "
[email protected]",
"username": "Qiscus Demo"
}
}
},
"status": 200
}
Request payload must be valid JSON string object, and it will return as what you have inputted. The JSON payload must have any type and content object. Type must be string, for example if you want to create promo payload, it can be promo. The content can be anything, such as object, array, number or string in JSON. By this, you can input, let say XML string in payload.content object value and later you can parse it by yourself by overriding Qiscus Chat SDK client chat view.
Example request payload:
{
"user_id": "
[email protected]",
"room_id": "457",
"type": "custom",
"payload": {
"type": "promo", // sub type of custom payload
"content": {
"date": "2017-09-09"
} // can be anything: object, array, string, number in JSON
}
}
Response with custom's payload example:
{
"results": {
"comment": {
"message": "",
"payload": {
"content": {
"date": "2017-09-09"
}
"type": "promo"
},
"timestamp": "2018-03-12T08:11:52Z",
"type": "custom",
"user": {
"avatar_url": "http://myimage.com/image.jpg",
"user_id": "
[email protected]",
"username": "Qiscus Demo"
}
}
},
"status": 200
}
Load Message
To retrieve the message data.
Request:
https://api.qiscus.com/api/v2.1/rest/load_comments
Headers:
"QISCUS-SDK-APP-ID":"Your Qiscus App Id"
"QISCUS-SDK-SECRET":"Your Qiscus SDK Secret Key"
Endpoint:
[GET] /load_comments
Params:
Key | Type | Description |
|---|
room_id (required) | int | Chat Room Id |
page (optional) | int | Number of page |
limit (optional) | int | Default, 20 messages |
Example request:
curl -X GET \
'https://api.qiscus.com/api/v2.1/rest/load_comments?room_id=1375619&page=1&limit=20' \
-H 'QISCUS-SDK-APP-ID: sdksample' \
-H 'QISCUS-SDK-SECRET: 2820ae9dfc5362f7f3a10381fb89afc7'
Response:
{
"results": {
"comments": [
{
"message": "testing message 1",
"timestamp": "2017-02-07T19:01:00Z",
"type": "text",
"payload": null,
"user": {
"avatar_url": "https://myimagebucket.com/image.jpg",
"user_id": "
[email protected]",
"username": "Liu Kang"
}
},
{
"message": "testing message 2",
"timestamp": "2017-02-07T19:03:00Z",
"type": "text",
"payload": null,
"user": {
"avatar_url": "https://myimagebucket.com/image.jpg",
"user_id": "
[email protected]",
"username": "Sonya"
}
}
]
},
"status": 200
}
Post System Event Message
To send event system message such as creating group, join room, remove member, and other use case that need to notify an event to participants in a Chat Room.
Request:
https://api.qiscus.com//api/v2.1/rest/post_system_event_message
Headers:
"Content-Type":"application/json"
"QISCUS-SDK-APP-ID":"Your Qiscus App Id"
"QISCUS-SDK-SECRET":"Your Qiscus SDK Secret Key"
Endpoint:
[POST] /post_system_event_message
Params:
Key | Type | Description |
|---|
system_event_type | string | set "custom" value, to able to use this system event |
room_id | string | it can be room id or room unique id specified by client or auto generated by server<br> |
message | string | Max message content is 4000 chars |
payload | json | Desired payload that you can define based on your needs |
extras | json | Meta data in message<br> |
An example request system event:
{
"system_event_type": "custom",
"room_id": "1375619",
"message": "Hello Qiscus",
"payload": {
"type": "add_admin",
"admin_email": "
[email protected]"
},
"extras": {
"qiscus_ios_pn": {
"aps": {
"content-avaibility": 1
}
}
}
}
if extras contains key qiscus_ios_pn, it will override payload value that for APNS PN.
Response:
{
"results": {
"comment": {
"message": "Admin is being set",
"payload": {
"payload": {
"admin_email": "
[email protected]",
"type": "add_admin"
},
"room_name": "Qiscsu Demo Update Room",
"type": "custom"
},
"timestamp": "2019-11-03T15:11:01Z",
"type": "system_event",
"user": {
"avatar_url": "https://d1edrlpyc25xu0.cloudfront.net/kiwari-prod/image/upload/75r6s_jOHa/1507541871-avatar-mine.png",
"extras": {},
"user_id": "
[email protected]",
"username": "System"
}
}
},
"status": 200
}
