> ## Documentation Index
> Fetch the complete documentation index at: https://developer.chatsyncs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Send File / Media
> Send an image, video, audio, or document over WhatsApp via the ChatSyncs API, using a public media URL or a media_id from Upload Media. Use when a developer asks how to send a file/image/video to a WhatsApp number.
Sends an image, video, audio, or document to a WhatsApp number — the single endpoint for all
media types.
You must provide **either `media_url` or `media_id`** — at least one is required.
## Sending a document
A document also needs **`media_name`** — the filename the recipient sees. Without it the API answers
`media_name is required when media_type is document`.
* With **`media_url`**, any filename is accepted. Use the last part of the URL, such as `invoice.pdf`.
* With **`media_id`**, pass the `media_name` that [Upload Media](/developer-api/whatsapp/upload-media) returned.
* `media_name` is only for documents. Leave it out for images, video and audio.
```bash theme={null}
curl -X POST 'https://platform.chatsyncs.com/api/v1/whatsapp/send/file' \
-d 'apiToken=API-KEY' \
-d 'phone_number_id=PHONE-NUMBER-ID' \
-d 'phone_number=PHONE-NUMBER' \
-d 'media_type=document' \
-d 'media_name=invoice.pdf' \
--data-urlencode 'media_url=https://example.com/invoice.pdf'
```
The response includes the `wa_message_id`, which you can pass to
[Get Delivery Message Status](/developer-api/whatsapp/get-message-status).
## OpenAPI
````yaml POST /whatsapp/send/file
openapi: 3.1.0
info:
title: ChatSyncs Developer API
version: 1.0.0
description: >-
REST API for sending WhatsApp messages and managing subscribers through
ChatSyncs.
**Authentication.** Send your key as the `apiToken` parameter, or as
`Authorization: Bearer ` — both work on every endpoint **except Custom
Fields List**, which only accepts the `apiToken` parameter (a Bearer header
alone is answered with *The api token field is required.*). A wrong key
returns HTTP 401 `{"status":"0","message":"Unauthenticated."}`; no key at
all redirects to the login page.
**Methods.** Every endpoint accepts both GET and POST with the same
parameters, except Upload Media, which is POST-only. Use POST for anything
that changes data.
**Errors.** Failures usually come back as HTTP 200 with `"status":"0"` and
the reason in `message`, so always check `status`. `status` is the string
`"1"` or `"0"` on most endpoints and a boolean on a few.
**Lists.** Endpoints that return rows put them in `message` as a list; there
is no `data` field (Custom Fields List is the exception and uses `data`).
servers:
- url: https://platform.chatsyncs.com/api/v1
security: []
paths:
/whatsapp/send/file:
post:
tags:
- WhatsApp API
summary: Send File / Media
description: >-
`media_type` is not validated either: an unsupported value is accepted
and the failure appears only afterwards. A success response means
ChatSyncs accepted the message; later delivery failures, such as a
`media_url` that returns 404, show up as `message_status` `failed` with
a `failed_reason` in Get Delivery Message Status and Get Conversation.
operationId: sendFile
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
apiToken:
type: string
description: >-
Your ChatSyncs API key (not a WhatsApp/Meta access token).
[Where to find
it](/developer-api/finding-ids#api-token-apitoken).
example: API-KEY
phone_number_id:
type: string
description: >-
The WhatsApp account's phone number ID. [Where to find
it](/developer-api/finding-ids#phone-number-id-phone_number_id).
example: PHONE-NUMBER-ID
phone_number:
type: string
description: >-
The subscriber's phone number, with country code, digits
only.
example: PHONE-NUMBER
media_url:
type: string
description: >-
Public HTTPS URL of the file. Required if media_id isn't
set.
example: https://example.com/image.jpg
media_id:
type: string
description: >-
A WhatsApp media ID from [Upload
Media](/developer-api/whatsapp/upload-media) or Graph.
Required if media_url isn't set; requires media_type when
used alone.
example: '1739230482390482'
media_type:
type: string
description: >-
One of image, video, audio, document. Required when using
media_id alone, or when media_url has no file extension.
example: image
media_name:
type: string
description: >-
The filename shown to the recipient. **Required when
`media_type` is `document`** (also when the type is inferred
from the URL); not used for image, video or audio. With
`media_url` any filename is accepted, such as the last part
of the URL; with a `media_id`, pass the `media_name` that
Upload Media returned.
example: invoice.pdf
media_caption_text:
type: string
description: >-
Caption for an image, video, or document (not supported for
audio). Falls back to message if omitted.
example: Here's your invoice
required:
- apiToken
- phone_number_id
- phone_number
responses:
'200':
description: >-
Standard ChatSyncs response. `status` is `"1"` on success and `"0"`
on failure.
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: '`"1"` = success, `"0"` = failure.'
message:
type: string
description: Human-readable result message.
examples:
success:
summary: Success
value:
status: '1'
wa_message_id: >-
wamid.HBgNODgwMTcyMzMwOTAwMxUCABEYEjlGQkY3MEFEMEVGODhCNDkxNQA=
message: Message sent successfully.
error:
summary: No media given
value:
status: '0'
message: media_url or media_id is required.
outsideWindow:
summary: Outside the 24-hour window
value:
status: '0'
message: >-
Sending message outside 24 hour window is not allowed. You
can only send template message to this user.
'401':
description: >-
`apiToken` is wrong. (With no token at all the API redirects to the
login page with HTTP 302 instead of returning JSON.)
content:
application/json:
schema:
type: object
properties:
status:
type: string
message:
type: string
examples:
unauthenticated:
summary: Wrong apiToken
value:
status: '0'
message: Unauthenticated.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.