Chat Service - Beta
The Chat Service provides the ability to:
- Send messages to a room
- Receive messages from a room
- Get a room's chat message history
All room members that are subscribed to the chat will receive the text messages. You must first enter the room before you may send and receive messages.
Initializing
First, instantiate the chat service. A Room Service is required to obtain the chat service.
import android.content.Context;
import com.phenixrts.chat.RoomChatService;
import com.phenixrts.chat.RoomChatServiceFactory;
import com.phenixrts.environment.android.AndroidContext;
import com.phenixrts.room.RoomService;
// IMPORTANT: Before accessing any of the static factories, make sure the context is passed to Phenix:
final Context context = ...; // e.g. Activity.getApplication();
AndroidContext.setContext(context);
final RoomService roomService = ...; // previously obtained
final RoomChatService chatService = RoomChatServiceFactory.createRoomChatService(roomService);
// Use a custom batch size, i.e. max number of message returned by 'getObservableChatMessages'
final int batchSize = 10;
final RoomChatService chatServiceWithBatchSize = RoomChatServiceFactory.createRoomChatService(
roomService, batchSize);
RoomChatService
Name | Signature | Returns | Description |
---|---|---|---|
getObservableChatMessages | () | Observable(of ChatMessage[]) | Get the observable of the most recent chat messages. This is a buffer of the most recent N messages up to a max of 100. See Listen for Chat Messages |
getObservableChatEnabled | () | Observable(of Boolean) | Get the observable of the enabled status of the chat service. Use this to disable or enable the chat. |
sendMessageToRoom | (message, callback) | void | Send a message to room. |
getMessages | (batchSize, afterMessageId, beforeMessageId, callback) | void | Get chat message history |
ChatMessage
Name | Type | Description |
---|---|---|
getMessageId | String | Unique ID of message |
getObservableTimeStamp | Observable(of Date) | Server UTC timestamp of message |
getObservableFrom | Observable(of ChatUser) | Information on the member that sent the message |
getObservableMessage | Observable(of String) | Chat message |
ChatUser
Name | Type | Description |
---|---|---|
getSessionId | String | Member's session ID |
getObservableScreenName | Observable(of String) | Screen name of the member |
getObservableMemberRole | Observable(of MemberRole) | Member's role. See Member Roles |
getObservableLastUpdate | Observable(of Date) | Last time member was updated as UTC timestamp |
Listen for Chat Messages in the Active Room
The chat service exposes an observable of the most recent N (batchSize) messages in the active room up to a max of 100 messages. To view older messages you will need to use the getMessages method.
import com.phenixrts.common.Disposable;
import com.phenixrts.common.Observable;
import com.phenixrts.chat.ChatMessage;
import com.phenixrts.chat.RoomChatService;
import com.phenixrts.chat.RoomChatServiceFactory;
import com.phenixrts.room.RoomService;
final RoomService roomService = ...; // previously obtained
final int batchSize = 10;
final RoomChatService chatService = RoomChatServiceFactory.createRoomChatService(roomService, batchSize);
final Observable<ChatMessage[]> chatMessageObservable = chatService.getObservableChatMessages();
final Disposable subscription = chatMessageObservable.subscribe((change) -> {
final ChatMessage[] messages = (ChatMessage[])change;
// Do something with chat messages
});
Send a Message to the Active Room
Send a single message to the active room. If the message is successfully sent the chatMessageObservable will trigger notifications on all subscribers with the new chat message.
import com.phenixrts.common.RequestStatus;
import com.phenixrts.chat.ChatMessage;
import com.phenixrts.chat.RoomChatService;
final RoomChatService chatService = ...; // previously obtained
// Without callback:
chatService.sendMessageToRoom("My First Message");
// With callback
chatService.sendMessageToRoom("My First Message", (RequestStatus status, String message) -> {
if (status == RequestStatus.OK) {
// Successfully sent
} else {
// handle error - send message again
// (`message` may provide more information about what went wrong)
}
});
Send Message Parameters
Name | Type | Description |
---|---|---|
message (required) | String | Message to send to the room |
sendMessageCallback (optional) | RoomChatService.SendMessageCallback | Callback with the status of the request |
Send Message Callback Arguments
Name | Type | Description |
---|---|---|
status | RequestStatus | The status of the operation |
message | String | Optional additional error status in case of a failure |
Send Message Callback Status Codes
| Status | Description | | -------- | ---------------------- | ------------------------------------- | | ok | Send message succeeded | | varies | | Send message failed for other reasons |
Chat Message History
Get messages older than the most recent N buffered in the chatMessageObservable.
Get the 10 most recent messages after a message:
import com.phenixrts.common.RequestStatus;
import com.phenixrts.chat.ChatMessage;
import com.phenixrts.chat.RoomChatService;
final RoomChatService chatService = ...; // previously obtained
final int batchSize = 10;
final String afterMessageId = "MessageId1";
final String beforeMessageId = null;
chatService.getMessages(
batchSize,
afterMessageId,
beforeMessageId,
(RoomChatService chatService, ChatMessage[] messages, RequestStatus status) -> {
if (status == RequestStatus.OK) {
// Successfully got chat messages
} else {
// handle error - request messages again
}
});
Get all messages between two messages:
import com.phenixrts.common.RequestStatus;
import com.phenixrts.chat.ChatMessage;
import com.phenixrts.chat.RoomChatService;
final RoomChatService chatService = ...; // previously obtained
final int batchSize = 100;
final String afterMessageId = "MessageId1";
final String beforeMessageId = "MessageId2";
chatService.getMessages(
batchSize,
afterMessageId,
beforeMessageId,
(RoomChatService chatService, ChatMessage[] messages, RequestStatus status) -> {
if (status == RequestStatus.OK) {
// Successfully got chat messages
} else {
// handle error - request messages again
}
});
Get Messages Parameters
Name | Type | Description |
---|---|---|
batchSize (required) | int | Limit of messages to receive. |
afterMessageId (optional) | String | The messageId to return after. The N messages after message with ID of afterMessageId but before beforeMessageId |
beforeMessageId (optional) | String | The messageId to return before. The N messages before message with ID of beforeMessageId |
callback (required) | RoomChatService.GetMessagesCallback | Callback with the status of the request |
Get Messages Callback Arguments
Name | Type | Description |
---|---|---|
roomChatService | RoomChatService | The chat service making the callback |
messages | ChatMessage[] | Array of chat messages matching search criteria |
status | RequestStatus | The status of the operation |
Get Messages Callback Status Codes
Status | Description |
---|---|
ok | Get messages succeeded |
varies | Get messages failed for other reasons |