Create Story

Use the story repository to create image or video stories for a target. The examples below use community targets, optional metadata, and an optional hyperlink story item. Story creation is optimistic on the SDKs that maintain local story state. Watch the returned story or active story collection for sync state changes such as syncing, synced, or failed.

Parameters

Concept	TypeScript	iOS	Android	Flutter
Target type	`'community'`	`.community`	`AmityStory.TargetType.COMMUNITY`	`AmityStoryTargetType.COMMUNITY`
Target ID	`string`	`String`	`String`	`String`
Image input	`FormData` with `files`	`imageFileURL`	`imageUri`	`imageFile`
Video input	`FormData` with `files`	`videoFileURL`	`videoUri`	`videoFile`
Metadata	Object	`[String: Any]?`	`JsonObject?`	`Map<String, dynamic>?`
Hyperlinks	`Amity.StoryItemType.Hyperlink`	`AmityHyperLinkItem`	`AmityStoryItem.HYPERLINK`	`HyperLink`

For TypeScript, append the file under the files key. The SDK throws if the FormData object has no files entry.

Create image story

Create an image story from a local image file, target, and optional metadata or hyperlink items.

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

const formData = new FormData();
formData.append('files', imageFile);

const result = await StoryRepository.createImageStory(
  'community',
  communityId,
  formData,
  { campaignId: 'launch' },
  'fit',
  [
    {
      type: Amity.StoryItemType.Hyperlink,
      data: {
        url: 'https://example.com',
        customText: 'Learn more',
      },
    },
  ],
);

renderResults(result.data);

let items: [AmityStoryItem] = [
    AmityHyperLinkItem(url: "https://example.com", customText: "Learn more")
]

let imageURL = URL(fileURLWithPath: "/path/to/image.jpg")
let options = AmityImageStoryCreateOptions(
    targetType: .community,
    targetId: communityId,
    imageFileURL: imageURL,
    metadata: ["campaignId": "launch"],
    items: items,
    imageDisplayMode: .fit
)

let story = try await storyRepository.createImageStory(options: options)
showSuccessMessage(story.storyId)

fun createImageStory(
    storyRepository: AmityStoryRepository,
    targetId: String,
    imageUri: Uri
) {
    storyRepository.createImageStory(
        targetType = AmityStory.TargetType.COMMUNITY,
        targetId = targetId,
        imageUri = imageUri,
        storyItems = listOf(
            AmityStoryItem.HYPERLINK(
                url = "https://example.com",
                customText = "Learn more"
            )
        ),
        imageDisplayMode = AmityStoryImageDisplayMode.FIT,
        metadata = JsonObject().apply {
            addProperty("campaignId", "launch")
        }
    )
        .doOnComplete { showSuccessMessage("Story created") }
        .doOnError { error -> showErrorMessage(error = error) }
        .subscribe()
}

import 'dart:io';

Future<void> createImageStory(String communityId) async {
  final storyRepository = AmitySocialClient.newStoryRepository();

  await storyRepository.createImageStory(
    targetType: AmityStoryTargetType.COMMUNITY,
    targetId: communityId,
    imageFile: File('/path/to/image.jpg'),
    imageDisplayMode: AmityStoryImageDisplayMode.FIT,
    metadata: {'campaignId': 'launch'},
    storyItems: [
      HyperLink(
        url: 'https://example.com',
        customText: 'Learn more',
      ),
    ],
  );
}

Create video story

Create a video story from a local video file, target, and optional metadata or hyperlink items.

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

const formData = new FormData();
formData.append('files', videoFile);

const result = await StoryRepository.createVideoStory(
  'community',
  communityId,
  formData,
  { campaignId: 'launch' },
  [
    {
      type: Amity.StoryItemType.Hyperlink,
      data: {
        url: 'https://example.com',
        customText: 'Watch more',
      },
    },
  ],
);

renderResults(result.data);

let items: [AmityStoryItem] = [
    AmityHyperLinkItem(url: "https://example.com", customText: "Watch more")
]

let videoURL = URL(fileURLWithPath: "/path/to/video.mp4")
let options = AmityVideoStoryCreateOptions(
    targetType: .community,
    targetId: communityId,
    videoFileURL: videoURL,
    metadata: ["campaignId": "launch"],
    items: items
)

let story = try await storyRepository.createVideoStory(options: options)
showSuccessMessage(story.storyId)

fun createVideoStory(
    storyRepository: AmityStoryRepository,
    targetId: String,
    videoUri: Uri
) {
    storyRepository.createVideoStory(
        targetType = AmityStory.TargetType.COMMUNITY,
        targetId = targetId,
        videoUri = videoUri,
        storyItems = listOf(
            AmityStoryItem.HYPERLINK(
                url = "https://example.com",
                customText = "Watch more"
            )
        ),
        metadata = JsonObject().apply {
            addProperty("campaignId", "launch")
        }
    )
        .doOnComplete { showSuccessMessage("Story created") }
        .doOnError { error -> showErrorMessage(error = error) }
        .subscribe()
}

import 'dart:io';

Future<void> createVideoStory(String communityId) async {
  final storyRepository = AmitySocialClient.newStoryRepository();

  await storyRepository.createVideoStory(
    targetType: AmityStoryTargetType.COMMUNITY,
    targetId: communityId,
    videoFile: File('/path/to/video.mp4'),
    metadata: {'campaignId': 'launch'},
    storyItems: [
      HyperLink(
        url: 'https://example.com',
        customText: 'Watch more',
      ),
    ],
  );
}

Hyperlink items

Story hyperlink items contain:

Field	Description
`url`	Destination URL.
`customText`	Optional text shown for the link.

Get Stories

Observe created stories and sync state.

Story Impressions

Mark synced stories as seen and track link clicks.

Powered by

Getting Started

Fundamentals

Social

Chat

Video

Release Notes

Migration Guides

Support

Parameters

Create image story

Create video story

Hyperlink items

Get Stories

Story Impressions

​Parameters

​Create image story

​Create video story

​Hyperlink items

​Related topics

Get Stories

Story Impressions

Parameters

Create image story

Create video story

Hyperlink items

Related topics