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);msg = client.whatsapp.send(
to="+16505551234",
from_="+13124495648",
video={"url": "https://cdn.example.com/unboxing.mp4"},
)
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",
Video: &bird.WhatsAppVideoSend{Url: "https://cdn.example.com/unboxing.mp4"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$video = (new WhatsAppMessageSendRequestVideo())
->setUrl('https://cdn.example.com/unboxing.mp4');
$message = $bird->whatsapp->send(
to: '+16505551234',
from: '+13124495648',
video: $video,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--from +13124495648 \
--to +16505551234 \
--video https://cdn.example.com/unboxing.mp4curl -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",
"video": {
"url": "https://cdn.example.com/unboxing.mp4"
}
}'The full shape adds an optional caption:
Code example
{
"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
| Field | Bound | Enforced by |
|---|---|---|
| File size | 16 MB | WhatsApp only, at fetch (async) |
| Format | MP4 container, H.264 video, AAC audio | 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, 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. Both are absent on an outbound read-back, since Bird never fetched the file it sent. See Receiving WhatsApp video for the inbound read in full, the whatsapp.received payload, and what to watch for.
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
- WhatsApp service messages: the customer service window and the model every service message shares
- Images: the same shape for a photo or graphic
- Audio: for a voice note or audio clip
- Sending WhatsApp messages: the request envelope, the 202 model, and safe retries
Related resources
Continue with the documentation, guides and examples for this topic. Resources are in English.
Watch the guideConnecting WhatsApp to Bird: from buying a number to a live channelUnderstand the conceptWhat is the 24-hour customer service window on WhatsApp?Use the toolWhatsApp message builderExplore the capabilityWhatsApp
Try the practice and get an implementation brief