Skip to main content

​
Create Event

Create scheduled events for communities or user timelines with support for virtual and in-person gatherings, timezone handling, and livestream integration.

​
Overview

The Event Creation API allows you to schedule events with comprehensive details including timing, location, cover images, and metadata. Events can be created for communities (with appropriate permissions) or on user timelines.

​
Creating an Event

​
Basic Event Creation

Task { @MainActor in
    do {
        let event = try await AmityEventRepository.shared.createEvent(
            options: AmityEventCreateOptions()
                .setTitle("Community Workshop 2025")
                .setDescription("Join us for an interactive workshop on iOS development")
                .setType(.virtual)
                .setStartTime("2025-03-20T14:00:00Z")
                .setOriginType(.community)
                .setOriginId("community-123")
                .setMetadata(["timezone": "America/Los_Angeles"])
        )
        print("Event created: \(event.eventId)")
    } catch {
        print("Failed to create event: \(error)")
    }
}

​
In-Person Event with Location

let event = try await AmityEventRepository.shared.createEvent(
    options: AmityEventCreateOptions()
        .setTitle("Annual Community Meetup")
        .setDescription("Join us for food, networking, and fun!")
        .setType(.inPerson)
        .setStartTime("2025-04-15T18:00:00Z")
        .setEndTime("2025-04-15T21:00:00Z")
        .setOriginType(.community)
        .setOriginId("community-123")
        .setLocation("123 Main Street, San Francisco, CA 94102")
        .setMetadata(["timezone": "America/Los_Angeles"])
)

​
Virtual Event with External URL

let event = try await AmityEventRepository.shared.createEvent(
    options: AmityEventCreateOptions()
        .setTitle("Product Launch Webinar")
        .setDescription("Introducing our latest features and roadmap")
        .setType(.virtual)
        .setStartTime("2025-05-10T16:00:00Z")
        .setEndTime("2025-05-10T17:30:00Z")
        .setOriginType(.user)
        .setOriginId("user-456")
        .setExternalUrl("https://zoom.us/j/123456789")
        .setTags(["product", "launch", "webinar"])
        .setMetadata(["timezone": "UTC"])
)

​
Event with Cover Image

// First upload the cover image
let imageData = UIImage(named: "event-cover")?.jpegData(compressionQuality: 0.8)
let imageFile = try await AmityFileRepository.shared.uploadImage(imageData!)

// Create event with cover image
let event = try await AmityEventRepository.shared.createEvent(
    options: AmityEventCreateOptions()
        .setTitle("Summer Festival 2025")
        .setDescription("Annual community celebration with music and activities")
        .setType(.inPerson)
        .setStartTime("2025-07-20T10:00:00Z")
        .setEndTime("2025-07-20T22:00:00Z")
        .setOriginType(.community)
        .setOriginId("community-123")
        .setLocation("Central Park, New York")
        .setCoverImageFileId(imageFile.fileId)
        .setMetadata(["timezone": "America/New_York"])
)

​
Parameters

Type: string
Required: Yes
Description: The event title/nameGuidelines:
  • Keep concise but descriptive
  • Maximum recommended length: 100 characters
  • Should clearly convey the event purpose
Example:
title: "Q4 Product Roadmap Review"
Type: string
Required: Yes
Description: Detailed event descriptionGuidelines:
  • Provide context and key information
  • Include agenda or key topics
  • Mention special requirements or prerequisites
Example:
description: "Join us to review our Q4 roadmap, discuss upcoming features, and provide feedback on our development priorities."
Type: AmityEventType
Required: Yes
Values: virtual | in_person
Description: Event format typeUsage:
  • virtual: Online events, webinars, livestreams
  • in_person: Physical location events, meetups
Example:
type: AmityEventType.VIRTUAL
Type: string (ISO 8601)
Required: Yes
Description: Event start date and timeFormat: ISO 8601 datetime string in UTCExample:
startTime: "2025-03-15T14:00:00Z"
Always use UTC timezone in the ISO string. Store the display timezone in metadata.
Type: string (ISO 8601)
Required: No
Description: Event end date and timeGuidelines:
  • Must be after startTime
  • Helps with scheduling conflicts
  • Used for calendar integration
Example:
endTime: "2025-03-15T16:00:00Z"
Type: AmityEventOriginType
Required: Yes
Values: community | user
Description: Where the event is createdUsage:
  • community: Event belongs to a community
  • user: Event on user’s timeline
Example:
originType: AmityEventOriginType.COMMUNITY
Type: string
Required: Yes
Description: ID of the community or userUsage:
  • Community ID when originType is community
  • User ID when originType is user
Example:
originId: "community-123"
Type: string
Required: No (recommended for in-person events)
Description: Physical location addressGuidelines:
  • Include full address for in-person events
  • Can include venue name
  • Consider including map links in description
Example:
location: "123 Main Street, San Francisco, CA 94102"
Type: string
Required: No
Description: External link (Zoom, Meet, etc.)Use Cases:
  • Video conference links
  • Registration pages
  • Additional event information
Example:
externalUrl: "https://zoom.us/j/123456789"
Type: string
Required: No
Description: File ID of uploaded cover imageSteps:
  1. Upload image using FileRepository
  2. Use returned fileId in event creation
Example:
coverImageFileId: "file-abc123"
Type: string[]
Required: No
Description: Event tags for categorizationGuidelines:
  • Use for filtering and discovery
  • Keep tags relevant and specific
  • Lowercase recommended
Example:
tags: ["workshop", "developer", "beginner-friendly"]
Type: object
Required: Yes (timezone field required)
Description: Event metadata including timezoneRequired Fields:
  • timezone: IANA timezone identifier
Example:
metadata: {
    timezone: "America/Los_Angeles",
    customField: "value"
}

​
Permission Requirements

Before creating an event, ensure the user has appropriate permissions: 
// Check global permission for user timeline events
let canCreateEvent = await AmityClient.shared.hasPermission(
    .createEvent
)

// Check community permission for community events
let canCreateInCommunity = await AmityClient.shared.hasPermission(
    .createEvent,
    communityId: "community-123"
)

// Check livestream event permission
let canCreateLivestream = await AmityClient.shared.hasPermission(
    .createEventWithLivestream,
    communityId: "community-123"
)

​
Timezone Best Practices

Timezone Handling: Always store event times in UTC and include the display timezone in metadata. This ensures correct display across different timezones.

​
Example Timezone Handling

// User in Bangkok (+7:00) scheduling event in Singapore (+8:00)
// User selects: Oct 21, 9 PM in date picker
// User selects: Singapore timezone

// In your application:
const selectedDate = new Date(2025, 9, 21, 21, 0, 0); // Oct 21, 9 PM local
const singaporeTime = convertToTimezone(selectedDate, 'Asia/Singapore');
const utcTime = singaporeTime.toISOString(); // "2025-10-21T13:00:00Z"

const event = await createEvent({
    startTime: utcTime, // UTC time
    metadata: {
        timezone: "Asia/Singapore" // Display timezone
    }
});

// When displaying:
const displayTime = new Date(event.startTime);
const localTime = convertFromTimezone(displayTime, event.metadata.timezone);
// Shows: Oct 21, 9 PM (Singapore time)

​
Error Handling

do {
    let event = try await AmityEventRepository.shared.createEvent(options: options)
    // Handle success
} catch AmityError.permissionDenied {
    // User doesn't have permission to create events
    showError("You don't have permission to create events")
} catch AmityError.invalidParameter(let message) {
    // Invalid parameters provided
    showError("Invalid event data: \(message)")
} catch {
    // Other errors
    showError("Failed to create event: \(error.localizedDescription)")
}

Manage Events

Update and delete events

Event RSVP

Handle attendee responses

Events Overview

Learn about event concepts