Custom Message

Send custom message types with free-form JSON data for polls, location sharing, interactive cards, and other app-specific content.

Send a custom message with a free-form JSON data field to represent content types beyond text, image, video, and file, such as polls, location pins, booking widgets, or any app-specific structure.

Custom Message Overview

Custom messages use a free-form JSON data field to represent any content type your application requires.

JSON Structure

JSON-based data format

• Free-form JSON object structure
• Support for nested objects and arrays
• Complex data type handling
• Schema validation capabilities

Interactive Content

Custom content types

• Surveys
• Location sharing and maps
• Booking and reservation widgets
• Custom UI components

Implementation Guide

Basic Custom Messages

Simple custom data structures

Create custom messages with structured JSON data for various use cases and interactive content.

Required Parameters

Parameter	Type	Description
subChannelId	String	Target subchannel identifier for the custom message
data	Object/JSON	Free-form JSON object containing your custom data structure

Optional Parameters

Parameter	Type	Description
tags	Array<String>	Message categorization and filtering tags
parentId	String	Parent message ID for threaded conversations
metadata	Object	Additional properties for extended functionality

Code Examples

iOS

// Basic custom message with simple data
let pollData: [String: Any] = [
    "type": "poll",
    "question": "What's your favorite programming language?",
    "options": [
        ["id": "swift", "text": "Swift", "votes": 0],
        ["id": "kotlin", "text": "Kotlin", "votes": 0],
        ["id": "typescript", "text": "TypeScript", "votes": 0],
        ["id": "python", "text": "Python", "votes": 0]
    ],
    "multiple_choice": false,
    "expires_at": "2024-01-20T23:59:59Z"
]

let options = AmityCustomMessageCreateOptions(
    subChannelId: "subChannel-123",
    data: pollData,
    tags: ["poll", "survey", "team"],
    parentId: nil
)

do {
    let message = try await messageRepository.createCustomMessage(options: options)
    print("Custom poll message sent: \(message.messageId)")
    
    // Access custom data
    if let customData = message.data as? [String: Any] {
        print("Poll question: \(customData["question"] ?? "")")
    }
} catch {
    print("Failed to send custom message: \(error)")
}

JSON Structure: Custom message data supports any valid JSON structure including nested objects, arrays, and primitive types. Design your data schema to match your UI requirements.

Interactive Content

Complex interactive message types

Build rich interactive experiences with custom messages for polls, location sharing, booking systems, and more.

Interactive Message Examples

// Location sharing custom message
let locationData: [String: Any] = [
    "type": "location",
    "name": "Conference Center",
    "address": "123 Tech Street, San Francisco, CA 94105",
    "coordinates": [
        "latitude": 37.7749,
        "longitude": -122.4194
    ],
    "details": [
        "floor": "2nd Floor",
        "room": "Conference Room A",
        "capacity": 50,
        "amenities": ["projector", "whiteboard", "wifi"]
    ],
    "metadata": [
        "shared_by": "user123",
        "accuracy": "high",
        "timestamp": "2024-01-15T10:30:00Z"
    ]
]

// Event/booking custom message
let eventData: [String: Any] = [
    "type": "event",
    "title": "Team Building Workshop",
    "description": "Interactive workshop to improve team collaboration",
    "datetime": [
        "start": "2024-01-20T14:00:00Z",
        "end": "2024-01-20T17:00:00Z",
        "timezone": "America/Los_Angeles"
    ],
    "location": [
        "venue": "Innovation Hub",
        "address": "456 Startup Ave, Palo Alto, CA",
        "room": "Workshop Space 1"
    ],
    "registration": [
        "required": true,
        "deadline": "2024-01-18T23:59:59Z",
        "max_attendees": 25,
        "current_attendees": 0
    ],
    "organizer": [
        "user_id": "user123",
        "name": "Sarah Johnson",
        "contact": "[e-mail]"
    ]
]

Common Interactive Types

Type	Use Case	Data Structure
Poll	Surveys, voting, decision making	{ question, options[], settings }
Location	Meeting points, directions, venue sharing	{ coordinates, address, details }
Event	Meeting invites, workshop announcements	{ datetime, location, registration }
Booking	Room reservations, appointment scheduling	{ service, availability, settings }
Rich Card	Announcements, reports, highlights	{ title, content, actions[], styling }

Advanced Custom Messages

Enterprise-grade custom message implementations

Build sophisticated custom message types with validation, schema definitions, and complex business logic.

Schema-Based Custom Messages

// Advanced approval workflow message
let approvalData: [String: Any] = [
    "type": "approval_request",
    "workflow": [
        "id": "expense_approval_001",
        "type": "expense_report",
        "priority": "normal",
        "deadline": "2024-01-18T17:00:00Z"
    ],
    "request": [
        "title": "Business Trip Expenses - Client Meeting",
        "description": "Travel expenses for Q1 client strategy meeting in New York",
        "category": "travel",
        "total_amount": 1250.00,
        "currency": "USD"
    ],
    "items": [
        [
            "type": "flight",
            "description": "Round-trip flight SFO-JFK",
            "amount": 650.00,
            "date": "2024-01-10",
            "receipt_url": "https://storage.company.com/receipts/flight_001.pdf"
        ],
        [
            "type": "hotel",
            "description": "Hotel accommodation (2 nights)",
            "amount": 400.00,
            "date": "2024-01-10",
            "receipt_url": "https://storage.company.com/receipts/hotel_001.pdf"
        ],
        [
            "type": "meals",
            "description": "Client dinner and business meals",
            "amount": 200.00,
            "date": "2024-01-11",
            "receipt_url": "https://storage.company.com/receipts/meals_001.pdf"
        ]
    ],
    "approval_chain": [
        [
            "step": 1,
            "approver_id": "manager_123",
            "approver_name": "John Smith",
            "status": "pending",
            "required": true
        ],
        [
            "step": 2,
            "approver_id": "finance_456",
            "approver_name": "Finance Team",
            "status": "awaiting",
            "required": true
        ]
    ],
    "metadata": [
        "submitted_by": "employee_789",
        "submitted_at": "2024-01-15T09:00:00Z",
        "department": "sales",
        "project_code": "CLIENT_2024_Q1"
    ]
]

Custom Message Use Cases

Polls & Surveys

Interactive voting and feedback collection

Poll Features

• Single/Multiple Choice: Support for both single selection and multiple selection polls
• Anonymous Voting: Optional anonymous voting for sensitive topics
• Time-Limited Polls: Set expiration dates for time-sensitive decisions
• Real-Time Results: Live vote counting and results display

Survey Capabilities

• Multi-Question Surveys: Complex surveys with various question types
• Conditional Logic: Show/hide questions based on previous answers
• Progress Tracking: Visual progress indicators for long surveys
• Response Analytics: Detailed analytics on survey responses

Question Types

• Rating Scales: 1-5 or 1-10 rating questions
• Open Text: Free-form text responses
• Multiple Choice: Single or multiple selection options
• Yes/No: Simple binary questions

Poll Data Structure

{
  "type": "poll",
  "question": "Which feature should we prioritize?",
  "options": [
    {"id": "feature_a", "text": "Feature A", "votes": 0},
    {"id": "feature_b", "text": "Feature B", "votes": 0}
  ],
  "settings": {
    "multiple_choice": false,
    "anonymous": true,
    "expires_at": "2024-01-20T23:59:59Z"
  }
}

Location & Events

Location sharing and event management

Location Sharing

• GPS Coordinates: Precise latitude/longitude coordinates
• Address Information: Human-readable addresses and venue details
• Interactive Maps: Embedded map views with directions
• Location Metadata: Additional context like floor, room, or landmarks

Event Management

• Event Details: Date, time, duration, and timezone information
• Venue Information: Location details with capacity and amenities
• Registration System: RSVP functionality with attendee limits
• Calendar Integration: Export to calendar applications

Use Cases

• Meeting Coordination: Share meeting locations and details
• Event Announcements: Company events and social gatherings
• Emergency Coordination: Share emergency meeting points
• Field Work: Location updates for remote teams

Location Data Structure

{
  "type": "location",
  "coordinates": {"lat": 37.7749, "lng": -122.4194},
  "address": "123 Tech Street, San Francisco, CA",
  "venue_details": {
    "name": "Conference Center",
    "floor": "2nd Floor",
    "room": "Room A"
  }
}

Rich Cards & Widgets

Structured content displays and interactive widgets

Rich Card Features

• Visual Hierarchy: Title, subtitle, and body content organization
• Media Integration: Images, videos, and file attachments
• Action Buttons: Interactive buttons for user actions
• Custom Styling: Colors, layouts, and branding options

Widget Types

• Booking Widgets: Appointment and reservation systems
• Product Showcases: Product information with pricing
• Status Updates: Project status and progress indicators
• Announcement Cards: Important updates with rich formatting

Interactive Elements

• Buttons: Call-to-action buttons with custom actions
• Forms: Embedded forms for data collection
• Media Players: Audio and video playback controls
• External Links: Deep links to other applications

Rich Card Structure

{
  "type": "rich_card",
  "title": "Q4 Performance Report",
  "content": {"summary": "...", "metrics": [...]},
  "actions": [
    {"type": "button", "label": "View Report", "action": "open_url"}
  ],
  "styling": {"color_scheme": "success"}
}

Business Workflows

Enterprise workflow integration and automation

Approval Workflows

• Multi-Step Approvals: Complex approval chains with multiple approvers
• Conditional Logic: Different approval paths based on criteria
• Deadline Management: Time limits for approval decisions
• Audit Trail: Complete history of approval actions

Task Management

• Task Assignment: Assign tasks with due dates and priorities
• Progress Tracking: Status updates and completion tracking
• Dependencies: Task dependencies and blocking relationships
• Resource Allocation: Resource and time estimates

Integration Features

• External Systems: Connect to HR, CRM, and project management tools
• API Webhooks: Trigger external actions based on message interactions
• Data Synchronization: Keep external systems in sync
• Reporting: Generate reports from workflow data

Approval Workflow Structure

{
  "type": "approval_request",
  "workflow_id": "expense_approval",
  "request_details": {...},
  "approval_chain": [
    {"step": 1, "approver": "manager", "status": "pending"}
  ],
  "metadata": {"department": "sales", "amount": 1250.00}
}

Best Practices

Data Structure Design

Designing effective custom message schemas

Schema Design Principles

• Consistent Structure: Use consistent field names and data types across similar message types
• Extensibility: Design schemas that can be extended without breaking existing implementations
• Validation: Include validation rules and constraints in your schema design
• Documentation: Maintain clear documentation of your custom message schemas

Performance Considerations

• Size Limits: Keep custom message data under reasonable size limits (recommended < 50KB)
• Nesting Depth: Avoid excessive nesting that can impact parsing performance
• Required vs Optional: Minimize required fields to reduce validation overhead
• Indexing: Design data structure to support efficient searching and filtering

Version Management

• Schema Versioning: Include version information in your custom message schema
• Backward Compatibility: Ensure new versions are backward compatible when possible
• Migration Strategies: Plan for data migration when schema changes are required
• Deprecation: Properly deprecate old schema versions with clear timelines

Schema Design Example

interface CustomMessageSchema {
  version: string;
  type: string;
  required_fields: string[];
  optional_fields: string[];
  validation_rules: {
    [field: string]: {
      type: string;
      min_length?: number;
      max_length?: number;
      enum_values?: string[];
    };
  };
}

User Experience

Creating intuitive custom message interfaces

UI Design Guidelines

• Visual Consistency: Maintain consistent visual design across all custom message types
• Loading States: Provide appropriate loading indicators for interactive elements
• Error Handling: Display clear error messages for failed interactions
• Accessibility: Ensure custom messages are accessible to all users

Interaction Design

• Touch Targets: Ensure interactive elements have appropriate touch target sizes
• Feedback: Provide immediate feedback for user interactions
• Progressive Disclosure: Show complex information progressively to avoid overwhelming users
• Contextual Actions: Provide relevant actions based on user permissions and context

Mobile Optimization

• Responsive Design: Ensure custom messages work well on all screen sizes
• Touch Gestures: Support appropriate touch gestures for mobile interactions
• Performance: Optimize rendering performance for complex custom messages
• Network Awareness: Handle poor network conditions gracefully

Testing Strategy

• Cross-Platform Testing: Test custom messages across all supported platforms
• User Testing: Conduct user testing to validate custom message designs
• Performance Testing: Test performance with large datasets and complex interactions
• Accessibility Testing: Verify accessibility compliance and usability

Related Features

Text Messages

Standard messaging Basic text messaging capabilities

Message Management

Content control Edit, delete, and moderate message content

Real-Time Updates

Live synchronization Real-time message updates and interactions

Implementation Strategy: Start with simple custom message types like polls or location sharing, then progressively build more complex interactive content. Always validate your data schema and implement proper error handling for the best user experience.