Skip to main content
Create engaging text posts with support for mentions, hashtags, and custom metadata. Text posts are the foundation of social interaction, perfect for sharing thoughts, updates, and conversations.

Rich Text Support

Up to 20,000 characters with mentions and hashtags

Flexible Targeting

Post to user feeds, communities, or your own timeline

​
Overview

Text posts provide a clean, straightforward way to share written content:
  • Text Support: Up to 20,000 characters per post
  • Mentions: Tag other users with @displayname syntax
  • Hashtags: Categorize content with #hashtag syntax
  • Custom Metadata: Add additional structured data
  • Flexible Targeting: Post to user feeds or communities
  • No Structure Type: Text-only posts don’t have a structureType field

​
Understanding Post Structure Types

New Concept: Posts now have a structureType field that describes their media composition. This enables precise content filtering and better content discovery.
Text-only posts are unique in the post structure type system:
  • Text-Only Posts
  • Posts with Attachments
Structure Type: null or absentWhen you create a text post without any attachments (images, videos, audio, or files), the post does not have a structureType value. This distinguishes pure text content from media-rich posts.
// Text-only post example
const textPost = {
  data: { text: "Hello, world!" },
  targetType: "user",
  targetId: "user123"
};
// Result: structureType = null (no attachments)

​
How Structure Types Affect Queries

The structureType field enables powerful content filtering: 
// Query all posts (including text-only)
const allPosts = await PostRepository.getPosts({
  // No dataTypes filter = returns all posts
});

// Query posts with specific media types
const imagePosts = await PostRepository.getPosts({
  dataTypes: ['image']
  // Returns only pure image posts (structureType = "image")
  // Excludes mixed posts by default
});

// Query including mixed media posts
const imageAndMixedPosts = await PostRepository.getPosts({
  dataTypes: ['image'],
  includeMixedStructure: true
  // Returns both pure image posts AND mixed posts containing images
});
For complete details on post structure types and filtering, see Mixed Media Posts.

​
Parameters

ParameterTypeRequiredDescription
textString✅Text content (max 20,000 characters)
targetTypeEnum✅Target type (user or community)
targetIdString✅Target ID (userId or communityId)
metadataObject❌Custom metadata for the post
mentionUsersArray<String>❌User IDs to mention in the post
let builder = AmityTextPostBuilder()
builder.setText("ABC")
// Create a post from builder
do {
    let post = try await postRepository.createTextPost(builder, targetId: nil, targetType: .user, metadata: nil, mentionees: nil)
} catch {
    // Handle error here
}

​
Best Practices

  • Keep text concise and engaging
  • Use mentions sparingly to avoid spam
  • Add relevant hashtags for discoverability
  • Include context for better user engagement
  • Validate text length before submission
  • Handle network errors gracefully
  • Provide user feedback during creation
  • Cache drafts for better user experience
  • Show character count indicators
  • Provide auto-complete for mentions
  • Suggest relevant hashtags
  • Allow draft saving and editing

​
Troubleshooting

Problem: Post creation fails with text length errorSolution: Ensure text content is under 20,000 characters
if (text.length > 20000) {
  throw new Error('Text exceeds maximum length of 20,000 characters');
}
Problem: Mentions not working properlySolution: Use correct format with @username (no spaces in username)
// ✅ Correct
"Hello @john-doe, how are you?"

// ❌ Incorrect  
"Hello @john doe, how are you?"
Problem: Post fails with invalid target errorSolution: Verify target exists and user has permission to post
// For community posts, ensure user is a member
const isMember = await CommunityRepository.isMember(communityId, userId);
if (!isMember) {
  throw new Error('User must be a community member to post');
}

​
Common Use Cases

  • Status Updates: Share personal thoughts and experiences
  • Community Discussions: Start conversations in community feeds
  • Announcements: Broadcast important information
  • Questions: Ask for advice or opinions from followers
  • Storytelling: Share experiences and narratives
  • Links Sharing: Share URLs with context and commentary

Image Posts

Create posts with photos and visual content

Video Posts

Share video content and multimedia experiences

Audio Posts

Share audio content like podcasts and music

File Posts

Share documents and file attachments

Mixed Media Posts

Combine multiple media types in one post

Post Management

Edit, delete, and moderate your published posts