Empresa brasileira · Entrega automática · Suporte em português Seg a sex, 9h as 18h · PIX em reais
ProxyBox
API de WhatsApp · Integrações

Como guardar a mídia recebida do WhatsApp no seu S3?

A ProxyBox grava no seu bucket as imagens, áudios e documentos recebidos e põe o endereço no aviso. S3, R2, Backblaze e MinIO. Beta.

6 min de leitura Atualizado em 14 de novembro de 2026
Resposta curta
Grave a integração com PUT /integrations/s3 (endereço, bucket e chaves do seu armazenamento). Daí em diante, quando chega uma imagem, áudio, vídeo, documento ou figurinha, a ProxyBox baixa o arquivo, grava no seu bucket e o aviso message.received traz data.media.url e data.media.stored: true. Se algo falhar, o aviso vai sem URL e com stored: false: o aviso nunca se perde.

Recurso em beta: pode mudar. Versão beta, em fase de testes.

Para que serve?

O aviso do WhatsApp traz só o tipo, o nome e o tamanho da mídia; o arquivo precisa ser baixado depois, por uma rota. Se o seu sistema precisa guardar os comprovantes, as fotos de produto e os áudios que os clientes mandam, é mais simples e mais seguro que o arquivo já chegue ao seu armazenamento, com um endereço que você controla. Também serve de base para outros fluxos: um robô lendo comprovantes, um CRM mostrando a foto.

Quais armazenamentos funcionam?

Qualquer um com a API do S3: Amazon S3, Cloudflare R2, Backblaze B2, MinIO, Wasabi e similares. A ProxyBox assina os pedidos (assinatura v4 da AWS) com código próprio, sem instalar biblioteca da AWS.

Como configuro?

bash
curl -X PUT "https://proxybox.com.br/api/whatsapp/v1/integrations/s3" \
  -H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://s3.us-east-1.amazonaws.com",
    "region": "us-east-1",
    "bucket": "minha-loja-whatsapp",
    "access_key": "AKIA...",
    "secret_key": "SEGREDO",
    "path_style": false,
    "prefix": "whatsapp",
    "url_mode": "presigned",
    "expire_days": 30
  }'
Campo Para que serve
endpoint Endereço https público do armazenamento
region Região (padrão us-east-1; use auto no R2)
bucket Nome do bucket
access_key, secret_key Chaves do seu armazenamento, cifradas; depois só aparecem mascaradas
path_style Estilo endpoint/bucket/objeto; é ligado sozinho para endereço IP ou bucket com ponto no nome
prefix Pasta base (até 100 caracteres, sem ..)
url_mode presigned (link temporário de 24 horas) ou public
public_base_url Endereço público do bucket, quando url_mode é public
expire_days Só anotação (0 a 3650): veja a seção sobre retenção

Para gravar, a ProxyBox testa o bucket: grava e apaga um arquivo chamado _proxybox-teste-xxxx.txt. O bucket precisa permitir gravar e apagar objetos. Para testar sem gravar a configuração, use POST /integrations/s3/test com o mesmo corpo. O PUT é parcial: o que você omitir (inclusive os segredos) permanece.

O endereço passa pela guarda de rede: https, nome que resolve para IP público, portas 443 ou 8443, sem usuário e senha na URL, sem redirecionamento.

Quer rodar isto agora? O sandbox é grátis, não precisa de número e já vem com a chave da API.

Testar grátis

O que muda no aviso?

json
{
  "event": "message.received",
  "uid": "in_3EB0A1",
  "instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
  "sent_at": "2026-11-12T10:06:10-03:00",
  "occurred_at": "2026-11-12T13:06:09Z",
  "data": {
    "id": "3EB0A1",
    "from": "5547999999999",
    "type": "image",
    "text": "Segue o comprovante",
    "media": {
      "mime": "image/jpeg",
      "filename": null,
      "size": 183204,
      "url": "https://minha-loja-whatsapp.s3.us-east-1.amazonaws.com/whatsapp/atendimento-da-loja/2026/11/3EB0A1.jpg?X-Amz-...",
      "stored": true
    }
  }
}

Em caso de falha (bucket recusou, arquivo grande demais, rede), o campo url não vem e stored é false. O mesmo vale no formato Z-API do aviso, em que imageUrl, audioUrl e similares vêm preenchidos quando há URL.

Como é o caminho do arquivo?

<prefixo>/<slug da instância>/<aaaa>/<mm>/<id da mensagem>.<extensão>. A extensão vem do tipo ou do nome do arquivo. Extensões perigosas (html, svg, js, exe e semelhantes) viram .bin e o tipo gravado é application/octet-stream: um cliente mal-intencionado não consegue plantar uma página no seu bucket pelo WhatsApp.

  • presigned: o link vale por 24 horas. É o mais seguro: ninguém acessa o arquivo sem o link. Se você precisa do arquivo depois, copie-o para outro lugar ou gere um novo link com as chaves do bucket, do seu lado.
  • public: o link é o public_base_url mais o caminho do objeto. Serve se o bucket é público ou está atrás de uma CDN. O bucket é seu e a exposição também: comprovantes de clientes são dados pessoais.

E a retenção?

A ProxyBox não apaga o que grava no seu bucket. O campo expire_days é só uma anotação mostrada no painel. Para apagar com o tempo, configure uma regra de ciclo de vida (lifecycle) no próprio bucket, no painel do seu provedor: por exemplo, apagar objetos do prefixo whatsapp/ depois de 90 dias. Sem isso, os arquivos ficam e o custo cresce.

Quais são os limites?

  • 25 MB por arquivo. Acima disso, o arquivo não é baixado e o aviso vai com stored: false.
  • Tempo de envio ao bucket: 8 segundos. O download do arquivo, do lado da ProxyBox, pode levar mais (até 90 segundos em casos de mídia pesada), e como a gravação acontece antes do aviso, o aviso pode atrasar. Esse efeito ainda não foi medido.
  • Só mídia recebida (message.received). Mídia que você envia não é copiada.
  • Teste de conexão: pausa de 3 segundos entre testes.

Em Python, como leio o aviso?

python
def tratar(ev):
    if ev["event"] != "message.received":
        return
    m = ev["data"].get("media") or {}
    if m.get("stored") and m.get("url"):
        print("Arquivo guardado:", m["url"])
    elif m:
        print("Sem URL; baixe pela rota de mídia recebida, id", ev["data"]["id"])

Se stored for falso, o caminho de segurança é a rota de mídia recebida (GET /messages/{id}/media), de preferência logo que o aviso chega.

Cuidados

  • Use chaves de acesso exclusivas para a ProxyBox, com permissão só no bucket e no prefixo necessários.
  • Não coloque o bucket em modo público só para facilitar. Prefira o link temporário.
  • Reveja a segurança: as chaves ficam cifradas e nunca em log, mas quem tem a chave da instância pode ler a configuração mascarada.

Veja também

Índice completo: documentação. Sobre o produto: uma instância de WhatsApp por número.

Autoria: equipe técnica da ProxyBox. Atualizado em 11/11/2026, contra as notas técnicas da integração S3 da versão 1.2. Recurso em beta.

Perguntas frequentes

A ProxyBox guarda a minha mídia?
Não além do necessário. O arquivo é baixado, enviado ao seu bucket e descartado. O bucket é seu, e a ProxyBox não limpa o que você guardou lá.
Que tamanho de arquivo vale?
Até 25 MB. Acima disso o arquivo não é baixado e o aviso segue com stored falso.
Se o envio ao bucket falhar, perco o aviso?
Não. O aviso message.received chega do mesmo jeito, só que sem a URL e com stored igual a false.

Guias relacionados

Pronto para colocar no ar?

Comece no sandbox, grátis. Quando funcionar, contrate a instância do seu número e pague com PIX ou saldo.

Com IP brasileiro dedicado R$ 89,90/mês
Só a instância (traga o seu IP) R$ 39,90/mês
Travou em alguma etapa?Manda o print do erro no WhatsApp. Respondemos em português.
Suporte em português Fale no WhatsApp