Chat Service

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.

Java
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.

Java
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.

Java
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:

Java
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:

Java
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

Page Content

v2023-01-31T21:25:10