Skip to main content
Send a media message by URL or by direct file upload. Requires an open 24-hour session, same as free-form text.

​
Endpoint

POST /api/v1/{subdomain}/messages/media
Required ability: messages.send.

​
Headers

HeaderValue
AuthorizationBearer apitk_...
Content-Typeapplication/json or multipart/form-data
Acceptapplication/json
Use multipart/form-data when uploading via media_file. Use application/json when referencing media_url.

​
Path parameters

​
subdomain
string
required
Your workspace subdomain.

​
Body parameters

​
phone_number
string
required
Recipient phone number. 10–15 characters.
​
media_type
string
required
One of image, document, video, audio. Stickers are not supported via API.
​
media_url
string
Public URL of the media asset. Required if media_file is not supplied.
​
media_file
file
Uploaded media file. Required if media_url is not supplied.
​
caption
string
Caption for image, video, or document. Max 1024 characters.
​
filename
string
Display filename for document messages. Max 255 characters.
​
contact
object
Optional contact payload for creating or updating the contact behind this send.

​
Example request

curl -X POST https://dash.xobito.com/api/v1/acme/messages/media \
  -H "Authorization: Bearer apitk_your_token_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "media_type": "image",
    "media_url": "https://example.com/invoice.png",
    "caption": "Your invoice"
  }'

​
Example response

200 OK
{
  "status": "success",
  "message": "Media message sent successfully",
  "data": {
    "message_id": "wamid.HBgLMTQxNTU1NTEyMzQVAgARGBI5QUQ1N...",
    "contact_id": 451,
    "phone": "+14155551234",
    "status": "sent",
    "sent_at": "2026-04-16T12:00:00.000000Z",
    "chat_id": 88,
    "contact_created": false
  }
}

​
Error responses

StatusWhenExample body
401Missing / invalid token{"status":"error","message":"Invalid API token"}
403Missing ability{"status":"error","message":"Token does not have the required ability: messages.send"}
422Validation{"status":"error","message":"Validation failed","errors":{"media_url":["The media url field is required when media file is not present."]}}
429Rate limit{"message":"Too many requests","retry_after":45}
500Send failure{"status":"error","message":"Failed to send media message"}