POST/api/v2/templates/media

Upload template header media

Upload an image, video, or document for a WhatsApp header. Pass assetId as headerAssetId. For official WhatsApp you may send mediaUrl instead of a file. For WhatsApp Web set targetProvider=user_session.

When to use it. Optional two-step upload. You can also attach the file directly on POST /api/v2/templates.

Code example

Correct: Upload a header image

curl --location 'https://raselsms.com/api/v2/templates/media' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"mediaType":"image","file":"<multipart binary>","note":"Content-Type: multipart/form-data"}'

Response example

201 — Upload a header image

{  "success": true,  "data": {    "media": {      "assetId": "6800asset123def4567890aaaa",      "mimeType": "image/png",      "size": 18432    }  }}

401 — Missing or invalid API key.

{  "success": false,  "requestId": "msgreq_1739012345678_abc123",  "code": "UNAUTHORIZED",  "error": "Missing or invalid API key"}

403 — Phone is not verified or the key lacks permission (usually messages:create or api_keys:read).

{  "success": false,  "requestId": "msgreq_1739012345678_abc123",  "code": "FORBIDDEN",  "error": "Phone not verified or missing permission"}

429 — Rate limit exceeded. Honor Retry-After when present.

{  "success": false,  "requestId": "msgreq_1739012345678_abc123",  "code": "RATE_LIMITED",  "error": "Rate limit exceeded",  "retryAfterSeconds": 30}

HTTP request

POST /api/v2/templates/media

Request Headers

Header	Type	Description
X-API-Key	string	Your Rasel API key. Send it on every documented request except inbound webhooks. *

Request body

Field	Type	Description
mediaType	image \| video \| document	Header media type: image, video, or document. *
file	string (binary)	Uploaded file. Alias of headerMedia on multipart create or send.
mediaUrl	string	Public HTTP(S) header media URL when not attaching a file. Official WhatsApp only on media upload.
targetProvider	user_session \| eshaar \| meta	Upload target: user_session, eshaar, or meta.

Response Fields

Field	Type	Description
success	boolean	True when the operation succeeded, or when at least one batch recipient succeeded.
data	object	Primary payload for list and snapshot endpoints.
data.media	object	Header media stored for this template.
data.media.assetId	string	Stored file id. Pass it back as headerAssetId when creating a template.
data.media.mediaHandle	string	Provider media handle, when the upload returned one.
data.media.previewUrl	string	URL you can open to preview the stored file.
data.media.mimeType	string	MIME type of the stored file.
data.media.size	integer	File size in bytes.
data.media.source	string	Wallet movement source such as usage, admin_topup, or topup_request. On media upload it is the stored asset origin.
message	string	Human-readable result message from create or upload.

Status Codes

Status	Description
201	Created.
400	Invalid request, validation error, or the resource cannot be used in this state.
401	Missing or invalid API key.
403	Phone not verified, missing permission, or the account cannot perform this action.
429	Rate limit exceeded, or the maximum number of verification attempts was reached.

Cases to handle

This path is multipart, not JSON.

Try it

This endpoint accepts a file upload (multipart/form-data). Send it from your server or a tool that can attach files — Try it only runs JSON requests.