Chat
All chat endpoints have path prefix /chat-service.
User Side
Fetch All Messages
Retrieve read and unread user messages. Messages in the response are grouped into messages (already read) and unread fields. messages and unread groups are JSON objects with peer identifiers (participant identifiers) as keys and arrays of messages as values. Each message value is a JSON object with fields from, to, ts (timestamp of the message) and text.
GET /chat-service/user_messages
Parameters
| Name | Type | Description |
|---|---|---|
| authenticateit_identity_ticket | header | Required: Session's ticket |
Example Response
{
"messages": {
"urn:authenticateit:participant:991789510426571": [
{
"from": "urn:authenticateit:participant:991789510426571",
"text": "Hello",
"to": "urn:authenticateit:user:email:xyz@foo.bar",
"ts": "2017-04-20T19:23:32Z"
}
]
},
"unread": {
"urn:authenticateit:participant:991789510426571": [
{
"from": "urn:authenticateit:participant:991789510426571",
"text": "How are you?",
"to": "urn:authenticateit:user:email:xyz@foo.bar",
"ts": "2017-04-20T19:31:32Z"
}
]
}
}
Fetch Unread Messages
Like fetch all messages endpoint but filters out already read messages. Response is the same as for fetch all messages endpoint, but messages field (already read messages) will be filtered out from the response.
GET /chat-service/user_messages/unread
Parameters
| Name | Type | Description |
|---|---|---|
| authenticateit_identity_ticket | header | Required: Session's ticket |
Example Response
{
"unread": {
"urn:authenticateit:participant:991789510426571": [
{
"from": "urn:authenticateit:participant:991789510426571",
"text": "How are you?",
"to": "urn:authenticateit:user:email:xyz@foo.bar",
"ts": "2017-04-20T19:31:32Z"
}
]
}
}
Mark Unread Messages as Read
Mark all unread user messages as read. Effectively moves messages from unread section of user messages document to messages section (already read messages).
DELETE /chat-service/user_messages/unread
Parameters
| Name | Type | Description |
|---|---|---|
| authenticateit_identity_ticket | header | Required: Session's ticket |
Brand Support Presence
Retrieve brand support operator presence. Response JSON object contains presence field with either online or offline value.
GET /chat-service/brand_support/:participant_id/presence
Parameters
| Name | Type | Description |
|---|---|---|
| authenticateit_identity_ticket | header | Required: Session's ticket |
| id | url | Required: Participant identifier |
Example Response
{
"presence": "online"
}
Send Message to Brand Support
Send message to a brand support operator. Request JSON must contain text field with the message text.
POST /chat-service/brand_support/:participant_id/messages
Parameters
| Name | Type | Description |
|---|---|---|
| authenticateit_identity_ticket | header | Required: Session's ticket |
| id | url | Required: Participant identifier |
| text | string | Required Text message |
Brand Side
User must have support role from a participant with livechat module to access these endpoints.
Fetch All Messages
Retrieve all brand support operator messages. Has the same request and response formats as for fetch all user messages endpoint, but messages are of brand operator instead of user.
GET /chat-service/brand_messages
Parameters
| Name | Type | Description |
|---|---|---|
| authenticateit_identity_ticket | header | Required: Session's ticket |
Example Response
{
"messages": {
"urn:authenticateit:user:email:xyz@foo.bar": [
{
"from": "urn:authenticateit:user:email:xyz@foo.bar",
"text": "Hello. I have a question",
"to": "urn:authenticateit:participant:991789510426571",
"ts": "2017-04-20T20:15:09Z"
},
{
"from": "urn:authenticateit:user:email:xyz@foo.bar",
"text": "test",
"to": "urn:authenticateit:participant:991789510426571",
"ts": "2017-04-20T13:24:19Z"
}
]
},
"unread": {}
}
Fetch Unread Messages
Retrieve only unread brand support operator messages. Has the same request and response formats as for fetch unread user messages endpoint, but messages are of brand operator instead of user.
GET /chat-service/brand_messages/unread
Parameters
| Name | Type | Description |
|---|---|---|
| authenticateit_identity_ticket | header | Required: Session's ticket |
Example Response
{
"unread": {
"urn:authenticateit:participant:991789510426571": [
{
"from": "urn:authenticateit:participant:991789510426571",
"text": "How are you?",
"to": "urn:authenticateit:user:email:xyz@foo.bar",
"ts": "2017-04-20T19:31:32Z"
}
]
}
}
Mark Unread Messages as Read
Mark all unread brand support operator messages as read. Has the same request and response formats as for mark unread user messages endpoint, but messages are of brand operator instead of user.
DELETE /chat-service/brand_messages/unread
Parameters
| Name | Type | Description |
|---|---|---|
| authenticateit_identity_ticket | header | Required: Session's ticket |
Brand Support Session
WebSocket endpoint for brand support operator to start a chat session.
GET /chat-service/brand_support/chat
Parameters
| Name | Type | Description |
|---|---|---|
| authenticateit_identity_ticket | header | Required: Session's ticket |
Example Response
Server upgrades connection to WebSocket.
Chat session protocol in WebSocket session is like JSON-RPC 1.0, but params must be JSON object instead of list of unnamed arguments.
send_message
Server accepts send_message method with message parameter:
{
"id": 1,
"method": "send_message",
"params": {
"message": {
"to": "urn:authenticateit:user:email:xyz@foo.bar",
"text": "Hello. Ill answer your question in a minute."
}
}
}
Field to must be a Shping user identifier to receive the message, and text must be message text. Server responds with null result:
{
"id": 1,
"result": null,
"error": null
}
receive_message
When a Shping user sends a message to the brand support operator, it will be delivered to all active chat sessions as receive_message notification:
{
"method": "receive_message",
"params": {
"message": {
"from": "urn:authenticateit:user:email:xyz@foo.bar",
"to": "urn:authenticateit:participant:9917895104265710",
"ts": "2017-04-20T19:35:17Z",
"text": "Hello. I have a question."
}
}
}