Skip to main content
SDK v7.x · Last verified March 2026 · iOS · Android · Web · Flutter
// 1. Create an image story
await StoryRepository.createImageStory({
  targetType: 'community', targetId: 'communityId',
  imageFileId: 'uploaded-image-id',
});

// 2. Create a video story
await StoryRepository.createVideoStory({
  targetType: 'community', targetId: 'communityId',
  videoFileId: 'uploaded-video-id',
});

// 3. Query active stories
StoryRepository.getActiveStories('communityId',
  ({ data }) => { /* render story ring */ }
);

// 4. Mark as seen
await StoryRepository.markStorySeen('storyId');
Full walkthrough below ↓
Platform note — code samples below use TypeScript. Every method has an equivalent in the iOS (Swift), Android (Kotlin), and Flutter (Dart) SDKs — see the linked SDK reference in each step.
Stories are 24-hour ephemeral content units that drive daily active usage. This guide covers creating image and video stories, rendering story rings, tracking views and impressions, and targeting stories to users or communities.
Prerequisites: SDK installed and authenticated. For video stories: video upload configured → Video Handling. You’ll need a targetType (user or community) and targetId.Also recommended: Complete User Profiles & Social Graph — stories target user profiles and communities.
After completing this guide you’ll have:
  • Image and video story creation targeting communities and user profiles
  • Story ring display with viewed/unviewed state on avatars
  • Per-story view count and impression data accessible

​
Limits at a Glance

PropertyLimit
Story lifespan24 hours (auto-deleted)
Max image size1 GB
Max video size1 GB
Max video duration2 minutes
Target typesuser or community
Hyperlinks per story1
Story typesimage or video

​
Quick Start: Create an Image Story

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

const formData = new FormData();
formData.append('files', imageFile); // imageFile from <input type="file">

await StoryRepository.createImageStory(
  'community',
  'communityId',
  formData,
  {}, // metadata - optional
  'fit', // 'fit' or 'fill'
  [
    {
      type: Amity.StoryItemType.Hyperlink,
      data: { url: 'https://example.com', customText: 'Learn more' },
    },
  ],
);

​
Step-by-Step Implementation

1

Get story targets (story rings)

Story targets are the entities (users or communities) that have active stories. Each target has a hasUnseenStory flag you can use to highlight the ring.
TypeScript
import { StoryRepository } from '@amityco/ts-sdk';

const unsubscribe = StoryRepository.getStoriesByTargetIds(
  {
    targets: [
      { targetType: 'community', targetId: 'communityId_1' },
      { targetType: 'community', targetId: 'communityId_2' },
    ],
    options: { orderBy: 'asc' },
  },
  ({ data: storiesData, loading }) => {
    if (storiesData) { /* render story rings */ }
  },
);
Full reference → Get Story Targets
2

Get global story targets (explore/discover)

For an explore page, query all communities with active stories.
TypeScript
import { StoryRepository } from '@amityco/ts-sdk';

const unsubscribe = StoryRepository.getGlobalStoryTargets(
  { seenState: Amity.StorySeenQuery.SMART, limit: 10 },
  ({ data, onNextPage, hasNextPage }) => {
    /* render explore story bar */
  },
);
Full reference → Get Global Story Targets
3

Get stories for a target

Query individual stories for a specific user or community to display in the full-screen viewer.
TypeScript
const unsubscribe = StoryRepository.getActiveStoriesByTarget(
  { targetType: 'community', targetId: 'communityId' },
  ({ data: stories, loading }) => {
    if (stories) { /* open full-screen story viewer */ }
  },
);
Full reference → Get Stories
4

Track story impressions

When a story is shown full-screen, call markAsSeen() to record the view impression. View analytics in Admin Console → Social Management → Stories.
TypeScript
// Inside the story viewer callback:
storiesData.forEach(storyItem => {
  if (storyItem) storyItem.analytics.markAsSeen();
});
Full reference → Story Impressions
5

Add reactions to stories

Stories support the same reaction system as posts. Use ReactionRepository with referenceType: 'story' and the story ID.
TypeScript
import { ReactionRepository } from '@amityco/ts-sdk';

// Add a reaction to a story
await ReactionRepository.addReaction('story', 'storyId', 'like');

// Remove a reaction
await ReactionRepository.removeReaction('story', 'storyId', 'like');
Full reference → Reactions

​
Connect to Moderation & Analytics

View total views, unique viewers, and per-story impression data in Admin Console → Social Management → Stories. Programmatic access via story.impressions in the SDK.→ Story Impressions
Users can flag inappropriate stories. Flagged stories appear in the Admin Console for moderator action.→ Content Flagging
Per-community story settings control whether comments are allowed on community stories. Configure in the Admin Console or via the SDK when creating/updating a community.→ Create Community

​
Common Mistakes

Uploading full-resolution images without compression — Stories are short-lived content. Uploading 4K images wastes bandwidth and slows story rings. Compress to ~1080p before uploading.
Not checking story expiration client-side — The API returns active stories, but network delays can cause a story to expire between fetch and render. Always check story.expiresAt before displaying.
Polling for new stories instead of subscribing — Stories update frequently. Use Live Collections to observe story changes instead of polling on a timer, which wastes battery and bandwidth.

​
Best Practices

  • Use a colored ring for unseen stories, a grey/transparent ring for fully seen stories
  • Order story rings: currently-active user’s story → friends → communities
  • Show a ”+” button on the current user’s ring to open the creation flow
  • Animate the ring on tap to give tactile feedback before opening the viewer
  • Auto-advance to the next story after ~5-7 seconds for images, or at video end
  • Allow tap-left / tap-right to navigate between stories
  • Show a progress bar across the top of the viewer for each story segment
  • Pause auto-advance when the user long-presses (hold to read)
  • Pre-fetch stories for the first 3 targets in the story ring so they open instantly
  • Compress images to ≤1MB before upload — story images are full-screen and load time matters
  • For video stories, start downloading the next story’s video while the current one plays
Dive deeper: Stories API Reference has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

​
Next Steps

Your next step → Notifications & Engagement

Stories are live — now set up push notifications so followers know when new stories are posted.
Or explore related guides:

Rich Content Creation

Create posts alongside stories for a complete content loop

Notifications & Engagement

Notify users when someone reacts to their story

Build a Social Feed

Combine a story bar at the top of the feed