Skip to main content

​
What it is

The Media API uploads an image, video, audio file, sticker, or document through the WhatsApp Business API. The returned media ID can be referenced by a later WhatsApp message request.

​
Before you begin

  • Connect and register the sending WhatsApp phone number.
  • Store your YCloud API key securely.
  • Prepare a file that meets Meta’s supported media type and size limits.
  • Know whether the target message type supports a media ID or requires a URL.

​
How it works

  1. Upload the file for the sending phone number.
  2. Store the returned media ID.
  3. Put the media ID in the matching WhatsApp message content object.
  4. Send the message before the uploaded media expires.
Uploaded files are encrypted and persist for 30 days.

​
Request

POST /whatsapp/media/{phoneNumber}/upload Send the file as multipart/form-data.
Use the registered business phone number in E.164 format.

​
Response

Store id and use it in the media object for a supported WhatsApp message request.

​
Media usage

A media ID is tied to WhatsApp media storage and expires after 30 days. Upload again when the ID is no longer valid. Interactive message headers cannot use a media ID for images, documents, videos, or audio. Use a publicly accessible link for those header elements.

​
Limits and troubleshooting

  • Send the correct MIME type with the uploaded file.
  • Check Meta’s supported media types and size limits before uploading.
  • Do not reuse an expired media ID.
  • Keep the upload and message sender phone number aligned.
  • For reusable public assets, a link may be simpler than repeated uploads when the message schema supports it.

Upload media API

Inspect the multipart request and response schema.

Send media messages

Add the returned media ID to a WhatsApp message request.