Documentation
Sign inGet started

WhatsApp video messages

A video message carries a public URL WhatsApp fetches at send time, with an optional caption underneath it.

Send a video

Set video.url:
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  video: { url: "https://cdn.example.com/unboxing.mp4" },
});
console.log(msg.id, msg.status);
The full shape adds an optional caption:
Ejemplo de código
{
  "to": "+16505551234",
  "from": "+13124495648",
  "video": {
    "url": "https://cdn.example.com/unboxing.mp4",
    "caption": "How to set it up"
  }
}
video 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 size16 MBWhatsApp only, at fetch (async)
FormatMP4 container, H.264 video, AAC audioWhatsApp 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, container, or codec; only WhatsApp's own fetch at send time can. See the hub's sending media by URL and when media fails.

Reading an inbound video

An inbound video carries the same video object, plus an id and mime_type Bird learned by fetching the file:
Ejemplo de código
{
  "id": "wam_01kya2c9hoswt3v6d0m5r8ynjg",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "video": {
    "id": "waf_01kyb2m4xq7whs0d8n3prv6tez",
    "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kya2c9hoswt3v6d0m5r8ynjg/media/waf_01kyb2m4xq7whs0d8n3prv6tez",
    "mime_type": "video/mp4",
    "caption": "Is this the part you meant?"
  },
  "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 video, see Receiving WhatsApp messages.

Limits and failure modes

  • The customer service window has to be open. Video is a service message, deliverable only inside an open window; see the hub's customer service window.
  • Bird rejects http; WhatsApp itself would fetch it. See the hub's sending media by URL for the full shape check.
  • A rejected fetch still gets charged. See the hub's when media fails for media_rejected and the charge-on-failure fact. Video's own rejection text from WhatsApp hasn't been independently measured the way image's has, so treat the mapping as inferred by symmetry rather than confirmed per cause.
  • WhatsApp caches a fetched URL for about 10 minutes. Resending the identical URL inside that window re-serves the first fetch; vary the URL to force a fresh one.
  • An animated GIF isn't a distinct type. WhatsApp doesn't have a gif message type; an animated GIF you send arrives to the recipient, and would arrive back to you inbound, as an ordinary video with an MP4 MIME type.

Next steps