API file multimediali
API Carica file multimediali
Carica un'immagine, un documento, un file audio o un video nella libreria multimediale del tuo spazio di lavoro e ricevi in cambio un URL di download. Passa quell'URL a Invia messaggio oppure, solo per le immagini, a Crea promemoria come img_url, quando non hai un tuo hosting per i file.
https://wbiztool.com/api/v1/media/upload/Corpo: multipart/form-data
Il file viene salvato subito e la risposta include il suo file_url. I file caricati compaiono anche nella pagina Directory Media della tua dashboard.
Esempio rapido#
curl -X POST https://wbiztool.com/api/v1/media/upload/ \
-F client_id=12345 \
-F api_key=YOUR_API_KEY \
-F media_file=@./invoice-4821.pdfimport requests
with open("invoice-4821.pdf", "rb") as f:
response = requests.post(
"https://wbiztool.com/api/v1/media/upload/",
data={"client_id": 12345, "api_key": "YOUR_API_KEY"},
files={"media_file": f},
timeout=120,
)
try:
result = response.json()
except ValueError:
# A proxy can reject a very large upload with an HTML page before it reaches Wbiztool.
raise SystemExit(f"HTTP {response.status_code}: not JSON. Check the file size.")
if result["status"] == 1:
print("Uploaded:", result["data"]["file_url"])
else:
print("Failed:", result["message"])// Node.js 20+ (built-in fetch, FormData and fs.openAsBlob). Save as .mjs to use top-level await.
import { openAsBlob } from "node:fs";
const form = new FormData();
form.append("client_id", "12345");
form.append("api_key", "YOUR_API_KEY");
form.append("media_file", await openAsBlob("./invoice-4821.pdf"), "invoice-4821.pdf");
// Don't set Content-Type yourself; fetch adds the multipart boundary.
const response = await fetch("https://wbiztool.com/api/v1/media/upload/", { method: "POST", body: form });
const result = await response.json();
if (result.status === 1) {
console.log("Uploaded:", result.data.file_url);
} else {
console.error("Failed:", result.message);
}<?php
$ch = curl_init('https://wbiztool.com/api/v1/media/upload/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
// An array body (not json_encode) makes cURL send multipart/form-data.
CURLOPT_POSTFIELDS => [
'client_id' => 12345,
'api_key' => 'YOUR_API_KEY',
'media_file' => new CURLFile('/path/to/invoice-4821.pdf', 'application/pdf', 'invoice-4821.pdf'),
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 120,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($result['status'] ?? 0) === 1) {
echo 'Uploaded: ' . $result['data']['file_url'];
} else {
echo 'Failed: ' . ($result['message'] ?? 'no response');
}Sostituisci 12345 e YOUR_API_KEY con i tuoi valori. Consulta Autenticazione per sapere dove trovarli.
Parametri della richiesta#
Invia la richiesta come multipart/form-data. Questo endpoint non legge né i corpi JSON né i parametri nella query string.
client_idintegerobbligatorioIl tuo ID Client API, da Impostazioni → Chiavi API.
api_keystringobbligatorioLa tua chiave API, dalla stessa pagina.
media_filefileobbligatorioIl file da caricare, fino a 64 MB. Il tipo viene determinato dall'estensione del nome del file, quindi il nome deve terminare con una delle estensioni supportate.
Tipi di file supportati#
| Categoria | Estensioni |
|---|---|
| Immagini | .jpg, .jpeg, .png, .gif |
| Documenti | .pdf, .doc, .xls, .ppt, .txt, .csv |
| Audio | .mp3, .wav |
| Video | .mp4, .mov |
| Archivi | .zip |
Le immagini vengono salvate con file_type impostato su image; tutto il resto è file.
Risposta#
Una richiesta riuscita restituisce HTTP 200:
{
"status": 1,
"message": "File uploaded successfully",
"data": {
"id": 5122,
"file_name": "media_12345_17895804001234.pdf",
"original_file_name": "invoice-4821.pdf",
"file_url": "https://wbiztool-static.s3.ap-southeast-1.amazonaws.com/media/org_12345/media_12345_17895804001234.pdf",
"file_type": "file",
"file_size": 248312,
"file_size_display": "242.5 KB",
"mime_type": "application/pdf",
"is_image": false,
"file_extension": "pdf",
"created_at": "2026-09-16T10:20:31.512934+00:00"
}
}
| Campo | Tipo | Descrizione |
|---|---|---|
status | integer | 1 se il file è stato caricato, 0 se la richiesta non è riuscita. |
message | string | File uploaded successfully, altrimenti l'errore. |
data.id | integer | ID del file multimediale. Usalo con Ottieni file multimediale. |
data.file_name | string | Nome con cui viene salvato il file, generato da Wbiztool. |
data.original_file_name | string | Il nome del file che hai caricato. |
data.file_url | string | URL di download diretto. Usalo come img_url o file_url durante l'invio. |
data.file_type | string | image o file. |
data.file_size | integer | Dimensione in byte. |
data.file_size_display | string | Dimensione leggibile con un decimale, ad esempio 242.5 KB. |
data.mime_type | string | Tipo MIME ricavato dall'estensione, ad esempio application/pdf. |
data.is_image | boolean | true quando file_type è image. |
data.file_extension | string | Estensione in minuscolo di original_file_name, senza il punto. |
data.created_at | string | Orario del caricamento, in formato ISO 8601 in UTC con l'offset +00:00. |
Errori#
Anche gli errori restituiscono HTTP 200, con status impostato su 0:
{ "status": 0, "message": "File is too large. Maximum size is 64MB. Your file: 71.3MB" }
| Messaggio | Come risolvere |
|---|---|
Only POST method is supported | Invia una richiesta POST. |
client_id is required | Aggiungi client_id come campo del modulo. Verifica che il corpo sia multipart/form-data e non JSON. |
api_key is required | Aggiungi api_key come campo del modulo. |
media_file is required | Invia il file in un campo chiamato media_file. |
client_id must be a valid integer | Invia client_id come numero. |
Invalid API key | Verifica che la chiave esista e non sia stata eliminata o disattivata. |
Invalid client_id for this API key | La chiave appartiene a un altro client_id. |
File is too large. Maximum size is 64MB. Your file: …MB | Carica un file di 64 MB o meno. |
File type not supported. Type detected: … | Usa una delle estensioni supportate. |
Error uploading file: … | Non è stato possibile completare il caricamento. Riprova. Ricevi questo errore anche se la chiave API non è collegata a uno spazio di lavoro; crea una nuova chiave nello spazio di lavoro che vuoi usare. |
Carica e invia#
Carica il file, poi passa file_url a Invia messaggio: come img_url con msg_type 1 per le immagini, oppure come file_url con msg_type 2 per gli altri file.
import requests
BASE = "https://wbiztool.com/api/v1"
AUTH = {"client_id": 12345, "api_key": "YOUR_API_KEY"}
with open("invoice-4821.pdf", "rb") as f:
upload = requests.post(f"{BASE}/media/upload/", data=AUTH, files={"media_file": f}, timeout=120).json()
if upload["status"] != 1:
raise SystemExit("Upload failed: " + upload["message"])
media = upload["data"]
message = {
**AUTH,
"whatsapp_client": 678,
"country_code": "91",
"phone": "9876543210",
"msg": "Your invoice for order #4821 is attached.",
}
if media["is_image"]:
message.update(msg_type=1, img_url=media["file_url"])
else:
message.update(msg_type=2, file_url=media["file_url"], file_name=media["original_file_name"])
sent = requests.post(f"{BASE}/send_msg/", json=message, timeout=60).json()
print(sent)// Node.js 20+ (built-in fetch, FormData and fs.openAsBlob). Save as .mjs to use top-level await.
import { openAsBlob } from "node:fs";
const BASE = "https://wbiztool.com/api/v1";
const form = new FormData();
form.append("client_id", "12345");
form.append("api_key", "YOUR_API_KEY");
form.append("media_file", await openAsBlob("./invoice-4821.pdf"), "invoice-4821.pdf");
const upload = await (await fetch(`${BASE}/media/upload/`, { method: "POST", body: form })).json();
if (upload.status !== 1) throw new Error(`Upload failed: ${upload.message}`);
const media = upload.data;
const message = {
client_id: 12345,
api_key: "YOUR_API_KEY",
whatsapp_client: 678,
country_code: "91",
phone: "9876543210",
msg: "Your invoice for order #4821 is attached.",
...(media.is_image
? { msg_type: 1, img_url: media.file_url }
: { msg_type: 2, file_url: media.file_url, file_name: media.original_file_name }),
};
const sent = await fetch(`${BASE}/send_msg/`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(message),
});
console.log(await sent.json());Invia messaggio ha un proprio elenco di estensioni di file. Tra i tipi accettati da questa API, i file .doc, .ppt, .csv, .zip, .wav e .mov inviati con msg_type 2 vengono consegnati con .pdf aggiunto al nome (ad esempio brochure.doc.pdf). Converti i documenti in PDF prima di inviarli. Vedi Invio di immagini e file. Il nome viene inoltre inviato in minuscolo (Invoice-4821.PDF arriva come invoice-4821.pdf).
Le immagini inviate con msg_type 1 devono essere di 16 MB o meno. Le immagini più grandi si caricano senza problemi qui, ma l'invio non riesce con File exceeds WhatsApp size limit (16MB max). Comprimile prima, oppure inviale come file con msg_type 2.
Suggerimenti#
- Riutilizza i caricamenti. Salva l'
ido ilfile_urle invia lo stesso file più volte invece di caricarlo di nuovo. - Mantieni significativo il nome originale.
original_file_nameè ciò che vedi nella dashboard ed è un buon valore perfile_namedurante l'invio. - Trova i caricamenti precedenti con Elenca file multimediali.
