WhatsApp image messages
An image message carries a public URL WhatsApp fetches at send time, with an optional caption underneath it.
Send an image
Set 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 \
--to +16505551234 \
--from +13124495648 \
--image https://cdn.example.com/receipt.pngcurl -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"
}
}'The full shape adds an optional caption:
Codevoorbeeld
{
"to": "+16505551234",
"from": "+13124495648",
"image": {
"url": "https://cdn.example.com/receipts/a1b2c3.png",
"caption": "Your receipt for order A1B2C3"
}
}image has no filename field. from is required on every service message: a number your workspace owns, not a Bird-managed one.
Limits
| Field | Bound | Enforced by |
|---|---|---|
| File size | 5 MB | WhatsApp only, at fetch (async) |
| File type | JPEG or PNG | WhatsApp only, at fetch (async) |
| caption | up to 1024 characters | Bird, at accept (422) |
| url | absolute, https, has a host, no raw space | Bird, at accept (422) |
Bird checks the URL's shape and the caption's length before anything is enqueued. It does not check the file's actual size or type; only WhatsApp's own fetch at send time can. See the hub's sending media by URL for what that shape check covers, and when media fails for what happens when WhatsApp's fetch rejects the file.
Reading an inbound image
An inbound image carries the same image object, plus an id and mime_type Bird learned by fetching the file:
Codevoorbeeld
{
"id": "wam_01kya19eknftrs2s6p82asmvnh",
"direction": "inbound",
"from": { "phone_number": "+14155550100" },
"to": { "phone_number": "+13124495569" },
"image": {
"id": "waf_01kyb2m4xq7whs0d8n3prv6tez",
"url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kya19eknftrs2s6p82asmvnh/media/waf_01kyb2m4xq7whs0d8n3prv6tez",
"mime_type": "image/jpeg",
"caption": "Is this the right part?"
},
"status": "received"
}id and mime_type are absent on an outbound read-back, since Bird never fetched the file it sent. To fetch the bytes behind an inbound image, see Receiving WhatsApp messages.
Limits and failure modes
- The customer service window has to be open. Images are service messages, deliverable only inside an open window; see the hub's customer service window.
- Bird rejects http; WhatsApp itself would fetch it. That distinction, and the rest of the URL shape check, live on the hub's sending media by URL.
- An oversize file, a wrong MIME type, or an unreachable URL all fail the same way, and after you're charged. See the hub's when media fails for media_rejected and the charge-on-failure fact.
- WhatsApp caches a fetched URL for about 10 minutes. Resending the identical URL inside that window re-serves the first fetch rather than fetching again; vary the URL (a query parameter, for instance) to force a fresh one.
Next steps
- WhatsApp service messages: the customer service window and the model every service message shares
- Video: the same shape for a video clip
- Documents: for a PDF, spreadsheet, or other file
- How sending works: the request envelope, the 202 model, and safe retries