Getting Inbox with the JS SDK

Overview

One of the key differences between the current implementations of the iOS SDK, Android SDK, and JS SDK is that the JS SDK does not download every message locally when the user logs in. This results in a noticeable performance improvement to login and page load times, and an improved user experience.

Instead, the client.conversations.selectConversation() call, documented below, must be called in order to retrieve messages for a single conversation.

When the roster is fetched, it will automatically download information about the last message sent or received in the conversation.

Fetching The Roster

The conversations.findAll() method retrieves the roster, which is a list of all Conversations that the current user is a part of.

Calling this method automatically loads any User and Group models that are part of these conversations.

The roster should usually be narrowed according to Organization, and to this effect each organization has a conversations field which contains their part of the roster.

Definition

client.conversations.findAll():Promise<Conversation[],Error>

Returns

An error will be thrown if any of the arguments are invalid.

Otherwise, once the returned Promise is resolved, you will have access to the array of Conversations.

Examples

const conversations = await client.conversations.findAll();
console.log('found', conversations.length, 'conversations');
conversations.forEach(function(conversation) {
  if (
    conversation.counterPartyType === 'user' ||
    conversation.counterPartyType === 'distributionList'
  ) {
    console.log(conversation.counterParty.displayName);
  } else if (conversation.counterPartyType == 'group') {
    console.log(
      conversation.counterParty.displayName,
      'group, members:',
      conversation.counterParty.members
        .map(function(user) {
          return user.displayName;
        })
        .join(', ')
    );
  }
});

Selecting a Single Conversation

The conversations.selectConversation() method, given a conversation ID and a minItemsToFetch parameter, calls client.conversations.fetchTimeline() repeatedly until at least that number of timeline items are loaded into conversation.timeline.

The conversation.timeline array includes all messages and bangs that were fetched for the conversation.

This method will load messages first in the higher direction using conversation.higherContinuation and then in the lower direction using conversation.lowerContinuation as needed to fulfill the desired minimum value.

If markAsRead=true is supplied, the messages will appear to be Read immediately (we call this the "optimistic status"), and then a server call will be made, and then the results of the server call will be reconciled with that optimistic status.

If fetchAllItems=true is supplied, then all unexpired messages will be fetched for the conversation, this will be defaulted to false.

Please note that in Conversation models affected by these calls, the values of conversation.lowerContinuation.itemsEstimate and conversation.higherContinuation.itemsEstimate will only be either 0 (which means "no more messages are in this direction") or a number greater than zero (which means "one or more messages may be present in this direction"). If exactly maxItems number of messages are fetched in the conversation, it is possible that the SDK may return a number greater than zero even if there are no more messages left, in which case the next attempt to follow the continuation in that direction will yield no messages and change the value of itemsEstimate to 0; the SDK makes an attempt to minimize the number of cases where this can happen.

Definition

await client.conversations.selectConversation(
  conversationId: string|Conversation,
  options: ?Object
):Promise<Object,Error>

Parameters

Options

Returns

The function returns a Promise with an object containing the number of items that were added to the Timeline and a message object which represents the previous first unread message. This function will also assign conversation.lowerContinuation and conversation.higherContinuation, you can find the description for those fields in the Conversation model.

Examples

• conversation.timeline = []
• Messages 1, 2, 3 are Read
• Message 4, 5, 6, 7, 8, 9, 10 are New

const {
  addedMessages,
  previousFirstUnreadMessage
} = await client.conversations.selectConversation(
  conversationId,
  {
    anchorPoint: 'FIRST_UNREAD_ITEM',
    minItemsToFetch: 8
  }
);
console.log(`added ${addedMessages} messages to the conversation`);
const conversation = client.conversations.getById(conversationId);
if (conversation.lowerContinuation.itemsEstimate > 0) {
  console.log('there may be more messages in the lower (historical) direction');
}
if (conversation.higherContinuation.itemsEstimate > 0) {
  console.log('there may be more messages in the higher (future) direction');
}

Result:

• conversation.timeline = [3, 4, 5, 6, 7, 8, 9, 10]
• This could also include more messages, depending on implementation
• conversation.lowerContinuation.continuation = lower_continuation_A
• conversation.lowerContinuation.itemsEstimate = 1
• conversation.higherContinuation.continuation = higher_continuation_B
• conversation.higherContinuation.itemsEstimate = 0