Skip to main content
Create specialized content types beyond standard posts with flexible schemas and structured data. Perfect for e-commerce, real estate, events, or any unique use case requiring custom rendering.

Flexible Schema

Define your own data structure with up to 100KB JSON payload

Custom Rendering

Full control over how content appears in feeds and apps

​
Overview

Custom posts enable you to create specialized content types beyond standard text, image, video, and file posts. Build unique experiences for e-commerce, events, real estate, or any structured content that requires custom rendering.

​
Key Features

Flexible Schema

Define your own data structure

Custom Rendering

Full control over appearance

Rich Metadata

Include complex structured data

Large Payload

Up to 100KB of custom data
1

Design Schema

Define your custom data structure and required fields
2

Create Post

Use the custom dataType and structured JSON data
3

Implement Rendering

Build custom UI components to display your content
The dataType parameter must have the custom prefix (e.g., “custom.recipe”, “custom.product”).

​
Parameters

ParameterTypeRequiredDescription
dataTypeString✅Custom type identifier (must start with “custom”)
dataObject✅Free-form JSON object with your custom structure
targetTypeEnum✅Target type (user or community)
targetIdString✅Target ID (userId or communityId)
textString❌Optional text content
metadataObject❌Additional properties
let builder = AmityCustomPostBuilder()
builder.setDataType("custom.mycustomtype") // Data type should be in this pattern custom.*
builder.setData([
    "favourite_color" : "Red",
    "favourite_food" : "Pizza"
])

// Create a post from builder
do {
    let post = try await postRepository.createCustomPost(builder, targetId: "feed-id", targetType: .community, metadata: nil, mentionees: nil)
} catch {
    // Handle error here
}

​
Data Structure Examples

{
    "dataType": "custom.product",
    "data": {
        "title": "Wireless Headphones",
        "price": 149.99,
        "currency": "USD",
        "brand": "AudioTech",
        "model": "WT-200",
        "category": "electronics",
        "subcategory": "audio",
        "features": [
            "Noise cancellation",
            "30-hour battery",
            "Bluetooth 5.0"
        ],
        "specifications": {
            "weight": "250g",
            "color_options": ["black", "white", "blue"],
            "warranty": "2 years"
        },
        "availability": {
            "in_stock": true,
            "quantity": 15,
            "shipping": {
                "free_shipping": true,
                "estimated_days": 3
            }
        }
    }
}

{
    "dataType": "custom.property",
    "data": {
        "title": "Modern Downtown Apartment",
        "price": 450000,
        "currency": "USD",
        "property_type": "apartment",
        "listing_type": "sale",
        "details": {
            "bedrooms": 2,
            "bathrooms": 2,
            "square_feet": 1200,
            "year_built": 2018
        },
        "location": {
            "address": "123 Main Street",
            "city": "San Francisco",
            "state": "CA",
            "zip": "94105",
            "coordinates": {
                "lat": 37.7749,
                "lng": -122.4194
            }
        },
        "amenities": [
            "Gym",
            "Rooftop deck",
            "Parking",
            "Pet-friendly"
        ],
        "agent": {
            "name": "Jane Smith",
            "phone": "+1-555-0123",
            "email": "[email protected]"
        }
    }
}

{
    "dataType": "custom.course",
    "data": {
        "title": "Advanced React Development",
        "instructor": "John Doe",
        "description": "Master advanced React patterns and best practices",
        "level": "advanced",
        "duration": {
            "hours": 40,
            "weeks": 8
        },
        "pricing": {
            "regular_price": 299,
            "sale_price": 199,
            "currency": "USD"
        },
        "curriculum": [
            {
                "module": 1,
                "title": "Advanced Hooks",
                "lessons": 6
            },
            {
                "module": 2,
                "title": "Performance Optimization",
                "lessons": 8
            }
        ],
        "requirements": [
            "Basic React knowledge",
            "JavaScript ES6+",
            "Node.js familiarity"
        ],
        "enrollment": {
            "start_date": "2024-07-01",
            "max_students": 50,
            "current_enrolled": 23
        }
    }
}
When designing custom post types, consider how they’ll appear in feeds on different platforms and devices. Always include meaningful text content as a fallback for better accessibility and user experience.

​
Best Practices

  • Keep JSON payload under 100KB for optimal performance
  • Use consistent naming conventions (snake_case or camelCase)
  • Include version fields for schema evolution
  • Document your schema structure for team collaboration
  • Validate data structure before posting
  • Design for extensibility - plan for future additions
  • Use nested objects for complex related data
  • Include metadata like timestamps, versions, and IDs
  • Consider data types carefully (strings vs numbers vs booleans)
  • Implement graceful degradation for missing fields
  • Provide fallback rendering for unsupported clients
  • Include descriptive text content as backup
  • Use appropriate tags for discoverability
  • Design mobile-friendly data structures
  • Consider accessibility in custom rendering
  • Optimize JSON structure to minimize payload size
  • Cache frequently accessed custom data
  • Index searchable fields appropriately
  • Consider lazy loading for complex custom content
  • Monitor custom post performance and user engagement

​
Troubleshooting

Problem: Custom post creation fails with dataType validation errorSolutions:
  • Ensure dataType starts with “custom.” prefix
  • Use only alphanumeric characters and dots in dataType
  • Avoid spaces or special characters in dataType names
  • Follow the pattern: custom.yourtype (e.g., custom.product, custom.event)
// ✅ Correct dataType formats
"custom.product"
"custom.event"
"custom.recipe"
"custom.job_listing"

// ❌ Invalid dataType formats
"product"           // Missing custom prefix
"custom product"    // Contains space
"custom.my-type"    // Contains hyphen
Problem: Post creation fails due to data size exceeding 100KB limitSolutions:
  • Reduce data structure complexity
  • Move large content (images, files) to separate uploads
  • Use references/IDs instead of embedding large objects
  • Compress or optimize JSON structure
// Check payload size before posting
const dataString = JSON.stringify(customData);
const sizeInKB = new Blob([dataString]).size / 1024;

if (sizeInKB > 100) {
  console.warn(`Payload too large: ${sizeInKB}KB. Consider optimizing.`);
  // Optimize or split data
}
Problem: Custom data doesn’t match expected schema or contains invalid valuesSolutions:
  • Implement client-side validation before posting
  • Use consistent data types across all fields
  • Handle null/undefined values gracefully
  • Provide clear error messages for validation failures
// Example validation function
const validateProductData = (data) => {
  const errors = [];
  
  if (!data.title || typeof data.title !== 'string') {
    errors.push('Title is required and must be a string');
  }
  
  if (data.price !== undefined && typeof data.price !== 'number') {
    errors.push('Price must be a number');
  }
  
  if (errors.length > 0) {
    throw new Error(`Validation errors: ${errors.join(', ')}`);
  }
};

​
Common Use Cases

E-commerce

Product listings with prices, specs, inventory, and ratings

Real Estate

Property listings with location, amenities, and pricing details

Events

Event details with dates, locations, speakers, and registration

Job Postings

Job listings with requirements, benefits, and application info

Recipes

Cooking instructions with ingredients and nutritional information

Reviews

Structured reviews with ratings, pros/cons, and recommendations

​
Industry-Specific Examples

Custom Types: custom.appointment, custom.health_tip, custom.exercise_planUse Cases: Medical appointment booking, health tips with structured advice, workout plans with exercises and timing
Custom Types: custom.course, custom.assignment, custom.quizUse Cases: Course catalogs with curriculum details, assignment submissions with rubrics, interactive quizzes with scoring
Custom Types: custom.hotel, custom.itinerary, custom.restaurantUse Cases: Hotel bookings with amenities, travel itineraries with schedules, restaurant reviews with menus
Custom Types: custom.stock_analysis, custom.portfolio, custom.market_updateUse Cases: Stock analysis reports, portfolio performance tracking, market news with data visualization
Schema Design Tip: Include version fields in your data structure to support schema evolution as your custom post types mature and require updates.

Text Posts

Create simple text-based posts for basic content sharing

Image Posts

Share visual content with photos and galleries

Post Management

Manage, edit, and moderate your custom posts