Figurinhas e pacotes de figurinhas
Envie figurinhas e pacotes, gerencie favoritas e recentes e acompanhe os pedidos ao celular.
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
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"}}}'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
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 | API Set sticker favorite | profile:write |
| Remover uma figurinha recente | API Remove recent sticker | profile:write |
| Solicitar novo envio da mídia | API Request sticker reupload | media:read |
| Solicitar histórico recente | API Bootstrap recent stickers | messages:read |
| Ler o catálogo hospedado | API List stored 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.
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.