# Stickers and sticker packs

> Send stickers and packs, manage favorites and recents, and handle phone synchronization results.

> **Note**
>
> Release candidate. These sticker operations are not yet available in staging or production. API version `2026-11-10` and matching released packages are required.

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.

```bash cURL
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"}}}'
```

```typescript TypeScript
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:**

```bash
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 | `PUT /messaging/{session}/stickers/favorite` | `profile:write` |
| Remove a recent sticker | `POST /messaging/{session}/stickers/recents/remove` | `profile:write` |
| Request media reupload | `POST /messaging/{session}/stickers/reuploads` | `media:read` |
| Request recent history | `POST /messaging/{session}/stickers/recents/bootstrap` | `messages:read` |
| Read the hosted catalog | `GET /messaging/{session}/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:**

```typescript
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); // requested
```

**CLI:**

```bash
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](https://docs.polymorfa.com/faqs/stickers) 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.
