Stickers and sticker packs
Send stickers and packs, manage favorites and recents, and handle phone synchronization results.
Use a Linked Devices number to send an individual sticker or a sticker pack. Received stickers have type: "sticker"; received packs have type: "sticker_pack". These operations use API version 2026-11-10.
Send a sticker#
API
Supply exactly one HTTPS url, base64 image or preconverted descriptor in content.sticker. An optional accessibilityLabel describes the image.
curl "https://api.polymorfa.com/messaging/$NUMBER_ID/messages/send" \
-H "Authorization: Bearer $POLYMORFA_KEY" \
-H "Polymorfa-Version: 2026-11-10" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SEND_KEY" \
--data '{"conversation":{"phoneNumber":"+15550001111"},"content":{"sticker":{"url":"https://example.com/wave.png","accessibilityLabel":"A friendly wave"}}}'await messaging.messages.send(numberId, {
conversation: { phoneNumber: "+15550001111" },
content: {
sticker: {
url: "https://example.com/wave.png",
accessibilityLabel: "A friendly wave",
},
},
}, { apiVersion: "2026-11-10", idempotencyKey: sendKey });CLI
polymorfa message send sticker --session "$NUMBER_ID" \
--to +15550001111 --file ./wave.png --label "A friendly wave"Image conversion accepts PNG, JPEG, GIF, WebP, APNG, AVIF and HEIC within the conversion limits: 20 MiB input, 16 million canvas pixels, 64 million frame pixels, 300 frames, 30 seconds and 1 MiB output. These are upper limits. Conversion also rejects inputs that exceed its memory budget. Reduce the dimensions or animation frame count when conversion fails. Preconverted static and animated descriptors use mimeType: "image/webp". Lottie descriptors use stickerType: "lottie" and mimeType: "application/was". Descriptors must reference valid sticker bytes. Customer-owned Signal sessions keep their descriptor-only boundary.
Send a pack#
Use exactly one form of content.stickerPack:
- Author a pack with its ID, name, publisher and up to 100 image items.
- Upload a validated archive and provide its descriptor and item metadata.
- Forward a received pack with
forwardMedia.
Authored items and an explicit tray share 64 MiB of input and 128 million pixels, counting source canvases and 512px output frames across the whole pack. Preparation stops at the request deadline or 30 seconds, whichever comes first. Use fewer items, smaller images or fewer animation frames if the pack exceeds these limits.
Do not mix these forms. Pack media uses the sticker_pack encryption type; its thumbnail uses sticker_pack_thumbnail with the pack's media key. Authenticate downloaded media before parsing its archive. Archive file names are flat names, and malformed or oversized archives fail. A pack is a separate message, not an installed-pack inventory.
Manage favorites and recents#
| Task | API | Required scope |
|---|---|---|
| Favorite or unfavorite | API Set sticker favorite | profile:write |
| Remove a recent sticker | API Remove recent sticker | profile:write |
| Request media reupload | API Request sticker reupload | media:read |
| Request recent history | API Bootstrap recent stickers | messages:read |
| Read the hosted catalog | API List stored stickers | Both messages:read and media:read |
Identify a sticker with its base64 SHA-256. Favoriting also needs its matching media reference. Unfavoriting uses the hash and explicit favorite: false. Removing a recent needs the exact observed lastStickerSentTs in milliseconds, including zero when observed. A later use survives an older removal.
API
if (sticker.lastStickerSentTs !== undefined) {
await messaging.stickers.removeRecent(numberId, {
fileSha256: sticker.fileSha256,
lastStickerSentTs: sticker.lastStickerSentTs,
});
}
const receipt = await messaging.stickers.bootstrapRecents(numberId);
console.log(receipt.data.data.status); // requestedCLI
polymorfa sticker list --session "$NUMBER_ID" --collection favorite --json
polymorfa sticker recents bootstrap --session "$NUMBER_ID"
polymorfa sticker recent remove "$FILE_SHA256" --session "$NUMBER_ID" \
--last-used-ms "$OBSERVED_LAST_USED_MS"requested confirms a request to the primary phone. It does not confirm that the phone returned history or uploaded media. Apply later sticker.update events and history results. A missing response or UNKNOWN result remains unconfirmed. Do not automatically repeat an uncertain write; retain the original business idempotency key when reconciling it.
Choose where to keep the catalog#
Customer-owned storage reducers keep sticker state in your database. Upgrade a persistent store with the additive schema 3 migration before using its sticker entity. Receiving another person's sticker never adds it to your own recents.
The hosted catalog needs HMS, live access and separate sticker-storage terms. Existing Chats acceptance alone does not authorize this account state. Read one page at a time with collection, limit and the returned nextCursor. The catalog covers retained favorites and recents; it does not list every installed pack. Browser views receive display data, and unavailable media stays disabled.
Use stickers in Chats#
Console
Open a conversation and select Stickers beside the message composer. Choose Recent, Favorites or Packs, then select a sendable item. Owner/admin access with sticker management permission exposes favorite, remove and phone request actions. Media without a sendable reference shows Media unavailable.
Open Sticker storage to review the exact terms for the selected Number. Storage terms are also available in the owning scope's Chats settings, including when sending is unavailable. Acceptance and withdrawal are confirmed only after the change succeeds. After an unconfirmed change, refresh before acting again.
See sticker troubleshooting for unavailable media and pending phone requests.
Upgrade an existing sticker sender#
Replace the old descriptor isAnimated field with stickerType: static, animated or lottie. Keep the descriptor's type when forwarding or uploading preconverted media. Select API version 2026-11-10 explicitly until the release advances the default. Use a matching SDK or CLI release once it is published.
Customer-owned stores need the additive schema 3 migration before reducing sticker account updates. Preserve exact observed millisecond timestamps and unknown or failed phone results. The shared React and web-component drawers accept canSend: false for retained entries without usable media. Keep media keys and send descriptors in the authorized data source, outside the view.