Pular para o conteúdo
D-APITestar grátis

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:

  1. Se a conta tem uma integração S3 ativa, o arquivo vai para esse bucket.
  2. 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.

A gente também é SaaS

SaaS liberado pelo time testa 14 dias grátis, com um grupo de onboarding em que o time técnico da D-API acompanha a integração no seu produto.

Continue por aqui

Liberar seu teste grátis

Responda rapidinho e o time libera seu teste pelo WhatsApp, com o time técnico ajudando na integração.

Seus dados são usados só pra liberar o teste. Sem spam.