Mensagens de sticker no WhatsApp
Uma mensagem de sticker carrega uma URL pública de WebP que o WhatsApp busca no momento do envio. É o tipo de mídia mais simples: sem legenda, sem nenhum outro campo opcional no envio.
Enviar um sticker
Defina sticker.url; não há mais nada a acrescentar:
const msg = await bird.whatsapp.send({
to: "+16505551234",
from: "+13124495648",
sticker: { url: "https://cdn.example.com/stickers/thumbs-up.webp" },
});
console.log(msg.id, msg.status);msg = client.whatsapp.send(
to="+16505551234",
from_="+13124495648",
sticker={"url": "https://cdn.example.com/stickers/thumbs-up.webp"},
)
print(msg.id, msg.status)package main
import (
"context"
"fmt"
"log"
"os"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+16505551234",
From: "+13124495648",
Sticker: &bird.WhatsAppStickerSend{Url: "https://cdn.example.com/stickers/thumbs-up.webp"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$sticker = (new WhatsAppMessageSendRequestSticker())
->setUrl('https://cdn.example.com/stickers/thumbs-up.webp');
$message = $bird->whatsapp->send(
to: '+16505551234',
from: '+13124495648',
sticker: $sticker,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--from +13124495648 \
--sticker https://cdn.example.com/stickers/thumbs-up.webp \
--to +16505551234{
"name": "whatsapp_send",
"arguments": {
"from": "+13124495648",
"sticker": {
"url": "https://cdn.example.com/stickers/thumbs-up.webp"
},
"to": "+16505551234"
}
}curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+16505551234",
"from": "+13124495648",
"sticker": {
"url": "https://cdn.example.com/stickers/thumbs-up.webp"
}
}'sticker não tem o campo caption, e animated não é algo que você define no envio; Bird apenas o retorna em um sticker recebido. from é obrigatório em toda mensagem de serviço: um número que o seu espaço de trabalho possui, não um gerenciado pelo Bird.
Limites
| Campo | Limite | Aplicado por |
|---|---|---|
| Tamanho do arquivo, estático | 100 KB | Apenas WhatsApp, no fetch (assíncrono) |
| Tamanho do arquivo, animado | 500 KB | Apenas WhatsApp, no fetch (assíncrono) |
| Tipo de arquivo | Somente WebP | Apenas WhatsApp, no fetch (assíncrono) |
| caption | campo inválido | Bird, no aceite (422, rejeição de schema) |
| url | absoluta, https, com host, sem espaço bruto | Bird, no aceite (422) |
Bird verifica o formato da URL antes de qualquer enfileiramento; não verifica o tamanho real do arquivo, o formato nem se é estático ou animado. Apenas o fetch do próprio WhatsApp no momento do envio pode fazer isso. Enviar um caption não é um erro de tamanho; o campo não existe no schema desse tipo, então falha como propriedade não reconhecida. Veja no hub enviar mídia por URL e quando a mídia falha.
Lendo um sticker recebido
Um sticker recebido carrega um id, mime_type e animated que o Bird obteve ao buscar o arquivo. Os três estão ausentes na leitura de uma mensagem enviada, já que o Bird nunca buscou nem inspecionou o arquivo que enviou. Veja Recebendo stickers do WhatsApp para a leitura completa do recebimento, o payload whatsapp.received e o que observar.
Limites e modos de falha
- A janela de atendimento ao cliente precisa estar aberta. Stickers são mensagens de serviço, entregáveis apenas dentro de uma janela aberta; veja no hub a janela de atendimento ao cliente.
- Bird rejeita http; o próprio WhatsApp faria o fetch. Veja no hub enviar mídia por URL para a verificação completa do formato.
- Um fetch rejeitado ainda é cobrado. Veja no hub quando a mídia falha. O texto de rejeição específico de sticker do WhatsApp não foi medido de forma independente, então trate o mapeamento como inferido por simetria e não como confirmado por causa.
- animated é somente leitura, e só aparece em um sticker recebido ou buscado. É o veredito do próprio WhatsApp sobre o arquivo, não algo que você possa declarar. Se o sticker é estático ou animado muda apenas o limite de tamanho; WebP é obrigatório em ambos os casos.
- WhatsApp mantém em cache uma URL buscada por cerca de 10 minutos. Reenviar a URL idêntica dentro dessa janela reutiliza o primeiro fetch; altere a URL para forçar uma nova busca.
Próximos passos
- Mensagens de serviço do WhatsApp: a janela de atendimento ao cliente e o modelo que toda mensagem de serviço compartilha
- Áudio: outro tipo de mídia sem campo de legenda
- Imagens: para uma foto ou gráfico com legenda
- Enviando mensagens do WhatsApp: o envelope de solicitação, o modelo 202 e tentativas seguras de reenvio
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.
Assista ao guiaConnecting WhatsApp to Bird: from buying a number to a live channelEntenda o conceitoWhat is the 24-hour customer service window on WhatsApp?Use a ferramentaWhatsApp message builderExplore a funcionalidadeWhatsApp
Experimente na prática e obtenha um resumo de implementação