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

NameTypeDescription
conversationIdstring|ConversationA conversation ID
options?ObjectOptions (described below)

Options

NameTypeDescription
anchorPoint = FIRST_UNREAD_ITEM?stringAnchor the results to the unread conversation item with the lowest sortNumber in that conversation.
anchorPoint = CONTINUATION?stringFollow the provided continuation, which can be either a lowerContinuation or higherContinuation from a previous request
anchorPoint = CONVERSATION_END (default)?stringAnchor the results to the end of the conversation and provide a page of results which end with the last item of the conversation
continuation?stringA continuation string to follow, only used if anchorPoint is CONTINUATION
markAsDelivered?booleanWhether 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?numberMaximum 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