Get Stories

Story retrieval APIs return live objects or live collections. Use a single-story API when you already have a storyId, active-story APIs for a target’s current stories, and multi-target APIs when building a story tray across communities.

Parameters

Operation	Parameter	Required	Description
Single story	`storyId`	Yes	Story ID to observe as a live object or stream.
Active stories for a target	`targetType`	Yes	Story target type, such as community.
Active stories for a target	`targetId`	Yes	Target ID whose active stories should be retrieved.
Active stories for a target	Sort/order option	No	Sort order for returned active stories where exposed.
Stories across targets	`targets`	Yes	Target type and target ID pairs to retrieve in one request.
Stories across targets	Sort/order option	No	Sort order for returned stories where exposed.

Single Story

Observe a single story when your UI already has a storyId and needs live story state.

import { StoryRepository } from '@amityco/ts-sdk';

const unsubscribe = StoryRepository.getStoryByStoryId(storyId, ({ data, loading, error }) => {
  if (error) {
    handleError(error);
    return;
  }

  if (!loading && data) {
    updateUI(data);
  }
});

unsubscribe();

token = storyRepository.getStory(storyId: "story-id").observe { object, error in
    if let error {
        handleError(error)
        return
    }

    if let story = object.snapshot {
        showSuccessMessage(story.storyId)
    }
}

fun observeStory(
    storyRepository: AmityStoryRepository,
    storyId: String
) {
    storyRepository.getStory(storyId = storyId)
        .doOnNext { story: AmityStory ->
            showSuccessMessage(story.getStoryId())
        }
        .doOnError { error -> showErrorMessage(error = error) }
        .subscribe()
}

void observeStory(String storyId) {
  final stream = AmitySocialClient.newStoryRepository().live.getStory(storyId);

  stream.listen((story) {
    final currentStoryId = story.storyId;
    showError(currentStoryId ?? '');
  });
}

Active Stories for a Target

Active-story APIs retrieve non-expired stories for one target. They are the usual choice for rendering a viewer after the user opens a story ring.

import { StoryRepository } from '@amityco/ts-sdk';

const unsubscribe = StoryRepository.getActiveStoriesByTarget(
  {
    targetType: 'community',
    targetId: communityId,
    options: {
      sortBy: 'createdAt',
      orderBy: 'desc',
    },
  },
  ({ data, loading, error }) => {
    if (error) {
      handleError(error);
      return;
    }

    if (!loading) {
      renderResults(data);
    }
  },
);

unsubscribe();

token = storyRepository
    .getActiveStoriesByTarget(
        targetType: .community,
        targetId: communityId,
        sortOption: .lastCreated
    )
    .observe { collection, error in
        if let error {
            handleError(error)
            return
        }

        showSuccessMessage(collection.snapshots.count)
    }

fun observeActiveStories(
    storyRepository: AmityStoryRepository,
    targetId: String
) {
    storyRepository.getActiveStories(
        targetType = AmityStory.TargetType.COMMUNITY,
        targetId = targetId,
        sortOption = AmityStorySortOption.LAST_CREATED
    )
        .doOnNext { stories: PagingData<AmityStory> ->
            getPagingData(stories)
        }
        .doOnError { error -> showErrorMessage(error = error) }
        .subscribe()
}

void observeActiveStories(String communityId) {
  final collection = StoryLiveCollection(
    request: () => AmitySocialClient.newStoryRepository()
        .getActiveStories(
          targetId: communityId,
          targetType: AmityStoryTargetType.COMMUNITY,
          orderBy: AmityStorySortingOrder.LAST_CREATED,
        )
        .build(),
  );

  collection.getStreamController().stream.listen((stories) {
    final visibleCount = stories.length;
    showError(visibleCount);
  });

  collection.getData();
}

Stories Across Targets

Use the multi-target APIs when you need stories from multiple targets in one live collection.

import { StoryRepository } from '@amityco/ts-sdk';

const unsubscribe = StoryRepository.getStoriesByTargetIds(
  {
    targets: [
      { targetType: 'community', targetId: communityId },
      { targetType: 'community', targetId: 'community-id-2' },
    ],
    options: {
      sortBy: 'createdAt',
      orderBy: 'desc',
    },
  },
  ({ data, loading, error }) => {
    if (error) {
      handleError(error);
      return;
    }

    if (!loading) {
      renderResults(data);
    }
  },
);

unsubscribe();

let targets = [
    AmityStoryTargetSearchInfo(targetType: .community, targetId: communityId),
    AmityStoryTargetSearchInfo(targetType: .community, targetId: "community-id-2")
]

token = storyRepository
    .getStoriesByTargets(targets: targets, sortOption: .lastCreated)
    .observe { collection, error in
        if let error {
            handleError(error)
            return
        }

        showSuccessMessage(collection.snapshots.count)
    }

fun observeStoriesByTargets(storyRepository: AmityStoryRepository) {
    val targets = listOf(
        AmityStory.TargetType.COMMUNITY to "community-id-1",
        AmityStory.TargetType.COMMUNITY to "community-id-2"
    )

    storyRepository.getStoriesByTargets(
        targets = targets,
        sortOption = AmityStorySortOption.LAST_CREATED
    )
        .doOnNext { stories: List<AmityStory> ->
            showSuccessMessage(stories.size)
        }
        .doOnError { error -> showErrorMessage(error = error) }
        .subscribe()
}

void observeStoriesByTargets() {
  final targets = [
    StoryTargetSearchInfo(
      targetType: AmityStoryTargetType.COMMUNITY,
      targetId: 'community-id-1',
    ),
    StoryTargetSearchInfo(
      targetType: AmityStoryTargetType.COMMUNITY,
      targetId: 'community-id-2',
    ),
  ];

  final collection = StoryLiveCollection(
    request: () => AmitySocialClient.newStoryRepository()
        .getStoriesByTargets(
          targets: targets,
          orderBy: AmityStorySortingOrder.LAST_CREATED,
        )
        .build(),
  );

  collection.getStreamController().stream.listen((stories) {
    final visibleCount = stories.length;
    showError(visibleCount);
  });

  collection.getData();
}

Notes

Active-story APIs include local optimistic stories where the platform SDK supports optimistic creation.
Multi-target APIs return synced stories across the requested targets.
Use story target APIs when you only need ring state such as hasUnseen.

Get Story Targets

Retrieve target-level story availability and unseen state.

Story Impressions

Track views and reached users for stories.

Powered by

Getting Started

Fundamentals

Social

Chat

Video

Release Notes

Migration Guides

Support

Parameters

Single Story

Active Stories for a Target

Stories Across Targets

Notes

Get Story Targets

Story Impressions

​Parameters

​Single Story

​Active Stories for a Target

​Stories Across Targets

​Notes

​Related Topics

Get Story Targets

Story Impressions

Parameters

Single Story

Active Stories for a Target

Stories Across Targets

Notes

Related Topics