WhatsApp Media Messages

Send images, videos, documents, and audio over WhatsApp. Media can be referenced either by a public link or by a media_id returned from the upload endpoint. Like all non-template messages, media can only be sent inside the 24-hour window.

📡 Endpoints

POST /v1/whatsapp/media          # Upload media, returns a media_id
GET  /v1/whatsapp/media/:id      # Retrieve / download media
POST /v1/whatsapp/messages       # Send a media message

📁 Supported Types & Limits

Type	Formats	Max size
image	JPEG, PNG	5 MB
video	MP4, 3GPP (H.264 + AAC)	16 MB
audio	AAC, MP3, AMR, OGG (Opus)	16 MB
document	PDF, DOC(X), XLS(X), PPT(X), TXT	100 MB

⬆️ Upload Media

curl -X POST https://api.afriroute.ai/api/v1/whatsapp/media \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -F "[email protected]" \
  -F "type=image/jpeg"

{
  "media_id": "media_abc123",
  "type": "image/jpeg",
  "expires_at": "2026-06-27T10:30:00Z"
}

Uploaded media is retained for 30 days. For frequently sent assets, upload once and reuse the media_id.

🖼️ Send by Link

curl -X POST https://api.afriroute.ai/api/v1/whatsapp/messages \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+251911234567",
    "type": "image",
    "image": {
      "link": "https://example.com/product.jpg",
      "caption": "Check out this new product!"
    }
  }'

🆔 Send by media_id

await fetch('https://api.afriroute.ai/api/v1/whatsapp/messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer $AFRIROUTE_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '+251911234567',
    type: 'document',
    document: {
      id: 'media_abc123',
      filename: 'invoice.pdf',
      caption: 'Your March invoice'
    }
  })
});

import requests

requests.post(
    'https://api.afriroute.ai/api/v1/whatsapp/messages',
    headers={'Authorization': 'Bearer $AFRIROUTE_API_KEY'},
    json={
        'to': '+251911234567',
        'type': 'video',
        'video': {
            'id': 'media_xyz789',
            'caption': 'Product demo'
        }
    }
)

⬇️ Download Inbound Media

When a user sends you media, the webhook delivers a media_id. Fetch the binary with:

curl https://api.afriroute.ai/api/v1/whatsapp/media/media_inbound123 \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  --output received.jpg

📊 Response

{
  "messaging_product": "whatsapp",
  "message_id": "wamid.HBgM...",
  "to": "+251911234567",
  "status": "accepted"
}

💡 Best Practices

• Reuse media_id for repeat sends instead of re-uploading.
• Host links over HTTPS — plain HTTP links are rejected.
• Compress before upload to stay within type limits and speed delivery.
• Use audio (not document) for voice notes so they play inline.
• Set a meaningful filename on documents — it is what the user sees.
• Captions are not supported on audio messages.

⚠️ Error Handling

Code	Description	Solution
131053	Media upload error	Check format and size
131052	Media download error	Re-host or re-upload the file
130429	Rate limit reached	Back off and retry

📚 Related Resources

• Send Message
• Templates
• Interactive Messages
• Webhooks

---

Need help? Contact Support → | Last Updated: May 2026