Upload asset

Upload asset

curl --request POST \
  --url https://macaly.com/api/client-app/assets/upload \
  --header 'Authorization: Bearer <token>'

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://macaly.com/api/client-app/assets/upload', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://macaly.com/api/client-app/assets/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://macaly.com/api/client-app/assets/upload"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://macaly.com/api/client-app/assets/upload")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

POST

api

client-app

assets

upload

Upload asset

curl --request POST \
  --url https://macaly.com/api/client-app/assets/upload \
  --header 'Authorization: Bearer <token>'

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://macaly.com/api/client-app/assets/upload', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://macaly.com/api/client-app/assets/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://macaly.com/api/client-app/assets/upload"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://macaly.com/api/client-app/assets/upload")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

Carica un file nelle Risorse di una chat e restituisce una URL CDN permanente. Usalo per immagini, documenti, audio, video o qualsiasi altro file che la tua app o la tua elaborazione deve richiamare tramite URL.

Richiesta

POST /api/client-app/assets/upload

Header	Obbligatorio	Descrizione
`Authorization`	Sì	`Bearer macaly_...`
`Content-Type`	Sì	`multipart/form-data`

Parametri del form data

Campo	Tipo	Obbligatorio	Predefinito	Descrizione
`chatId`	string	Sì	-	La chat in cui caricare la risorsa
`file`	file	Sì	-	Il file da caricare. Dimensione massima 20 MB
`folderPath`	string	No	-	Percorso della cartella separato da barre, ad esempio `images/products`
`createFolders`	string	No	`false`	Con `"true"`, `"1"` o `"yes"` crea le cartelle mancanti in `folderPath`
`folderId`	string	No	-	ID di una cartella esistente. Non inviare insieme `folderId` e `folderPath`
`title`	string	No	Nome del file originale	Titolo visualizzato della risorsa
`metadata`	string (JSON)	No	-	Oggetto JSON memorizzato insieme alla risorsa

Indica folderId oppure folderPath, non entrambi. Inviarli insieme restituisce un errore 400.

Esempio di richiesta

curl -X POST https://www.macaly.com/api/client-app/assets/upload \
  -H "Authorization: Bearer macaly_abc123..." \
  -F "chatId=abc123def456" \
  -F "file=@./logo.png;type=image/png"

const form = new FormData();
form.append('chatId', 'abc123def456');
form.append('file', fileBlob, 'logo.png');

const response = await fetch('https://www.macaly.com/api/client-app/assets/upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer macaly_abc123...',
  },
  body: form,
});

const data = await response.json();
console.log(data.asset.url);

import requests

response = requests.post(
    'https://www.macaly.com/api/client-app/assets/upload',
    headers={'Authorization': 'Bearer macaly_abc123...'},
    data={'chatId': 'abc123def456'},
    files={'file': ('logo.png', open('logo.png', 'rb'), 'image/png')},
)

data = response.json()
print(data['asset']['url'])

Caricamento in una cartella

Usa folderPath per una struttura di cartelle leggibile e imposta createFolders=true per creare le cartelle mancanti lungo il percorso:

cURL

curl -X POST https://www.macaly.com/api/client-app/assets/upload \
  -H "Authorization: Bearer macaly_abc123..." \
  -F "chatId=abc123def456" \
  -F "folderPath=images/products" \
  -F "createFolders=true" \
  -F "title=Product hero image" \
  -F "file=@./hero.png;type=image/png"

Risposta

{
  "success": true,
  "asset": {
    "assetId": "asset_123",
    "url": "https://cdn.macaly.app/user/chat/key/logo.png",
    "storageKey": "user/chat/key/logo.png",
    "contentType": "image/png",
    "fileSize": 12345,
    "type": "image",
    "folderId": "folder_123"
  }
}

Campo	Tipo	Descrizione
`asset.assetId`	string	Identificatore univoco della risorsa
`asset.url`	string	URL CDN permanente del file caricato
`asset.storageKey`	string	Percorso di archiviazione interno
`asset.contentType`	string	Tipo MIME del file caricato
`asset.fileSize`	number	Dimensione del file in byte
`asset.type`	string	Tipo di risorsa dedotto, ad esempio `image`, `document`
`asset.folderId`	string \| null	Cartella in cui è stata inserita la risorsa, se presente

Codici di stato

Codice	Descrizione
200	Operazione riuscita: risorsa caricata
400	`chatId` o `file` mancante, JSON di `metadata` non valido oppure `folderId` e `folderPath` inviati insieme
401	Chiave API non valida o mancante
403	La chiave API non ha accesso a questa chat
404	Cartella non trovata
413	Il file supera il limite di caricamento di 20 MB
500	Errore del server

Regole per le cartelle

I percorsi delle cartelle vengono divisi in corrispondenza di /, ripuliti dagli spazi superflui e i segmenti vuoti vengono ignorati.
La profondità massima è di 8 cartelle.
Ogni nome di cartella può contenere fino a 255 caratteri.
All’interno della stessa cartella superiore la corrispondenza dei nomi non distingue tra maiuscole e minuscole.
Se folderPath non esiste e createFolders non è true, il caricamento fallisce con un errore 404.

Informazioni utili

Questo endpoint usa la stessa chiave API macaly_... del resto dell’API, anche se la URL inizia con /api/client-app/. Non serve un token separato.
La chat indicata da chatId deve appartenere allo stesso team della tua chiave API.
Le risorse caricate ottengono una URL CDN permanente che puoi indicare come allegato in Create chat o Publish message, oppure usare ovunque al di fuori di Macaly.

Per iniziare

Endpoint

Richiesta

Header

Parametri del form data

Esempio di richiesta

Caricamento in una cartella

Risposta

Codici di stato

Regole per le cartelle

Informazioni utili

​Richiesta

​Header

​Parametri del form data

​Esempio di richiesta

​Caricamento in una cartella

​Risposta

​Codici di stato

​Regole per le cartelle

​Informazioni utili

Richiesta

Header

Parametri del form data

Esempio di richiesta

Caricamento in una cartella

Risposta

Codici di stato

Regole per le cartelle

Informazioni utili