How to send file from your local computer using the API

We will explain what “Upload from file” means and show how to do it in different programming languages using the multipart/form-data format

Whapi.Cloud supports sending media files (images, documents, audio, etc.) using several methods:

• By URL;

• By Base64;

• By media ID (after a file is uploaded);

• By directly uploading the file from your local computer;

This article explains how to use the "Upload from file" option — one of the most commonly misunderstood steps for new developers.

---

One of the most common points of confusion for new developers working with media upload is the "Upload from File" option. While uploading by URL or Base64 is relatively straightforward, sending a file from your local machine using code requires a clear understanding of how multipart/form-data works in HTTP.

What Does "Upload from File" Mean?

When using "Media with upload from file", you are expected to send the file as binary data (not a path or URL) inside the request body using the multipart/form-data format. This is the same method used when uploading files through forms on websites.

⚠️ A common mistake is trying to send a local file path or localhost URL like: "media": "http://localhost:8080/files/logo.png" This will not work — the API doesn't know how to access your local system.

Instead, you must send the actual file content as part of the HTTP request.

Sending a media file works via multipart/form-data or via a Base64 string with the appropriate prefix. Both methods are valid. You can choose the one that best suits your development environment.

Read more about Sending File as Base64.

Sending File via multipart/form-data

You can upload the file directly in binary form using multipart/form-data. This is how file uploads typically work in forms and in Postman.

Examples:

cURL

curl -X POST https://gate.whapi.cloud/messages/image \
  -H "Authorization: Bearer {YOUR_TOKEN}" \
  -F 'to=919984351847' \
  -F 'caption=Hello, this message was sent via API!' \
  -F 'media=@/path/to/your/file.png'

Python

import requests

url = 'https://gate.whapi.cloud/messages/image'
token = 'YOUR_TOKEN'

data = {
    'to': '919984351847',
    'caption': 'Hello, this message was sent via API!'
}

files = {
    'media': open('file.png', 'rb')
}

headers = {
    'Authorization': f'Bearer {token}'
}

response = requests.post(url, data=data, files=files, headers=headers)
print(response.json())

Note: Python automatically formats the request as multipart/form-data when using the files parameter.

PHP

<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://gate.whapi.cloud/messages/image');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);

$headers = [
    'Authorization: Bearer YOUR_TOKEN'
];

$data = [
    'to' => '919984351847',
    'caption' => 'Hello, this message was sent via API!',
    'media' => new CURLFile('file.png')
];

curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Note: CURLFile ensures that the file is sent as multipart/form-data. The API will handle the rest.

Node.js

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const form = new FormData();
form.append('to', '919984351847');
form.append('caption', 'Hello, this message was sent via API!');
form.append('media', fs.createReadStream('./file.png'));

axios.post('https://gate.whapi.cloud/messages/image', form, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    ...form.getHeaders()
  }
})
.then(response => console.log(response.data))
.catch(error => console.error(error.response?.data || error.message));