integração · s3 e minio
Salvar mídia do WhatsApp no S3 ou MinIO, no bucket que é seu
Salve a mídia do WhatsApp no S3 ou no MinIO do seu SaaS: cada foto, áudio e documento que os clientes recebem vai para o seu bucket, com caminho por sessão, e o webhook chega com a media_url apontando para lá.
SaaS testa 14 dias com o time técnico ajudando na integração.
- conexões na D-API
- 1.875
- de uptime garantido em contrato
- 99,9%
- datacenters no Brasil
- 4
- por ligação de WhatsApp na API não-oficial
- R$ 0
Qualquer storage compatível com S3
AWS S3, MinIO e outros compatíveis. Endpoint, região, bucket, chaves, path style e SSL configuráveis.
Teste antes de salvar
A conexão com o bucket é testada antes de a integração ser criada. Configuração errada não entra em produção.
Caminho organizado por sessão
Os arquivos recebidos ficam em sessionId, tipo da mídia e ID da mensagem, o que facilita retenção por cliente.
Salvar a mídia do WhatsApp no S3 do seu próprio SaaS resolve uma pergunta que aparece cedo em vendas para clientes maiores: onde ficam os arquivos que os pacientes, compradores e alunos mandam pelo WhatsApp? Foto de exame, comprovante, contrato assinado, áudio com reclamação. Para clínicas, escritórios e qualquer cliente com área jurídica, a resposta certa é “num bucket que a gente controla, com a nossa política de retenção”. A integração S3 da D-API entrega isso sem que você escreva um pipeline de download e upload.
Esta página mostra como a integração funciona, como configurar e o que muda no seu webhook, com o exemplo de um software de prontuário que precisa guardar os anexos dos pacientes.
Como a mídia recebida chega ao seu bucket
Quando uma mensagem com mídia chega numa conexão da sua conta, a D-API baixa o arquivo do WhatsApp, descriptografa e grava no storage. A regra de destino é simples:
- Se a conta tem uma integração S3 ativa, o arquivo vai para esse bucket.
- Se não tem, o arquivo fica no storage da D-API.
Nos dois casos, o webhook messages.received chega com media_url apontando para o arquivo já gravado, e com media_data trazendo mimetype, file_length, legenda, duração e nome do arquivo quando existem. O seu handler não precisa saber de onde a URL veio.
Arquivos grandes não passam inteiros pelo evento interno em base64: acima de um limiar, o arquivo sobe por streaming direto para o mesmo bucket por URL pré-assinada, e o webhook sai igual ao de um arquivo pequeno.
Configurar o bucket no painel
No painel da D-API, a integração fica em Integrações, na categoria Armazenamento, com o nome Amazon S3 / MinIO. Os campos são os de qualquer cliente S3:
| Campo | O que informar |
|---|---|
| Nome da integração | Um rótulo seu, como prontuario-prod |
| Endpoint | https://s3.amazonaws.com na AWS, ou o endereço do seu MinIO |
| Região | A região do bucket |
| Bucket | O nome do bucket de destino |
| Access Key ID e Secret Access Key | Uma credencial com permissão de escrita no bucket |
| Force Path Style | Ligue para MinIO e storages compatíveis que usam path style |
| SSL/TLS | Usa HTTPS na conexão com o storage |
O botão Testar conexão valida endpoint, credencial e bucket. A criação da integração repete esse teste e recusa a configuração se ele falhar, então um bucket inacessível não chega a virar o destino da sua mídia.
Para automatizar o onboarding de ambientes, o SDK Node expõe a mesma operação:
import { DApi } from 'd-api-sdk';
const dapi = new DApi({ apiKey: process.env.DAPI_API_KEY! });
const config = {
endpoint: 'https://minio.seu-saas.com',
region: 'us-east-1',
bucket: 'whatsapp-anexos',
accessKeyId: process.env.MINIO_KEY!,
secretAccessKey: process.env.MINIO_SECRET!,
forcePathStyle: true,
sslEnabled: true,
};
await dapi.integrations.testS3Connection(config);
await dapi.integrations.create({ integrationName: 'prontuario-prod', integrationType: 'S3', config });
Dê à credencial só o que ela precisa: escrita no bucket de destino. Uma chave com acesso amplo à sua conta de cloud é risco que não traz benefício aqui.
Onde os arquivos ficam e como é a URL
A mídia recebida é gravada com uma chave no formato {sessionId}/{tipo}/{id-da-mensagem}.{extensão}, em que o tipo vem do mimetype, como image, audio ou application. Para o software de prontuário, isso significa que tudo que chegou pela sessão clinica-sorriso está sob o prefixo clinica-sorriso/, pronto para uma regra de lifecycle por cliente ou para uma exportação quando a clínica cancelar o contrato.
A media_url é o endereço do objeto no seu storage. Com Force Path Style ligado, o formato é endpoint/bucket/chave; desligado, https://bucket.endpoint/chave. Quem decide se essa URL abre no navegador é a política do bucket. Num bucket privado, o seu backend lê o objeto com as próprias credenciais e entrega ao usuário com a autorização do seu produto, que é o desenho recomendado para dado sensível.
Baixar mídia sob demanda
Há casos em que o arquivo precisa ser obtido depois, como uma mensagem antiga ou um reprocessamento. POST /api/v1/media/download recebe os metadados de mídia que vêm no payload da mensagem e devolve o arquivo de duas formas. Com base64: true, o conteúdo volta embutido na resposta. Sem ele, a D-API grava o arquivo no bucket da integração S3 da conta, ou no storage padrão se não houver, e devolve a media_url.
curl -X POST https://api.d-api.cloud/api/v1/media/download \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "clinica-sorriso",
"media_key": "VALOR_DO_WEBHOOK",
"direct_path": "VALOR_DO_WEBHOOK",
"mimetype": "application/pdf"
}'
Nas conexões da API Oficial, a mídia fica na Meta e é identificada pelo media_id que chega em media_data.media_id. Nesse caso, envie media_id e mimetype no lugar de media_key e direct_path; a resposta é sempre síncrona.
Quando o cliente não quer mídia guardada em lugar nenhum
Alguns contratos pedem o oposto: nenhum arquivo persistido fora do sistema do cliente. A opção Não armazenar mídias, em Minha Conta, Privacidade, faz a D-API não guardar mídia da conta em storage, cache, fila ou banco. Os webhooks chegam só com os metadados, sem media_url e sem base64, e o arquivo é obtido por POST /api/v1/media/download, que nessas contas responde sempre em base64 e só no modo síncrono. Envios de mídia em base64 com async também são recusados nessas contas; use envio síncrono ou URL.
Ativar ou desativar a opção reinicia as conexões não oficiais da conta, que ficam alguns segundos offline. Faça a troca fora do horário de pico dos seus clientes.
Do bucket para o produto
Com os arquivos no seu storage, o resto é produto. O prontuário anexa a foto do exame ao atendimento do paciente, o CRM guarda o comprovante no card do lead, a plataforma de cobrança arquiva o PDF junto do título. O catálogo de eventos de webhook mostra os campos de mídia de cada tipo de mensagem, e a página sobre enviar mídia pela API cobre o sentido oposto, do seu sistema para o cliente final.
O comportamento do download e da opção de não armazenar mídias está na documentação da D-API.
Time D-API. Atualizado em .
Perguntas frequentes
A integração S3 vale para todas as conexões da conta?
Vale. A integração é da conta: com ela ativa, a mídia recebida em todas as sessões da conta vai para o bucket configurado, separada por sessionId no caminho.
O que acontece se eu não configurar bucket nenhum?
A mídia recebida é armazenada pela D-API e o webhook traz a media_url do arquivo do mesmo jeito. A integração S3 serve para quem precisa dos arquivos sob o próprio controle.
A URL que chega no webhook é pública?
Ela aponta para o objeto no seu bucket, e quem decide o acesso é a política do bucket. Se ele for privado, o seu backend lê o arquivo com as próprias credenciais.
Dá para não guardar mídia em lugar nenhum?
Dá. Com a opção Não armazenar mídias, em Minha Conta, Privacidade, a D-API não guarda mídia. O webhook traz só os metadados, e o arquivo é obtido por POST /api/v1/media/download, sempre em base64.