Media

Base: /v2/media

Auth + Premium/Enterprise + active plan required. See HTTP API v2 Overview.

---

POST /v2/media/upload

Uploads bytes to Meta POST /{phone-number-id}/media and returns a mediaId for use with send media and templates.

Limits: maximum 100 MB per request (WhatsApp ceiling).

Phone number: phoneNumberId must belong to your account (same rules as message sends).

Mode A — multipart/form-data

Field	Required	Description
file	yes	File part
phoneNumberId	yes	Meta phone number ID
type	no	MIME hint if the part has a generic type

Example (curl):

curl -sS -X POST "https://api.avenping.com/v2/media/upload" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "phoneNumberId=YOUR_META_PHONE_NUMBER_ID" \
  -F "file=@/path/to/photo.jpg;type=image/jpeg"

Response 200:

{
  "success": true,
  "data": {
    "mediaId": "1234567890"
  }
}

Mode B — raw body (buffer / stream)

Same pattern as the main AvenPing app upload route: the body is the raw file bytes.

Header	Required	Description
Content-Type	recommended	File MIME type (e.g. image/jpeg)
X-Phone-Number-Id	yes	Meta phone number ID (also accepts phoneNumberId header)
X-Filename	no	Original filename (default file)
X-Upload-Type	no	Optional MIME override

Example (curl):

curl -sS -X POST "https://api.avenping.com/v2/media/upload" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Phone-Number-Id: YOUR_META_PHONE_NUMBER_ID" \
  -H "X-Filename: photo.jpg" \
  -H "Content-Type: image/jpeg" \
  --data-binary "@/path/to/photo.jpg"

Response 200: same as multipart.

Meta / validation errors

Failures from Meta are returned as JSON with success: false, HTTP status aligned when possible (e.g. 400), message from Meta, and the raw Graph payload in details when available (same style as other proxied Graph calls).

---

GET /v2/media/:mediaId/download

Path: mediaId — Meta media ID.
Query (optional): disposition — inline (default) or attachment (affects Content-Disposition).

Success: binary stream, not JSON.

Example request (save to file):

curl -sS -L "https://api.avenping.com/v2/media/MEDIA_ID_FROM_META/download?disposition=attachment" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o "download.bin"

Response 200 (headers — body is raw bytes):

Header	Example value
Content-Type	image/jpeg (from Meta)
Content-Length	48291
Content-Disposition	attachment or inline

Response 404 (JSON):

{
  "success": false,
  "error": "NOT_FOUND",
  "message": "Media URL not found"
}

---

Related

• Messages (sending media messages)
• HTTP API v2 Overview