conversations.fetchTimeline()
The conversations.fetchTimeline()
method loads paginated conversation content into the conversation.timeline
array.
The conversation.timeline
array includes all messages and bangs that were fetched for the conversation.
Contrast to client.conversations.selectConversation(), which repeatedly calls fetchTimeline()
until a minimum number of items are reached, and also can mark messages as Read.
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.fetchTimeline(conversationId: string|Conversation,options: ?Object):Promise<number,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 = CONTINUATION | ?string | Follow the provided continuation, which can be either a lowerContinuation or higherContinuation from a previous request |
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 |
continuation | ?string | A continuation string to follow, only used if anchorPoint is CONTINUATION |
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. |
maxItems | ?number | Maximum number of items to return (default: 15 ). If this is larger than what the server can support for performance reasons, then the server should round this value down to the highest supported value instead of throwing an error. |
Returns
The function returns a Promise
with the number of items that were added to the Timeline and will also assign conversation.lowerContinuation
and conversation.higherContinuation
. You can find the description for those fields in the Conversation model.
Examples
Example 1:
- conversation.timeline = []
- Messages 1, 2, 3 are Read
- Message 4, 5, 6, 7, 8, 9, 10 are New
const addedMessages = await client.conversations.fetchTimeline(conversationId,{anchorPoint: client.enums.ConversationAnchorPoints.FIRST_UNREAD_ITEM,maxItems: 3});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 = [4, 5, 6]
- conversation.lowerContinuation.continuation =
lower_continuation_A
- conversation.lowerContinuation.itemsEstimate = 1
- conversation.higherContinuation.continuation =
higher_continuation_A
- conversation.higherContinuation.itemsEstimate = 1
const addedMessages = await client.conversations.fetchTimeline(conversationId,{anchorPoint: client.enums.ConversationAnchorPoints.CONTINUATION,continuation: conversation.higherContinuation.continuationmaxItems: 10});
Result:
- conversation.timeline = [4 ,5, 6, 7, 8 ,9, 10]
- conversation.lowerContinuation.continuation =
lower_continuation_A
- conversation.lowerContinuation.itemsEstimate = 1
- conversation.higherContinuation.continuation =
higher_continuation_B
- conversation.higherContinuation.itemsEstimate = 0
Example 2:
- conversation.timeline = []
- Messages in conversation 1, 2, 3, 4 ,5, 6, 7, 8, 9, 10
const addedMessages = await client.conversations.fetchTimeline(conversationId,{anchorPoint: client.enums.ConversationAnchorPoints.CONVERSATION_END,maxItems: 2});
Result:
- conversation.timeline = [9, 10]
- conversation.lowerContinuation.continuation =
lower_continuation_A
- conversation.lowerContinuation.itemsEstimate = 1
- conversation.higherContinuation.continuation =
higher_continuation_A
- conversation.higherContinuation.itemsEstimate = 0
const addedMessages = await client.conversations.fetchTimeline(conversationId,{anchorPoint: client.enums.ConversationAnchorPoints.CONTINUATION,continuation: conversation.lowerContinuation.continuationmaxItems: 5});
Result:
- conversation.timeline = [4 ,5, 6, 7, 8 ,9, 10]
- conversation.lowerContinuation.continuation =
lower_continuation_B
- conversation.lowerContinuation.itemsEstimate = 1
- conversation.higherContinuation.continuation =
higher_continuation_A
- conversation.higherContinuation.itemsEstimate = 0