Vai al contenuto
Wbiztool

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.

POSThttps://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.pdf

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_idintegerobbligatorio

Il tuo ID Client API, da Impostazioni → Chiavi API.

api_keystringobbligatorio

La tua chiave API, dalla stessa pagina.

media_filefileobbligatorio

Il 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#

CategoriaEstensioni
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"
  }
}
CampoTipoDescrizione
statusinteger1 se il file è stato caricato, 0 se la richiesta non è riuscita.
messagestringFile uploaded successfully, altrimenti l'errore.
data.idintegerID del file multimediale. Usalo con Ottieni file multimediale.
data.file_namestringNome con cui viene salvato il file, generato da Wbiztool.
data.original_file_namestringIl nome del file che hai caricato.
data.file_urlstringURL di download diretto. Usalo come img_url o file_url durante l'invio.
data.file_typestringimage o file.
data.file_sizeintegerDimensione in byte.
data.file_size_displaystringDimensione leggibile con un decimale, ad esempio 242.5 KB.
data.mime_typestringTipo MIME ricavato dall'estensione, ad esempio application/pdf.
data.is_imagebooleantrue quando file_type è image.
data.file_extensionstringEstensione in minuscolo di original_file_name, senza il punto.
data.created_atstringOrario 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" }
MessaggioCome risolvere
Only POST method is supportedInvia una richiesta POST.
client_id is requiredAggiungi client_id come campo del modulo. Verifica che il corpo sia multipart/form-data e non JSON.
api_key is requiredAggiungi api_key come campo del modulo.
media_file is requiredInvia il file in un campo chiamato media_file.
client_id must be a valid integerInvia client_id come numero.
Invalid API keyVerifica che la chiave esista e non sia stata eliminata o disattivata.
Invalid client_id for this API keyLa chiave appartiene a un altro client_id.
File is too large. Maximum size is 64MB. Your file: …MBCarica 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.

Carica un PDF e invialo
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)

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'id o il file_url e 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 per file_name durante l'invio.
  • Trova i caricamenti precedenti con Elenca file multimediali.