# Figurinhas e pacotes de figurinhas

> Envie figurinhas e pacotes, gerencie favoritas e recentes e acompanhe os pedidos ao celular.

> **Note**
>
> Versão candidata. Estas operações de figurinhas ainda não estão disponíveis em homologação ou produção. Elas exigem a versão `2026-11-10` da API e os pacotes correspondentes publicados.

Use um número de Dispositivos vinculados para enviar uma figurinha ou um pacote.
Figurinhas recebidas têm `type: "sticker"`. Pacotes recebidos têm
`type: "sticker_pack"`. Essas operações usam a versão `2026-11-10` da API.

## Enviar uma figurinha

Em `content.sticker`, informe apenas uma fonte: `url` HTTPS, imagem em `base64`
ou `descriptor` já convertido. Use `accessibilityLabel` para descrever a imagem.

**API:**

```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":"Uma pessoa acenando"}}}'
```

```typescript TypeScript
await messaging.messages.send(numberId, {
  conversation: { phoneNumber: "+15550001111" },
  content: {
    sticker: {
      url: "https://example.com/wave.png",
      accessibilityLabel: "Uma pessoa acenando",
    },
  },
}, { apiVersion: "2026-11-10", idempotencyKey: sendKey });
```

**CLI:**

```bash
polymorfa message send sticker --session "$NUMBER_ID" \
  --to +15550001111 --file ./wave.png --label "Uma pessoa acenando"
```

A conversão aceita PNG, JPEG, GIF, WebP, APNG, AVIF e HEIC dentro destes limites:
20 MiB de entrada, 16 milhões de pixels na tela, 64 milhões de pixels somados nos
quadros, 300 quadros, 30 segundos e 1 MiB de saída. Imagens incompatíveis ou acima
dos limites falham. Sessões com Signal sob custódia do cliente mantêm a exigência
de descritores de mídia já convertida.

A conversão também recusa imagens que excedem o orçamento de memória. Reduza as dimensões ou a quantidade de quadros quando isso acontecer.

Descritores estáticos ou animados usam `mimeType: "image/webp"`. Descritores
Lottie usam `stickerType: "lottie"` e `mimeType: "application/was"`.

## Enviar um pacote

Escolha apenas uma forma de `content.stickerPack`: criar o pacote com ID, nome,
editor e até 100 imagens; fornecer um arquivo validado com descritor e metadados;
ou encaminhar um pacote recebido com `forwardMedia`.

As imagens e uma miniatura explícita compartilham 64 MiB de entrada e 128 milhões
de pixels, somando as telas de origem e os quadros de saída de 512 pixels de todo
o pacote. A preparação para no prazo da solicitação ou em 30 segundos, o que vier
primeiro. Reduza a quantidade de imagens, as dimensões ou os quadros da animação
se o pacote exceder esses limites.

O pacote usa o tipo de criptografia `sticker_pack`. A miniatura usa
`sticker_pack_thumbnail` com a mesma chave de mídia. Autentique a mídia baixada
antes de ler o arquivo. Arquivos com caminhos de diretórios, conteúdo inválido
ou tamanho excessivo são recusados. Um pacote é uma mensagem separada; ele não
representa a lista de pacotes instalados no celular.

## Gerenciar favoritas e recentes

| Tarefa | Operação | Escopo |
| --- | --- | --- |
| Favoritar ou remover dos favoritos | `PUT /messaging/{session}/stickers/favorite` | `profile:write` |
| Remover uma figurinha recente | `POST /messaging/{session}/stickers/recents/remove` | `profile:write` |
| Solicitar novo envio da mídia | `POST /messaging/{session}/stickers/reuploads` | `media:read` |
| Solicitar histórico recente | `POST /messaging/{session}/stickers/recents/bootstrap` | `messages:read` |
| Ler o catálogo hospedado | `GET /messaging/{session}/stickers` | `messages:read` e `media:read` |

Identifique a figurinha pelo SHA-256 em base64. Para favoritar, forneça também a
referência de mídia correspondente. Para remover dos favoritos, envie o hash e
`favorite: false`. A remoção de recentes exige o valor observado de
`lastStickerSentTs` em milissegundos, incluindo zero quando esse for o valor.
Um uso posterior não é apagado por uma remoção anterior.

`requested` confirma o pedido ao celular principal. Não confirma a chegada do
histórico nem o envio da mídia. Aplique os eventos `sticker.update` e os
resultados de histórico posteriores. Uma resposta ausente ou `UNKNOWN` continua
sem confirmação. Não repita gravações de resultado incerto automaticamente.
Preserve a mesma chave de idempotência ao reconciliar a operação.

## Armazenamento

Os redutores de armazenamento do cliente mantêm o estado no seu banco. Aplique a
migração aditiva do esquema 3 antes de usar a entidade de figurinhas em um banco
existente. Receber uma figurinha de outra pessoa não a adiciona às suas recentes.

O catálogo hospedado exige HMS, acesso válido e aceite separado dos termos de
armazenamento de figurinhas. O aceite de Chats sozinho não autoriza esse estado.
Use `collection`, `limit` e o `nextCursor` retornado para paginar. O catálogo
contém favoritas e recentes retidas, sem enumerar todos os pacotes instalados.

## Usar em Chats

**Console:**

Abra uma conversa e selecione **Figurinhas** ao lado do campo de mensagem.
Escolha **Recentes**, **Favoritas** ou **Pacotes** e selecione um item disponível
para envio. As ações de gerenciamento exigem acesso de proprietário ou
administrador e a permissão correspondente. Referências sem mídia disponível
permanecem desabilitadas.

Abra **Armazenamento de figurinhas** para ler os termos do número selecionado.
Os termos também ficam nas configurações de Chats do escopo, inclusive quando
o envio está indisponível. Aceite e retirada só são confirmados após a conclusão
da alteração. Se o resultado estiver incerto, atualize antes de agir novamente.

Veja [problemas com figurinhas](https://docs.polymorfa.com/pt-br/faqs/stickers).

## Atualizar um envio de figurinha existente

Substitua o campo antigo `isAnimated` do descritor por `stickerType`: `static`,
`animated` ou `lottie`. Preserve o tipo do descritor ao encaminhar mídia ou enviar
mídia já convertida. Selecione explicitamente a versão `2026-11-10` da API até
que o lançamento atualize o padrão. Use uma versão correspondente do SDK ou da
CLI quando ela for publicada.

Armazenamentos próprios precisam da migração aditiva para o esquema 3 antes de
aplicar atualizações da conta. Preserve os horários observados em milissegundos
e os resultados desconhecidos ou com falha do celular. As gavetas compartilhadas
para React e web components aceitam `canSend: false` para entradas retidas sem
mídia utilizável. Mantenha chaves de mídia e descritores de envio na fonte de
dados autorizada, fora da interface.
