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
Name | Type | Description |
---|---|---|
conversationId | string |Conversation | A conversation ID |
options | ?Object | Options (described below) |
Options
Name | Type | Description |
---|---|---|
anchorPoint = FIRST_UNREAD_ITEM | ?string | Anchor the results to the unread conversation item with the lowest sortNumber in that conversation. |
anchorPoint = CONVERSATION_END (default) | ?string | Anchor the results to the end of the conversation and provide a page of results which end with the last item of the conversation |
fetchAllItems = false (default) | ?boolean | Call client.conversations.fetchTimeline() repeatedly until all messages are returned |
markAsDelivered | ?boolean | Whether to automatically mark fetched items as Delivered (default: true ). At this time, the parameter is ignored, and the fetched messages will always be marked as Delivered. Please contact your TigerConnect support representative if you are interested in being able to fetch messages without automatically marking them as Delivered. |
markAsRead | ?boolean | Whether to automatically mark fetched items as Read (default: true ); when this and markAsDelivered are both true, fetched items will be marked as Read instead of Delivered. |
maxItemsPerBatch | ?number | How many items to retrieve (default: the value of the minItemsToFetch argument) for each fetchTimeline() call |
minItemsToFetch | ?number | Call client.conversations.fetchTimeline() repeatedly until at least this many items (default: 20) are returned |
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.
Name | Type | Description |
---|---|---|
addedMessages | number | Number of items that were added to the Timeline |
previousFirstUnreadMessage | Message | A message model representing the firstUnreadMessage before all messages in this conversation are marked as 'Read' |
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