POST /v1/media/upload

Uploads a file to WhatsApp and returns a media_id. Use it as image.id, video.id, audio.id or document.id in a message send, or as the media of a template header.

Upload when the file isn’t publicly reachable, or when you’ll send the same file many times. Otherwise you can pass a public link in the send itself and skip this step.

POST /v1/media/upload
Authorization: Bearer hello_live_xxxxxxxxxxxxxxxx
Content-Type: multipart/form-data

Example: multipart upload

curl -X POST $HELLO_API_URL/v1/media/upload \
  -H "Authorization: Bearer $HELLO_API_KEY" \
  -F "phone_number=15551234567" \
  -F "file=@./invoice-INV-2291.pdf;type=application/pdf" \
  -F "filename=Invoice INV-2291.pdf"

Example: base64 data URI

If your system already sends files as base64, post them URL-encoded as a data:<mime>;base64,<payload> URI:

curl -X POST $HELLO_API_URL/v1/media/upload \
  -H "Authorization: Bearer $HELLO_API_KEY" \
  --data-urlencode "phone_number=15551234567" \
  --data-urlencode "file=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…"

Form fields

Field	Type	Required	Description
`phone_number`	string	Yes	The sending WhatsApp number the media is for, digits only with country code, for example `15551234567`. It’s matched exactly against your connected number.
`file`	file or string	Yes	The file (multipart), or a `data:<mime>;base64,<payload>` URI
`filename`	string	No	File name the recipient sees for documents. Defaults to the uploaded file’s name.

The file type comes from its declared MIME type, then its extension, then its contents. A file whose contents clearly contradict the declared type is rejected. See supported media for allowed types and sizes.

Response `200`

{
  "media_id": "1099999999993456",
  "mime_type": "application/pdf",
  "bytes": 184320
}

A media_id is valid for about 30 days, and only for the number it was uploaded under. Send it from the same number, using its phone_number_id in the send URL.

Errors

Status	`code`	Cause
`400`	`MISSING_PHONE_NUMBER`	`phone_number` wasn’t sent
`400`	`MISSING_FILE`	No `file`, or a `file` value that isn’t a valid data URI
`400`	`INVALID_MEDIA`	Unsupported type, file too large or empty, or contents that don’t match the declared type
`401`	`UNAUTHORIZED`	Missing, wrong or disabled API key
`404`	`ACCOUNT_NOT_FOUND`	No connected number in your organization matches `phone_number`
`413`		The request body is larger than the server allows
`4xx`	`UPLOAD_REJECTED`	WhatsApp rejected the file. `message` has WhatsApp’s explanation.
`502`	`UPLOAD_REJECTED`	WhatsApp rejected Hello’s credentials for this number. Contact support.
`500`	`UPLOAD_FAILED`	Temporary error. Retry.