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?
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átisO que muda no aviso?
{
"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.
Link temporário ou público?
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 é opublic_base_urlmais 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?
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
- Ler conversas e baixar mídia no WhatsApp via API
- Webhook da API de WhatsApp: eventos e assinatura
- Segurança da API de WhatsApp: chave e IPs
Í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.