Pular para o conteúdo principal
Atualizado em Oct 23, 2026

Enviando arquivos (API & MCP)

O que você vai aprender
  • Como enviar uma imagem ou arquivo de forma programática e obter uma referência reutilizável
  • O fluxo de upload REST em duas etapas (e a ferramenta MCP de uma etapa)
  • Onde usar a referência {bucket, fullPath} resultante

Muitos recursos do AutoTalk usam mídia — uma imagem de produto para um catálogo do WhatsApp, uma mensagem de mídia, uma foto de perfil. Em vez de hospedar esses arquivos por conta própria, envie-os ao AutoTalk uma vez e obtenha uma referência de armazenamento primária que pode reutilizar em qualquer lugar:

{ "bucket": "autotalk-prod", "fullPath": "companies/<id>/api/images/storage_manual_upload/<id>.png" }

Essa referência {bucket, fullPath} é aceita por send_message, campos de documentos Dynadata e funções como createWhatsappWebEvoProduct (no array images) — veja Onde usar a referência.

REST: o upload em duas etapas​

O upload pela API REST é um PUT assinado, para que os bytes vão direto ao armazenamento. Autentique cada chamada com sua x-api-key.

1. Reserve uma URL de upload assinada​

curl -X POST https://api.autotalk.io/v1/storage/upload-url \
  -H "x-api-key: sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mimeType": "image/png",
    "fileSize": 41161,
    "fileName": "product.png",
    "purpose": "whatsapp_catalog_product_image"
  }'

A resposta fornece uma uploadUrl de curta duração, os requiredHeaders exatos e um uploadIntentId:

{
  "success": true,
  "uploadIntentId": "...",
  "uploadUrl": "https://storage.autotalk.io/...&X-Amz-Signature=...",
  "uploadMode": "signed_put",
  "bucket": "autotalk-prod",
  "fullPath": "companies/<id>/api/images/whatsapp_catalog_product_image/<id>.png",
  "category": "images",
  "requiredHeaders": { "Content-Type": "image/png", "Content-Length": "41161", "x-amz-meta-...": "..." }
}

2. Faça o PUT dos bytes​

Envie o arquivo diretamente para a uploadUrl, enviando todas as entradas de requiredHeaders exatamente como fornecidas. O tamanho do corpo deve corresponder a fileSize.

curl -X PUT "<uploadUrl>" \
  -H "Content-Type: image/png" \
  -H "Content-Length: 41161" \
  --data-binary @product.png

3. Finalize​

curl -X POST https://api.autotalk.io/v1/storage/upload-complete \
  -H "x-api-key: sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "uploadIntentId": "<uploadIntentId>" }'

A resposta é sua referência reutilizável:

{ "success": true, "bucket": "autotalk-prod", "fullPath": "companies/<id>/api/images/whatsapp_catalog_product_image/<id>.png", "size": 41161, "contentType": "image/png", "category": "images", "fileName": "product.png" }

Arquivos grandes: upload em partes​

Um único PUT aceita no máximo 90 MB. Para um arquivo entre 90 MB e 1 GB, adicione "multipart": true à requisição da etapa 1. Sem isso, um arquivo acima de 90 MB é recusado com 400 e uma mensagem pedindo que você adicione a flag. A resposta então traz "uploadMode": "multipart_put", "uploadUrl": null e uma lista parts em vez de uma única URL:

{
  "success": true,
  "uploadIntentId": "...",
  "uploadMode": "multipart_put",
  "uploadUrl": null,
  "partSize": 67108864,
  "parts": [
    { "partNumber": 1, "offset": 0, "size": 67108864, "uploadUrl": "https://storage.autotalk.io/...&partNumber=1&...", "requiredHeaders": { "Content-Length": "67108864" } },
    { "partNumber": 2, "offset": 67108864, "size": 32891136, "uploadUrl": "https://storage.autotalk.io/...&partNumber=2&...", "requiredHeaders": { "Content-Length": "32891136" } }
  ],
  "expiresAtMs": 1760000000000,
  "bucket": "autotalk-prod",
  "fullPath": "companies/<id>/api/documents/storage_manual_upload/<id>.pdf",
  "category": "documents"
}

Para cada parte, faça o PUT dos bytes de offset até offset + size (sem incluir) para a uploadUrl dessa parte. Envie os requiredHeaders dela e nenhum Content-Type: o tipo já foi definido quando o upload foi reservado. As partes podem ir em qualquer ordem, e uma parte que falhou pode ser reenviada para a mesma URL. Todas as partes devem ser enviadas antes de expiresAtMs, 60 minutos após a reserva.

Depois chame upload-complete como na etapa 3. O AutoTalk verifica se cada parte chegou com o tamanho exato e as junta em um único arquivo.

  • Se ainda faltarem partes, upload-complete retorna 409 e o upload continua aberto. Envie as partes que faltam e chame de novo.
  • Se você abandonar o upload, ele expira após 60 minutos. As partes são descartadas e a reserva de cota é liberada.

Para ler um objeto armazenado depois, chame GET /v1/storage/url?path=<fullPath>. Ele devolve uma URL de download assinada válida por até 7 dias — a expiração é fixada no início do dia UTC, então o link dura pelo menos 6 dias a partir do momento em que você o gera — e servida com public, max-age=3600, o que a torna cacheável na borda de CDN. Trate a própria string da URL como uma credencial portadora durante toda essa janela: qualquer pessoa que a tenha consegue baixar o objeto sem se autenticar, então não registre a URL em logs, não a cole em chamados nem a encaminhe.

MCP: begin/complete ou inline em uma etapa​

Se você se conecta via servidor MCP, use as ferramentas de arquivo:

  • begin_file_upload({fileName, mimeType, fileSize}) → faça o PUT HTTP para a uploadUrl retornada → complete_file_upload({uploadIntentId}). Retorna {bucket, fullPath}. Aceita arquivos de até 1 GB. Acima de 90 MB a ferramenta responde com uploadMode: "multipart_put" e uma lista parts: faça o PUT de cada parte como descrito em Arquivos grandes: upload em partes e depois chame complete_file_upload. Nenhuma flag é necessária nesta ferramenta.
  • upload_file_inline({fileName, mimeType, data}) — passe os bytes codificados em base64 diretamente e obtenha {bucket, fullPath} em uma única chamada. Prático para arquivos pequenos (≤ ~1 MB); arquivos maiores devem usar o fluxo em duas etapas.

Onde usar a referência​

Passe {bucket, fullPath} (ou, para images, uma URL pública ou a referência) onde quer que mídia seja aceita:

  • Enviar uma mensagem de mídia — send_message body.file = {bucket, fullPath}.
  • Catálogo do WhatsApp — createWhatsappWebEvoProduct / updateWhatsappWebEvoProduct images: [{bucket, fullPath}, ...].
  • Foto de perfil / grupo — updateWhatsappWebEvoProfilePicture picture, updateWhatsappWebEvoGroupPicture image.
  • Campos de documento Dynadata — qualquer campo de objeto de armazenamento (por exemplo, a imagem de um documento).

Propósitos e limites​

  • purpose (opcional, padrão storage_manual_upload) indica para que serve o arquivo. Valores permitidos: storage_manual_upload, whatsapp_catalog_product_image, template_message_media, chat_media_upload, scheduled_message_media, contact_avatar, company_logo.
  • fileSize pode ir até 1 GB. Um PUT carrega no máximo 90 MB, porque cada requisição precisa passar inteira pela CDN na frente do armazenamento do AutoTalk. Por isso, arquivos acima de 90 MB são enviados em partes, cada uma abaixo desse limite. POST /v1/storage/upload-url precisa de "multipart": true para esses arquivos; begin_file_upload passa a usar partes sozinho. Uma requisição acima de 1 GB é recusada na hora, com um erro claro. Envie a contagem exata de bytes; o tamanho armazenado precisa corresponder a ela.
  • Os bytes enviados contam para a cota de armazenamento da sua empresa; um upload que a excederia retorna 409.
  • Os arquivos ficam sob o prefixo da sua empresa; você só pode referenciar objetos do seu próprio tenant.

Próximos passos​

Última atualização em
Nesta página