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

Envia um ficheiro para os Recursos de um chat e devolve uma URL CDN permanente. Usa este endpoint para imagens, documentos, áudio, vídeo ou qualquer outro ficheiro que queiras que a tua app ou processamento referencie por URL.

Pedido

POST /api/client-app/assets/upload

Cabeçalhos

Cabeçalho	Obrigatório	Descrição
`Authorization`	Sim	`Bearer macaly_...`
`Content-Type`	Sim	`multipart/form-data`

Parâmetros do formulário

Campo	Tipo	Obrigatório	Predefinição	Descrição
`chatId`	string	Sim	-	O chat para o qual enviar o recurso
`file`	file	Sim	-	O ficheiro a enviar. Tamanho máximo 20 MB
`folderPath`	string	Não	-	Caminho de pasta separado por barras, por exemplo `images/products`
`createFolders`	string	Não	`false`	`"true"`, `"1"` ou `"yes"` cria as pastas em falta em `folderPath`
`folderId`	string	Não	-	ID de uma pasta existente. Não envies `folderId` e `folderPath` em simultâneo
`title`	string	Não	Nome original do ficheiro	Título de apresentação do recurso
`metadata`	string (JSON)	Não	-	Objeto JSON guardado junto do recurso

Fornece folderId ou folderPath, não ambos. Enviar os dois devolve um erro 400.

Exemplo de pedido

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'])

Enviar para uma pasta

Usa folderPath para uma estrutura de pastas legível e define createFolders=true para criar as pastas em falta ao longo do caminho:

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"

Resposta

{
  "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	Descrição
`asset.assetId`	string	Identificador único do recurso
`asset.url`	string	URL CDN permanente do ficheiro enviado
`asset.storageKey`	string	Caminho de armazenamento interno
`asset.contentType`	string	Tipo MIME do ficheiro enviado
`asset.fileSize`	number	Tamanho do ficheiro em bytes
`asset.type`	string	Tipo de recurso inferido, por exemplo `image`, `document`
`asset.folderId`	string \| null	Pasta onde o recurso foi colocado, se aplicável

Códigos de estado

Estado	Descrição
200	Sucesso: recurso enviado
400	`chatId` ou `file` em falta, JSON de `metadata` inválido, ou `folderId` e `folderPath` fornecidos em simultâneo
401	Chave API inválida ou em falta
403	A chave API não tem acesso a este chat
404	Pasta não encontrada
413	O ficheiro excede o limite de envio de 20 MB
500	Erro do servidor

Regras das pastas

Os caminhos de pasta são divididos por /, com espaços removidos, e os segmentos vazios são ignorados.
A profundidade máxima é de 8 pastas.
Cada nome de pasta pode ter até 255 caracteres.
A correspondência de pastas não distingue maiúsculas de minúsculas dentro do mesmo diretório principal.
Se folderPath não existir e createFolders não for true, o envio falha com um erro 404.

É bom saber

Este endpoint usa a mesma chave API macaly_... que o resto da API, apesar de a URL começar com /api/client-app/. Não é necessário um token separado.
O chat referenciado por chatId tem de pertencer à mesma equipa que a tua chave API.
Os recursos enviados obtêm uma URL CDN permanente que podes referenciar em Create chat ou Publish message como anexo, ou usar em qualquer lugar fora da Macaly.

Primeiros passos

Endpoints

Pedido

Cabeçalhos

Parâmetros do formulário

Exemplo de pedido

Enviar para uma pasta

Resposta

Códigos de estado

Regras das pastas

É bom saber

​Pedido

​Cabeçalhos

​Parâmetros do formulário

​Exemplo de pedido

​Enviar para uma pasta

​Resposta

​Códigos de estado

​Regras das pastas

​É bom saber

Pedido

Cabeçalhos

Parâmetros do formulário

Exemplo de pedido

Enviar para uma pasta

Resposta

Códigos de estado

Regras das pastas

É bom saber