# 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](/content/docs/sdk_ref/android/chat/#roomchatservice/index.html) 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](/content/docs/sdk_ref/android/chat/#chatmessage/index.html)\[\]) | 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](/content/docs/sdk_ref/android/chat/#listen-for-chat-messages-in-the-active-room/index.html) |
| 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](/content/docs/sdk_ref/android/chat/#send-a-message-to-the-active-room/index.html). |
| getMessages | (batchSize, afterMessageId, beforeMessageId, callback) | void | [Get chat message history](/content/docs/sdk_ref/android/chat/#chat-message-history/index.html) |

### ChatMessage

| Name | Type | Description |
| --- | --- | --- |
| getMessageId | String | Unique ID of message |
| getObservableTimeStamp | Observable(of Date) | Server UTC timestamp of message |
| getObservableFrom | Observable(of [ChatUser](/content/docs/sdk_ref/android/chat/#chatuser/index.html)) | 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](/content/docs/sdk_ref/android/sdk-room/#member-roles/index.html) |
| 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](/content/docs/sdk_ref/android/chat/#chat-message-history/index.html) 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";

### 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](/content/docs/sdk_ref/android/chat/#roomchatservice/index.html) | The chat service making the callback |
| messages | [ChatMessage](/content/docs/sdk_ref/android/chat/#chatmessage/index.html)\[\] | 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 |
