Mensagens de imagem WhatsApp
Uma mensagem de imagem carrega uma URL pública que WhatsApp busca no momento do envio, com uma legenda opcional abaixo dela.
Enviar uma imagem
Defina image.url:
const msg = await bird.whatsapp.send({
to: "+16505551234",
from: "+13124495648",
image: { url: "https://cdn.example.com/receipt.png" },
});
console.log(msg.id, msg.status);msg = client.whatsapp.send(
to="+16505551234",
from_="+13124495648",
image={"url": "https://cdn.example.com/receipt.png"},
)
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",
Image: &bird.WhatsAppImageSend{Url: "https://cdn.example.com/receipt.png"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$image = (new WhatsAppMessageSendRequestImage())
->setUrl('https://cdn.example.com/receipt.png');
$message = $bird->whatsapp->send(
to: '+16505551234',
from: '+13124495648',
image: $image,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--from +13124495648 \
--image https://cdn.example.com/receipt.png \
--to +16505551234{
"name": "whatsapp_send",
"arguments": {
"from": "+13124495648",
"image": {
"url": "https://cdn.example.com/receipt.png"
},
"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",
"image": {
"url": "https://cdn.example.com/receipt.png"
}
}'A estrutura completa adiciona um caption opcional:
Exemplo de código
{
"to": "+16505551234",
"from": "+13124495648",
"image": {
"url": "https://cdn.example.com/receipts/a1b2c3.png",
"caption": "Your receipt for order A1B2C3"
}
}image não tem o campo filename. from é obrigatório em toda mensagem de serviço: um número que o seu espaço de trabalho possui, não um gerenciado por Bird.
Limites
| Campo | Limite | Aplicado por |
|---|---|---|
| Tamanho do arquivo | 5 MB | somente WhatsApp, ao buscar (async) |
| Tipo de arquivo | JPEG ou PNG | somente WhatsApp, ao buscar (async) |
| caption | até 1.024 caracteres | Bird, ao aceitar (422) |
| url | absoluta, https, tem host, sem espaço bruto | Bird, ao aceitar (422) |
Bird verifica o formato da URL e o comprimento da legenda antes de enfileirar qualquer coisa. Ele não verifica o tamanho ou tipo real do arquivo; somente a busca do WhatsApp no momento do envio pode fazer isso. Consulte envio de mídia por URL do hub para saber o que essa verificação de formato cobre, e quando a mídia falha para o que acontece quando a busca do WhatsApp rejeita o arquivo.
Lendo uma imagem recebida
Uma imagem recebida carrega o mesmo objeto image, mais um id e mime_type que Bird obteve ao buscar o arquivo. Ambos estão ausentes em uma leitura de mensagem enviada, já que Bird nunca buscou o arquivo que enviou. Consulte Recebendo imagens WhatsApp para a leitura completa de entrada, o payload whatsapp.received e o que observar.
Limites e modos de falha
- A janela de atendimento ao cliente precisa estar aberta. Imagens são mensagens de serviço, entregáveis somente dentro de uma janela aberta; consulte a janela de atendimento ao cliente do hub.
- Bird rejeita http; WhatsApp mesmo é que buscaria. Essa distinção, e o restante da verificação de formato da URL, estão em envio de mídia por URL do hub.
- Um arquivo grande demais, um tipo MIME errado ou uma URL inacessível falham da mesma forma, e depois de você ser cobrado. Consulte quando a mídia falha do hub para media_rejected e o fato da cobrança em caso de falha.
- WhatsApp armazena em cache uma URL buscada por cerca de 10 minutos. Reenviar a mesma URL dentro dessa janela reutiliza a primeira busca em vez de buscar novamente; altere a URL (um parâmetro de query, por exemplo) para forçar uma nova busca.
Próximos passos
- Mensagens de serviço WhatsApp: a janela de atendimento ao cliente e o modelo que toda mensagem de serviço compartilha
- Vídeo: a mesma estrutura para um clipe de vídeo
- Documentos: para um PDF, planilha ou outro arquivo
- Enviando mensagens WhatsApp: o envelope de solicitação, o modelo 202 e novas tentativas seguras
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