Pular para o conteúdo principal
Atualizado em Jul 26, 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" }

Para ler um objeto armazenado depois, chame GET /v1/storage/url?path=<fullPath> para obter uma URL de download de curta duração.

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}. Use para qualquer tamanho.
  • 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.
  • 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