conversations.selectConversation()

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