Documentation
Sign inGet started

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);
The full shape adds an optional caption:
कोड उदाहरण
{
  "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

FieldBoundEnforced by
File size5 MBWhatsApp only, at fetch (async)
File typeJPEG or PNGWhatsApp only, at fetch (async)
captionup to 1024 charactersBird, at accept (422)
urlabsolute, https, has a host, no raw spaceBird, 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:
कोड उदाहरण
{
  "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