Skip to main content

Documentation Index

Fetch the complete documentation index at: https://learn.social.plus/llms.txt

Use this file to discover all available pages before exploring further.

Central, living knowledge base for developers integrating social.plus. Use the quick navigation, browser find (⌘/Ctrl + F), or your docs site search to jump to relevant answers. Each category groups focused, implementation‑level questions gathered from support & community discussions.

​
Quick Navigation

API

Authentication • Pagination • Bulk Ops • Moderation

Social & Chat

Feeds • Communities • Roles • Media

UIKits & SDKs

Platforms • Push • Blocking • Feature Gaps

Poll

Creation • Limits • Retrieval

Console

Admin • Certificates • Access • Limits

Portal

Environments • Plans • Org Data

Alt Solutions

Workarounds & Patterns

Beta Features

Realtime • Search • Webhooks

Errors

Common Failures & Fixes

General

Accounts • Theming • Multi‑tenant

Dashboard

Metrics • Definitions

​
Using This FAQ

1

Scan Categories

Skim the Quick Navigation cards to locate a domain (e.g. Errors vs API).
2

Deep Link

Copy the URL after clicking a section heading to share precise context with teammates.
3

Validate Versions

For SDK questions, confirm your SDK / UIKit versions vs latest changelogs before implementing a workaround.
4

Escalate Gaps

If an answer points to a workaround, log a feature request in the Developer Forum with context (scale, impact, timeline).
5

Contribute Back

Found a nuance or edge case? Propose an edit so the knowledge stays current.
Looking for a question that is not here? Use the Developer Forum anchor in the SDK navigation to open community discussions or submit a new thread.

​
API

To create a large number of users, use the session registration endpoint: Register a session. Script the call over your user list (respecting rate limits) to establish accounts.
This question is answered under the Console section (“Where can I get my admin token?”). See Console » Admin token.
API list endpoints return a paging.next token. Pass it back as the options[token] (or documented query param) to fetch the next slice.

Example response:
{
  "paging": { "next": "eyJza2lwIjoyMCwibGltaXQiOjEwfQ==" }
}
Example request: 
curl —location —globoff ‘https://api.sg.amity.co/api/v3/communities?filter=all&sortBy=lastCreated&options[token]=eyJza2lwIjoxMCwibGltaXQiOjEwfQ%3D%3D’ \
—header ‘accept: application/json’ \
—header ‘Authorization: Bearer xxx’
Use the blocklist records endpoint:
curl --location 'https://api.sg.amity.co/api/v3/blacklist/records' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer xxx' \
  --data '{
    "regexs": ["word1", "word2", "word3"],
    "isMatchExactWord": true
}'
Set isMatchExactWord to true for exact term blocking or false for substring / regex style matches. API Ref: Moderation » Blocklists.
Update social network settings via: PUT /network-settings/social
curl --location --request PUT 'https://api.sg.amity.co/api/v3/network-settings/social' \
  --header 'accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer xxx' \
  --data '{"isFollowWithRequestEnabled": false}'
Append ?size=full to the file download URL. Sizes: small | medium | large | full.
Example: …/files//download?size=full
The SDK auto-manages refresh / access tokens. When using raw REST, simply request a new session (register session) instead of manually rotating a refresh token.
Auth tokens (secure mode) are valid 10 minutes. See: Secure Mode docs. Obtain a fresh one server-side when expiring, then call Session create.
Filter with filter=member on communities endpoint:
curl --location 'https://apix.sg.amity.co/api/v3/communities?filter=member&sortBy=lastCreated&options[limit]=100' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer xxx'
  1. Get new auth token:
curl --location 'https://api.sg.amity.co/api/v3/authentication/token?userId=Amity' \
  --header 'accept: application/json' \
  --header 'x-server-key: xxx'
  1. Exchange via Session API:
curl --location 'https://apix.sg.amity.co/api/v4/sessions' \
  --header 'accept: application/json' \
  --header 'x-api-key: xxx' \
  --header 'Content-Type: application/json' \
  --data '{"userId":"Amity","deviceId":"test","authToken":"xxx"}'
Use the Authentication token endpoint then register session. Docs: Authentication. For context see Security page.
No direct “my reacted posts” endpoint. Query reactions (Reactions list) and filter client-side for your userId per target post.
Send only the metadata field in a user update body; unspecified fields remain unchanged.
curl --location --request PUT 'https://api.eu.amity.co/api/v2/users' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer xxx' \
  --data '{"userId":"Test","metadata":{"tier":"gold"}}'
Iterate: list posts (community / user feeds) then call delete for each (Delete Post v4). Build an idempotent script with backoff; respect rate limits.
Use POST /files then attach returned fileId when creating the post/message referencing audio.
curl --location --globoff 'https://apix.sg.amity.co/api/v3/communities/COMMUNITY_ID/users?memberships[]=member&roles[]=moderator&options[limit]=10' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer xxx'
Not supported: upload endpoints expect file data (multipart / direct). Fetch remote file server-side then re-upload if needed.
Creating a new session with the same deviceId invalidates the old access token. Use stable per-device identifiers; avoid reusing one id across multiple concurrent logins.
To receive real-time event notifications, register a webhook by supplying a callback URL in the Social Plus Console. Once registered, the platform will deliver event data via HTTP POST requests to the specified URL whenever supported events occur (e.g., users added to a channel, messages created, users joining, or posts being flagged).Event names follow a structured format, such as: “event”: “channel.didAddUsers”For the full list of supported webhook events and payload details, refer to the documentation.
Our API rate limit is 100 requests per 5 seconds per user (userId). This means the limit is shared across all devices for the same user. For example, if one user is logged in on multiple devices, all requests from those devices are counted together under the same limit.If the limit is exceeded, the API will return a rate limit error (e.g., HTTP 429).To handle high-volume traffic, we recommend implementing throttling, retry with backoff, batching, and caching to ensure smooth and reliable performance.
Via Console: Navigate to Moderation → AI Content Moderation and set confidence levels per category.

​
Social and Chat

targetType identifies feed scope (user | community); targetId is the userId or communityId. Together they scope post queries. See SDK docs: https://docs.amity.co/amity-sdk/social/posts/query-post

Engagement-based sort is only available on global feed. Community feeds support lastCreated and firstCreated ordering. Docs: https://docs.amity.co/amity-sdk/social/posts/query-post
API: add isDeleted=false param.
curl --location 'https://api.sg.amity.co/api/v3/communities?filter=all&isDeleted=false' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer xxx'
SDK: set includeDeleted (or includeDelete) flag false. Docs: https://docs.amity.co/amity-sdk/social/communities/query-communities
Only the current authenticated user can list their joined communities (filter=member). Privacy prevents enumerating others’ memberships.
curl --location 'https://api.sg.amity.co/api/v3/communities?filter=member' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer xxx'
Standard page size is 20. Use paging.next (API) or nextPage() (SDK live collections) to iterate. See Live Objects & Collections docs.
API (Add roles):
curl --location 'https://api.sg.amity.co/api/v4/communities/COMMUNITY_ID/users/roles' \
  --header 'accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer xxx' \
  --data '{"roles":["community-moderator"],"userIds":["test"]}'
Console path: Community > Members > (⋮) beside user > Change user role.Change user role screenshot
Use SDK moderation APIs or Delete community users endpoint.
Delete via API (delete community) or close in Console: Communities > select > Settings > Close Community.Close community screenshot
Auto-join starter communities immediately after user creation (call Join Community API) so their feed contains initial posts.
Lightweight extensible key/value storage for custom attributes (e.g. user tier). Not for large blobs or high-write analytics fields.
User has no joined communities and follows no users. Ensure onboarding joins at least one community or recommends follows.
Formats: JPG, PNG. Max size: 1 GB. Up to 10 images per post. UIKit v4 auto-converts unsupported formats (e.g. HEIC) client-side.
Formats: 3gp, avi, f4v, flv, m4v, mov, mp4, ogv, 3g2, wmv, vob, webm, mkv. Max 1 GB, ≤ 2 hours, ≤ 10 videos/post. HEVC/HDR converted in UIKit v4.
Provide only auth token to SDK during login; SDK handles session/access token internally. Docs: user creation page.
Global feed may use custom ranking (engagement, freshness blend). Contact support to adjust configuration. See Custom Post Ranking docs.
Call queryCommunities({ filter: ‘membership’ }). Docs: /social/communities/query-communities.
Construct download URL: https://api.{region}.amity.co/api/v3/files/{fileId}. Retrieve fileId from message/post objects via SDK.
Customize RecentChat component: on mount select first channel when list populated (example previously shown) to avoid blank panel.
Use conversation channel creation endpoint in idempotent mode (or SDK convenience) which returns existing if already present.
Append repeated tags[]= query params.
curl --location --globoff 'https://api.sg.amity.co/api/v4/posts?targetId=COMMUNITY_ID&targetType=community&sortBy=lastCreated&tags[]=tag1&tags[]=tag2' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer xxx'
Not supported; comments are fetched by post. Store needed mappings externally if user-centric aggregation required.
Configure who can join and what they can do.
First, set your community or network membership mode (open, request/approval, or invite‑only) so users either join freely or require approval/invites.
Then, define role types (e.g. admin, moderator, member, guest) and assign them to users to control permissions like posting, moderating, and managing settings.
Review these settings regularly to match your business rules and compliance needs.
AI is used to evaluate the livestream going on and based on the defined confidence levels, if the content is considered as not adequate it will be automatically terminated. More details about how our AI Livestream moderation works can be found here.
Yes, you can search for chat messages by calling the following API. At the same time, we do have this feature available in our Flutter SDK.

​
UIKits and SDKs

Ensure ALL of:
  • Production APNs cert or key uploaded (Sandbox & Production) and not expired
  • App capability: Push Notifications enabled
  • Correct app_id matches certificate
  • Running on real device (not simulator) and production/TestFlight build when testing prod cert
  • User granted notification permission & device not in Do Not Disturb / Focus
  • APNs key also uploaded to Firebase if using FCM bridge (docs)
Docs: certificate setup & register/unregister pages.
Not supported. Ship with bundled Realm version aligned to SDK. See iOS SDK & UIKit changelogs for compatibility matrix.
Upload APNs (.p12 or key) selecting “Apple Push Notification service SSL (Sandbox & Production)” so a single cert covers both.
Not recommended / unsupported. Use a package manager (npm, Yarn, pnpm) for versioned SDK distribution.
Use blocked users list query. Docs: /social/block-and-unblock-user#blocked-users-list.
Call SDK mark-read API or start/stop reading subchannel utilities (unread-count docs). Ensures backend updates unread counters.
Poll post type not yet supported in current Flutter SDK (only video/image/file). Track changelog for availability.
The SDK provides two methods:
• Search Users — Find users by displayName (min 3 characters), ranked by relevance
• Query Users — Retrieve users with sorting (displayName, firstCreated, lastCreated)
Full documentation
  1. Create keys/certs in Apple Developer
  • In Apple Developer account, create an APNs Auth Key (.p8) with Push Notifications enabled.
  • Note the Key ID, Team ID, and download the .p8 file.
  1. Configure your backend / Social+ console
    • Go to your project’s Notifications → Apple (iOS) page.
    • Upload the .p8 file, fill in Key ID, Team ID, and Bundle ID, then click Activate.
  2. Enable push in Xcode
    • Open your app target → Signing & Capabilities.
    • Add Push Notifications and (if needed) Background Modes → Remote notifications.
    • Make sure you use a provisioning profile that includes push.
  3. Request permission and get APNs token
    • In your app, ask for notification permission on first launch (UNUserNotificationCenter).
    • Implement application(_:didRegisterForRemoteNotificationsWithDeviceToken:) to get the APNs device token.
  4. Register token with your SDK
    • Pass the APNs token to your SDK (e.g. Client.registerPushNotification(apnToken) or fcmToken= in AmityUiKitProvider (React Native))
  5. Test real production push notifications.
    • Install a TestFlight (release) build on a physical iPhone (push notifications are not supported on simulators).
    • Trigger a real notification from your production backend or console, and verify that it is successfully delivered and displayed on the device.
Metadata in posts and comments is an optional Object field for storing additional custom properties. To configure it correctly:Pass metadata as a JSON object (e.g; “key”: “value”) when creating or updating posts/comments. Metadata patching is allowed for all post types via the patch post data and metadata API using set/delete operations. There is no strict schema, it accepts arbitrary key-value pairs for your custom needs.
The Social plus Portal is your organization-level management platform where you create and manage applications, handle billing, and control team access. Each application lives in its own Console, where you configure settings, moderate content, manage users, and grab your API key for integration.
iOS (UIKit):
  • Add AmitySDK and AmityUIKit4 via Swift Package Manager in Xcode.
  • Link to your app target and initialize in AppDelegate.
Android (UIKit):
  • Add Amity SDK and UIKit dependencies in your Gradle files.
  • Initialize SDK in your Application class.
Visitor Secure Mode is also available for UIKit. We will publish documentation about this soon. In the meantime, please contact us if you would like to use it.
Currently our stories feature is based on communities, which means that user can create stories but they need to be directed to a specific community.
More details about our story features can be found here.
The SocialPlus SDK supports real-time updates through its built-in real-time event system. This system maintains persistent connectivity to deliver live updates such as new posts, comments, reactions, notifications, and membership changes. If you are using the SDK directly, developers subscribe to the relevant real-time event topics (for example communities, posts, comments, or user updates). Once subscribed, the SDK automatically keeps the observed objects and collections synchronized. If you are using UIKit, this real-time functionality is already integrated for the supported features, so no additional implementation is required.
More details about the real-time event model can be found here.
Our open soure UIKits are fully customisable, so you can change any part of them. You can select between multiple components and based on them get the right version you are looking for. The idea of these UIKits is to help you accelerate implementation, making it easir to have our features available.

​
Poll

Call Get Poll Answer endpoint to retrieve voters (userIds) for specific answerId. Ref: API docs.
Not supported: create either a poll OR other attachment types, not combined.
Not directly. Use Portal: My Dashboard > Posts and filter type=Poll. (Console UI lacks poll list.)Poll posts screenshot

​
Console

Console: Settings > Admin Users > (cog icon). Screenshot below.Admin token screenshot
Admin user creates others: Settings > Admin Users > Create New Admin (top right) then share credentials securely.Create admin screenshot
Only portal owner initially. Use ”+ Add new certificate” button in Push Notification section.Add certificate screenshot
User option fetches user feed posts only; not a cross-community aggregation by userId.
Console: Settings > Security tab shows API key and region endpoint.Security tab screenshot
Performed by super admin; user-level self-service not provided.Password change screenshot
Hidden by design (privacy / noise). See Channel Characteristics docs for rationale.
Only one active push certificate per platform allowed simultaneously.

​
Portal

Portal: Create Application button (top right). Use distinct apps per environment to isolate data & config.Create application screenshot
In-place upgrade unavailable; create new application with desired plan, migrate, then retire old one.
Portal: Manage Payment tab > update Organization Name.Manage payment screenshot
The Social+ Portal does not support deleting applications once created, an app remains in your list permanently. You can only rename existing apps to keep things organized, and if you’re nearing the 50-app cap, contact support to request a limit increase.

​
Alternative solutions for unsupported features

Store array of postIds in user metadata (e.g. favorites). On profile render, fetch posts by those IDs.
Add metadata.verified=true (or role) on user; frontend displays badge based on flag.
New post with metadata.originalPostID referencing source. On display, fetch original, render nested.
Subscribe to webhook (post flagged) then trigger email via external service. See Real-time Events & WebhookEvent docs.
Store pinned postId in community metadata (e.g. pinPostID) and prepend when rendering feed if present.
UI hide non-admin button (weak) OR enforce via Pre-Hook Event (Max package) to reject non-admin create attempts.
Client filter after fetching OR use search/posts (beta) filtering by type then show results.
Capture duration client-side after record; store in message metadata; display using stored value.
Use Search Post API with postedUserId param (beta feature) to filter.
GIF upload is not natively supported by Social plus currently. As a workaround, GIFs can be uploaded via the Upload File API, and clients can customize the UI rendering on their end to display them.

​
Beta features

Use webhook events backend -> push service to send notifications (posts/comments). Reference WebhookEvent list.
Only indexes posts created after feature enablement; earlier posts excluded.
Include hashtagList in content search query.
{
  "hashtagList": ["#tags1", "#tags2", "#tags3"]
}
Subscribe to follow create / follow request webhooks, then dispatch notification to target user.

​
Frequent error types: Definition

Occurs when SDK calls made before session established. Wait until session state == established (listen to session state changes) before repository operations.
Use the paging.next (or previous) token from prior response. Do not reuse stale/modified tokens.
Queue actions until login promise resolves; avoid concurrent login + API operations.
More than 100 calls per user within 5s. Debounce, batch, or add exponential backoff; remove accidental loops.
Triggered by image moderation threshold. Adjust confidence level or disable temporarily in Settings > Image Moderation.
Link moderation allow list enforced. Add domain to Allow list or disable link moderation.

​
General

Permanent. Delete user API cannot be undone.
Iterate list of users meeting inactivity criteria then call DELETE user API (example with flags). Irreversible.
User cannot authenticate; removed from channels; messages deleted (cache may persist until refresh); social content intact.
Per active WebSocket/tab. Background/inactive tabs may auto-disconnect reducing CCU.
No native dark theme; customize via open-source UIKit theming.
Contact support ([email protected]) to remove.
Registered but no connections in the month being measured (historic register date irrelevant).
Achieved via multiple applications; strict data isolation per app.
Not supported; must upload through Social Plus SDK/API to store & moderate.
Not exposed; metrics available per application (Dashboard/Console). Use Portal Dashboard Guide for details.
Backend stores plain text (security). Implement client-side markup (e.g. markdown) and render safely.
GIF upload not supported currently.
You can extract at any point your data by calling our APIs:#description/using-social-apis.
In case you want some built-in reports that contain some of the most recent data and metrics, you can call our 1st party data API: #tag/admin/get/api/v1/reports/1p/download.
To see further detail, please access here: #get-first-party-data-export
We recommend keeping your SDK/UIKit updated to the latest version whenever possible. However, if you are not encountering any bugs or do not require new features that are supported by new version of SDK/UIKit, an immediate update may not be strictly necessary.

​
Dashboard

Users who view content without active engagement (posting/commenting/reactions).
Dashboard > Channels section > “New Messages by Day” widget.New messages widget screenshot