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.continuation
    maxItems: 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.continuation
    maxItems: 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