Skip to content

Sticker API

Manage Saved and official packs as account resources. All paths below start with /v1/accounts/{accountId}. GET requests read metadata or already owned media; they do not start acquisition or change account membership.

ResourceMethods and purpose
/sticker-collectionsGET Saved plus every added-pack picker descriptor
/custom-stickersGET ordered Saved/revision; POST save prepared or received media
/custom-stickers/{id}GET metadata/media; PATCH placement; DELETE Saved membership
/sticker-preparationsPOST uploaded source plus optional trim, fit, maxEdge and fps
/sticker-preparations/{id}GET job, outputs, previews, transformations and expiry
/sticker-packsGET available-feed page; ?membership=added reads the complete account-added list
/sticker-packs/{id}GET name, membership and separate content readiness
/sticker-packs/{id}/stickersGET contents and optional official captions; ?language=en selects a locale
/sticker-packs/{id}/stickers/{stickerId}GET one item
/sticker-packs/{id}/membershipPUT {} adds eligible-free membership; DELETE removes it
/sticker-downloadsPOST stickerId for Saved, packId for one whole pack, or both for one pack item; assetId acquires an advertised icon/cover/thumbnail
/sticker-syncsPOST {"scope":"saved"}, "added" or "all"

Metadata/media reads and downloads use media scope. Saved mutations, membership and sync submissions use send scope. Uploads, jobs, media-content, sends and events reuse the ordinary API resources. A sticker send may acquire a missing canonical GIF; it preserves an existing alternate-format Saved cache.

Prepare, review and save

  1. Upload bytes through /uploads. Preparation receives the returned sourceId, never a path on the caller’s machine. Sources can be up to 64 MiB for images and GIFs and 512 MiB for videos.

    {"sourceId":"SOURCE_ID","maxEdge":360,"fps":12,"trim":{"startMs":1000,"durationMs":2000}}

    Images and GIFs up to 1024 pixels keep their size and encoding. fit shrinks a larger one to 1024; maxEdge (16–1024) shrinks the longest side further and never enlarges. Video becomes a GIF at 240 pixels and 10 fps unless maxEdge and fps (1–30) say otherwise; fps is refused for images.

  2. POST that body to /sticker-preparations with Idempotency-Key. A completed preparation links to authenticated original, preview and sampled-frame media.

  3. Save the reviewed output with POST /custom-stickers:

    {"source":{"kind":"prepared","preparationId":"PREPARATION_ID"}}

    A received source instead uses {"source":{"kind":"message","messageId":"MESSAGE_ID","assetId":"ASSET_ID"}}. Its original must already be downloaded and verified. Alternate WXGF files cannot be saved as a new item directly; use a verified canonical original.

  4. Once the sticker is saved, or you decide not to save it, DELETE /uploads/{sourceId} to free the source’s disk space. It returns {"released":true}, or false if the upload was already gone. While a preparation or send still needs the upload, it returns 409 upload_in_use.

Placement and operation recovery

PATCH and DELETE require the quoted collection revision in If-Match. Place an item with {"position":{"afterId":"OTHER_ID"}}; null means first. Resolve last against a fresh list with the moving item excluded. Missing preconditions return 428. A stale revision returns 412 with the current revision; refresh the list.

Asynchronous submissions return 202, the existing job representation and a status location. Reuse the same idempotency key and intent after an uncertain response. Already-satisfied membership reconciles as a no-op. Keep server acceptance, profile writeback, membership and media readiness separate. A needs_review result is not permission to resubmit under a new key. Local writeback repair uses retained inputs without resending or acquiring again.

Send a selection

POST /sends with the normal send idempotency header:

{"kind":"sticker","threadId":"CHAT_ID","source":{"kind":"pack","packId":"PACK_ID","stickerId":"STICKER_ID"}}

Saved uses {"kind":"saved","stickerId":"STICKER_ID"}; direct prepared sends use {"kind":"prepared","preparationId":"PREPARATION_ID"}. Sending does not add Saved membership. Existing selections need an available original and are revalidated before submission.

Listen for sticker-collections.changed and refresh the affected view. The daemon reconciles supported push notifications and reconnects; clients do not need continuous list polling.