Social docs
Guides
Build with Social.
The end-to-end tutorial plus a shelf of focused single-feature guides. Most customers go through the tutorial once during integration, then come back here for the feature they're wiring next.
Looking for the full HTTP API? API reference. For the conceptual model in one page, Getting started.
Series
Tutorials
Focused
Single-feature guides
Webhooks
Durable outbound webhooks: signed deliveries (X-Pcft-Signature), a 21-event catalog, ~32h of backoff retries, delivery log, test pings, redelivery, and auto-disable recovery. At-least-once, strictly async.
Read more Notification preferences
Per-actor / per-kind opt-out. Mute follow notifications, keep mentions on. Producer checks the preference before inserting, so muted kinds never land in the inbox.
Read more Drafts
Save half a thought without shipping it. Author-only, hidden from feeds and lists. Promote via PATCH { status: 'published' } and the post_count counter is bumped at the transition.
Read more Per-post interaction settings
The typed post.settings object: who can comment (everyone / followers / mentioned / off), hide reaction counts from non-authors, and allow or forbid reposts and quotes — all enforced server-side.
Read more Tagging people in posts
Tag actors with review: tags land pending, the tagged actor approves or removes them (or the author removes), approved tags surface on a visibility-aware /tagged listing, and each tag fires a notification + tag.created webhook.
Read more Private accounts & follow requests
Flip an actor to private: posts cap at followers-only across every surface, and following creates an approve/decline request. Auto-approve on going public, follow_pending in the relationships lookup, block-teardown of pending requests.
Read more Hidden words
A community blocked-terms lexicon (admin lane, hide / pending_approval) plus author-side muted-term holds — matching comments are hidden or held for review server-side, without fanning the term list to clients.
Read more Not interested & don't suggest
Hide a post as a hard per-viewer feed filter, and dismiss an actor from your follow suggestions — with a read-time staleness filter so dismissals take effect immediately against the cached suggestion set.
Read more Creator insights
Report impressions (with optional viewer for unique reach), then read per-post views/reach/engagement with a daily series, plus a nightly-snapshot follower time series per actor. Gated by social.analytics.read.
Read more Collections
Group posts into named collections — private bookmark folders and profile-public highlight reels (which bypass story expiry) — over one generic primitive, additive over the flat bookmark/highlight surfaces.
Read more Media uploads & attachments
Upload images (EXIF-stripped, renditioned) and videos (presigned PUT, transcoded to a streaming-ready MP4 + poster) once, stored privately behind short-lived presigned URLs — attach to posts, comments, and DMs by id, up to 20 per item with per-attachment alt text.
Read more Fulfilling data-subject requests
Assemble a complete GDPR Art. 15/20 export by walking the per-actor endpoints (including the admin-lane comments + reactions listings), and fulfil erasure with a single hard delete that cascades everything the actor owns.
Read more Moderation queue & enforcement
File flags against posts, comments, actors, or DMs; act on the queue or act directly on anything unflagged; suspend/reinstate actors and moderator-soft-delete DMs. Reporters poll a scoped listing to see whether their own report was reviewed.
Read more Suggested follows
Friend-of-a-friend recommendation with a top-by-followers cold-start fallback. 1-hour cache per (actor, limit). Excludes self, existing follows, mutes, blocks, and inbound blocks.
Read more Bookmarks
Personal save-for-later list per actor. Toggle on/off, list per actor. Bookmarks are private — no notifications, no counters, no public visibility.
Read more @-mentions
Parses @handle in post / comment bodies, indexes them, fires 'mention' notifications, and exposes a per-actor 'show me everywhere I'm tagged' feed.
Read more #-hashtags
Per-community tag directory, indexed at write time inside the same DB transaction as the post insert. Listing, detail with post count, posts-for-tag, prefix autocomplete.
Read more User search
Postgres FTS over a generated tsvector column on the actor table (display_name A + external_id B + bio C). Sub-100ms ranked search; block / mute filtering via actor_id.
Read more Post search
Postgres FTS over a generated tsvector column on the post table (title A + body B). Pick relevance ranking or recency ordering; status / expiry / block filters live at the SQL layer.
Read more Comment reactions
Same free-form `type` reactions as posts, this time on individual comments. Idempotent toggle, denormalised reaction_counts on the comment row, kind='reaction' notification with target_kind='comment'.
Read more Hashtag-followed feed
Per-actor follow list for hashtags. Posts using any followed tag get unioned into the actor's feed alongside posts from people they follow. Both chronological and ranked modes pick them up.
Read more Reposts
X-style retweet. Reposts ride on the existing post pipeline (kind='repost' + source_post_id) so feeds, reactions, comments all work without bespoke code. Idempotent toggle.
Read more Edit history
X-style edit window. Pre-edit snapshots in post_revision; edited_at + edit_count on the post row. Default 30-min window, configurable per-community. Drafts edit freely.
Read more Quote posts
X-style quote-tweet. kind='quote' + source_post_id + body via the existing post-create endpoint. The quote IS a post — its own engagement, edit history, mentions, hashtags. Source carries quote_count.
Read more Actor lists & list feeds
X-style lists. Curate a set of actors — private or public — and read a dedicated chronological or ranked feed of just those members. Block-aware membership, owner-managed.
Read more Muted terms
Per-actor keyword muting. Case-insensitive substring over post body + title, optional expiry, upsert on re-POST, idempotent DELETE. Filters the home + discover feeds; mind the short-page caveat.
Read more Community settings reference
Every supported community.settings key — ranking weights, half-life and candidate window, max_comment_depth, auto_hide_flag_threshold, edit_window_minutes, max_group_conversation_size, max_pinned_comments — with defaults, bounds, and the consuming feature.
Read more Sister docs
Cross-references
Social often pairs with other ProductCraft services:
- Auth — your customers' user accounts. Project them into Social as actors (see
02 · Profiles) so they show up with consistent identity across both services. - Mail — sending notification digest emails. Wire to Social's notification events (see
08 · Notifications) for the “you got a new follower” email. - Platform — PATs for CI/CD for the workspace credential pattern Social's customer-backend lane uses.