How to upload and download media via API v2 ​

WhatsApp media IDs come from Meta after you upload bytes. In AvenPing API v2, use POST /v2/media/upload (not POST /v2/media) with phoneNumberId, then pass mediaId in messages or templates. Download with GET /v2/media/:mediaId/download. Details: Media.

Prerequisites ​

  • An API token on Premium or Enterprise. See How to generate an API token.
  • A phoneNumberId from GET /v2/me.
  • A file within 100 MB and WhatsApp type limits.

Step-by-step ​

  1. Get phoneNumberId
    Call GET /v2/me.

  2. Upload
    POST /v2/media/upload as multipart file plus phoneNumberId, or raw body with X-Phone-Number-Id. The JSON includes data.mediaId.

  3. Use the mediaId
    Send it in POST /v2/messages/send/media or as a template header component. See Messages and Templates.

  4. Download if needed
    GET /v2/media/:mediaId/download returns a binary stream. Optional phoneNumberId or accountId selects the WABA token. Missing URL returns JSON 404.

WARNING

There is no POST /v2/media route. Only POST /v2/media/upload.

FAQ ​

Can I use a template example header_handle?

Production sends should use a mediaId from this upload (or another Meta-accepted handle your integration supports). The send route does not copy template examples.

Upload failed with VALIDATION_ERROR

Check file type, size (100 MB max), and that phoneNumberId is owned by the token. Meta payload may appear in details.

Is inbox paperclip the same as this API?

The inbox uploads through the app. This how-to is for server integrations. Both end as Meta media IDs.