Quick Start
About I2A Chat Service
Configure your App
Create a Chat Room
Connect to the Chat Server
Rest API
Overview
You Are The Source of Truth
API URLs and Authentication
URLs and Authentication
Ping
Open session
Close session
Create Chat Room
Add User to Chat Room
Remove User from Chat Room
Delete Chat Room
Send System Message
Report a Message
Websocket
Messages in
Error message
Messages out
WEBSOCKET MESSAGES
1) To start a conversation, you first need to find other users in the system (find their userprofile IDs).
You can query all users in the system via GET /users/user-profiles/, refer to Swagger on available filtering
options
2) Then, create a conversation. There are two types of conversation: user-to-user (only 2 users) and group conversations (from 0 to N users). Just like on facebook, users **don't need to be friends** to start conversation, you can start conversation with any user in the system.
* Create user-to-user conversation via POST /chats/conversation/, pass JSON with one field: userprofile_id (the guy you want to talk to)
* Create group conversation via POST /chats/group_conversation/, pass JSON with name and user_profile_ids (list of guys you want to talk to - you MUST include your own profile id here as well!)
3) To list conversations and group conversations we are in:
* GET /api/v1/chats/conversation
* GET /api/v1/chats/group_conversation/
4) Get a chat server session token via POST /chats/session/open-session/, pass device_identifier (unique device id such as mac address)
5) Open a web socket to the chat server, and start sending/receiving messages: see the section below.
2) Then, create a conversation. There are two types of conversation: user-to-user (only 2 users) and group conversations (from 0 to N users). Just like on facebook, users **don't need to be friends** to start conversation, you can start conversation with any user in the system.
* Create user-to-user conversation via POST /chats/conversation/, pass JSON with one field: userprofile_id (the guy you want to talk to)
* Create group conversation via POST /chats/group_conversation/, pass JSON with name and user_profile_ids (list of guys you want to talk to - you MUST include your own profile id here as well!)
3) To list conversations and group conversations we are in:
* GET /api/v1/chats/conversation
* GET /api/v1/chats/group_conversation/
4) Get a chat server session token via POST /chats/session/open-session/, pass device_identifier (unique device id such as mac address)
5) Open a web socket to the chat server, and start sending/receiving messages: see the section below.
ROUTABLE
A message that user want to send to all others' people in given chat room.
Request
{
type: 'ROUTABLE'
chat_room_identifier: string
message: string
}
type: 'ROUTABLE'
chat_room_identifier: string
message: string
}
HISTORY
Request for a chat room history. Returns {limit} messages that occurred BEFORE given point in time.
Returned messages are sorted from newer to older.
* from_message_timestamp_identifier -> unix epoch timestamp (in nanoseconds) before which you want to pull messages.
For example to pull messages before September 1, 2021 9:50:38 (unix timestamp 1630489838) you need to pass 1630489838000000000
* limit -> how many messages you want to get. Maximum is 100.
* from_message_timestamp_identifier -> unix epoch timestamp (in nanoseconds) before which you want to pull messages.
For example to pull messages before September 1, 2021 9:50:38 (unix timestamp 1630489838) you need to pass 1630489838000000000
* limit -> how many messages you want to get. Maximum is 100.
Request
{
type: 'GET_HISTORY'
chat_room_identifier: string
from_message_timestamp_identifier: integer
limit: integer
}
type: 'GET_HISTORY'
chat_room_identifier: string
from_message_timestamp_identifier: integer
limit: integer
}
SET LAST MESSAGE READ
Marks a chat room message as read. Server will automatically notify all online users
who read which message. Note: user does not need to mark their own messages as read - server does that
automatically.
You will know the message_timestamp_identifier because each routable message you receive from the socket
includes
that timestamp. See more in "receiving messages from the socket" section.
Request
{
type: 'SET_LAST_MESSAGE_READ'
chat_room_identifier: string
message_timestamp_identifier: integer
}
type: 'SET_LAST_MESSAGE_READ'
chat_room_identifier: string
message_timestamp_identifier: integer
}
GET LAST MESSAGES READ
Requests information about last message that all users has read in chat room. Use this ONLY
when user enters the chat room on a new session.
Request
{
type: 'GET_LAST_MESSAGES_READ'
chat_room_identifier: string
}
type: 'GET_LAST_MESSAGES_READ'
chat_room_identifier: string
}
GET LAST CHAT ROOM MESSAGE
Specify a list of chat room identifiers and get last 1 last message published in each
of those chat rooms in response. Note that chat_room_identifiers needs to be a list of strings.
Request
{
type: 'GET_LAST_CHAT_ROOM_MESSAGE'
chat_room_identifiers: list[string]
}
type: 'GET_LAST_CHAT_ROOM_MESSAGE'
chat_room_identifiers: list[string]
}
GET UNREAD MESSAGES COUNT
Specify a list of chat room indentifiers (max 10) and get a number of unread messages
the calling user has in each of those chat rooms. The operation is quite heavy on the server side and is
meant to be
used in paginated views only, hence the number of chat room identiers you can send is limited to 10.
Another
limitation is that if user has more than 100 unread messages in given chatroom, the response will still
return a
count of 100. The chat client should display this as "99+ unread messages".
Request
{
type: 'GET_UNREAD_MESSAGES_COUNT'
chat_room_identifiers: list[string]
}
type: 'GET_UNREAD_MESSAGES_COUNT'
chat_room_identifiers: list[string]
}
ERROR
You receive this message when something goes wrong.
There are following error codes possible:
* 10001 - Internal server error.
* 10001 - User does not belong to this chat room. The cause of this error is when you pass an incorrect chat_room_identifier.
* 10002 - 'message' field must be a string type.
* 10003 - Length of chat_room_identifiers list cannot be grater than 10. This error is specific to GET_UNREAD_MESSAGES_COUNT request.
* 10004 - Invalid message format. You'll see this error when your message is malformed, i.e. not a valid JSON.
* 10005 - Missing required field. You sent a message without a required field. This error will include an extra object with the name of the required field.
* 10006 - Central router not present. Consider this an internal server error.
* 10007 - Message flood detected. If user spams the chat with more than 300 messages per minute, server will send back this error and terminate
socket connection. You should show an appropriate error message to the user in your client app and re-open the socket.
* 10001 - Internal server error.
* 10001 - User does not belong to this chat room. The cause of this error is when you pass an incorrect chat_room_identifier.
* 10002 - 'message' field must be a string type.
* 10003 - Length of chat_room_identifiers list cannot be grater than 10. This error is specific to GET_UNREAD_MESSAGES_COUNT request.
* 10004 - Invalid message format. You'll see this error when your message is malformed, i.e. not a valid JSON.
* 10005 - Missing required field. You sent a message without a required field. This error will include an extra object with the name of the required field.
* 10006 - Central router not present. Consider this an internal server error.
* 10007 - Message flood detected. If user spams the chat with more than 300 messages per minute, server will send back this error and terminate
socket connection. You should show an appropriate error message to the user in your client app and re-open the socket.
Example response
{
type: ROUTABLE
message_timestamp_identifier: 1630499662256827108
chat_room_identifier: b95c5d7e-0fad-415a-8ea5-035f1a79c335:SFF-QA
app_user_identifier: def094f5-2e13-45e7-8712-edb2e8b55fe5:SFF-QA
message: Hello world!
custom_data: {\"display_name\": \"Joe Biden\", \"first_name\": \"Joe\", \"last_name\": \"Biden\"}
}
type: ROUTABLE
message_timestamp_identifier: 1630499662256827108
chat_room_identifier: b95c5d7e-0fad-415a-8ea5-035f1a79c335:SFF-QA
app_user_identifier: def094f5-2e13-45e7-8712-edb2e8b55fe5:SFF-QA
message: Hello world!
custom_data: {\"display_name\": \"Joe Biden\", \"first_name\": \"Joe\", \"last_name\": \"Biden\"}
}
SYSTEM ROUTABLE
You receive this message when server wants to tell something all users in given chat room. It covers
cases such as user being added to or kicked from a group conversation, conversation owner transferring
group
ownership to another user, and the like.
* chat_room_identifier - chat room in which the message was written
* message_timestamp_identifier - message timestamp in form of unix epoch time, in nanoseconds
* app_user_identifier - identifier of the use who wrote the message
* custom_data - custom data associated with the user who wrote the message
* message - the message content
* chat_room_identifier - chat room in which the message was written
* message_timestamp_identifier - message timestamp in form of unix epoch time, in nanoseconds
* app_user_identifier - identifier of the use who wrote the message
* custom_data - custom data associated with the user who wrote the message
* message - the message content
Example response
{
type: SYSTEM_ROUTABLE
chat_room_identifier: b95c5d7e-0fad-415a-8ea5-035f1a79c335:SFF-QA
message_timestamp_identifier: 1639741268522956324
message: System message!
}
type: SYSTEM_ROUTABLE
chat_room_identifier: b95c5d7e-0fad-415a-8ea5-035f1a79c335:SFF-QA
message_timestamp_identifier: 1639741268522956324
message: System message!
}
GET HISTORY
You receive this message as a response to GET_HISTORY message sent to the socket.
It will list user messages as well as system messages, the "is_system_message" flag indicates the type
of message.
System messages do not include custom_data and app_user_identifier, because they don't come from any
user.
Example response
{
type: GET_HISTORY
payload: [
{
message: Hello world!
is_system_message: False
message_timestamp_identifier: 1639741268522956324
chat_room_identifier: b95c5d7e-0fad-415a-8ea5-035f1a79c335:SFF-QA
app_user_identifier: def094f5-2e13-45e7-8712-edb2e8b55fe5:SFF-QA
custom_data: {\"display_name\": \"Joe Biden\", \"first_name\": \"Joe\", \"last_name\": \"Biden\"}
},
... more messages ...
]
}
type: GET_HISTORY
payload: [
{
message: Hello world!
is_system_message: False
message_timestamp_identifier: 1639741268522956324
chat_room_identifier: b95c5d7e-0fad-415a-8ea5-035f1a79c335:SFF-QA
app_user_identifier: def094f5-2e13-45e7-8712-edb2e8b55fe5:SFF-QA
custom_data: {\"display_name\": \"Joe Biden\", \"first_name\": \"Joe\", \"last_name\": \"Biden\"}
},
... more messages ...
]
}
GET LAST MESSAGES READ
List with last messages read by users in a chatroom. You receive this message as a response to
GET_LAST_MESSAGES_READ
sent to the server. It includes last message read by each user in the chat room, so for example, if
there are 5
users in the chatroom, the list will have 5 elements, one for each user.
Example response
{
type: GET_LAST_MESSAGES_READ
payload: [
{
message_timestamp_identifier: 1630499662256827108
chat_room_identifier: b95c5d7e-0fad-415a-8ea5-035f1a79c335:SFF-QA
app_user_identifier: def094f5-2e13-45e7-8712-edb2e8b55fe5:SFF-QA
custom_data: {\"display_name\": \"Joe Biden\", \"first_name\": \"Joe\", \"last_name\": \"Biden\"}
},
... more messages ...
]
}
type: GET_LAST_MESSAGES_READ
payload: [
{
message_timestamp_identifier: 1630499662256827108
chat_room_identifier: b95c5d7e-0fad-415a-8ea5-035f1a79c335:SFF-QA
app_user_identifier: def094f5-2e13-45e7-8712-edb2e8b55fe5:SFF-QA
custom_data: {\"display_name\": \"Joe Biden\", \"first_name\": \"Joe\", \"last_name\": \"Biden\"}
},
... more messages ...
]
}
SET LAST MESSAGE READ
A notification from the server indicating that a specific user has marked specific message as read
Example response
{
type: GET_LAST_MESSAGES_READ
message_timestamp_identifier: 1630499662256827108
chat_room_identifier: b95c5d7e-0fad-415a-8ea5-035f1a79c335:SFF-QA
app_user_identifier: def094f5-2e13-45e7-8712-edb2e8b55fe5:SFF-QA
custom_data: {\"display_name\": \"Joe Biden\", \"first_name\": \"Joe\", \"last_name\": \"Biden\"}
type: GET_LAST_MESSAGES_READ
message_timestamp_identifier: 1630499662256827108
chat_room_identifier: b95c5d7e-0fad-415a-8ea5-035f1a79c335:SFF-QA
app_user_identifier: def094f5-2e13-45e7-8712-edb2e8b55fe5:SFF-QA
custom_data: {\"display_name\": \"Joe Biden\", \"first_name\": \"Joe\", \"last_name\": \"Biden\"}
GET LAST CHAT ROOM MESSAGE
The payload object will list the newest chat message from all chat rooms sent in the request. The
'has_unread_messages'
flag is true if calling user has at least one unread message in given chat room, otherwise it's false.
Example response
{
type: GET_LAST_CHAT_ROOM_MESSAGE
payload: [
{
chat_room_identifier: ceaa81a9-6ca9-4b5c-a1c7-64c81f7cbf87:SFF-QA
last_message_text: Hello world!
message_timestamp_identifier: 1634223745351316876
has_unread_messages: true
},
... more chat room data ...
]
}
type: GET_LAST_CHAT_ROOM_MESSAGE
payload: [
{
chat_room_identifier: ceaa81a9-6ca9-4b5c-a1c7-64c81f7cbf87:SFF-QA
last_message_text: Hello world!
message_timestamp_identifier: 1634223745351316876
has_unread_messages: true
},
... more chat room data ...
]
}
GET UNREAD MESSAGES COUNT
The payload object will list unread messages counts for all chat rooms sent in the request.
Example response
{
type: GET_UNREAD_MESSAGES_COUNT
payload: [
{
chat_room_identifier: ceaa81a9-6ca9-4b5c-a1c7-64c81f7cbf87:SFF-QA
unread_messages_count: 13
},
... more chat room data ...
]
}
type: GET_UNREAD_MESSAGES_COUNT
payload: [
{
chat_room_identifier: ceaa81a9-6ca9-4b5c-a1c7-64c81f7cbf87:SFF-QA
unread_messages_count: 13
},
... more chat room data ...
]
}