Mídia

A mídia é enviada pelo mesmo método client.message.send, usando um objeto de conteúdo de mídia tipado. O builder preenche para você os campos gerenciados pelo protocolo (chaves de criptografia, digests SHA-256, direct path, upload) — você fornece a fonte e, opcionalmente, um mimetype.

Para mídia utilizável, instale @zapo-js/media-utils e conecte um processor via opção de client media. A mídia ainda faz upload sem ele, mas sem um processor ela fica sem thumbnail/preview, dimensões ou waveform — então pode chegar como anexo simples.

Resolução de mimetype

mimetype é opcional. O builder resolve nesta ordem:

O mimetype que você passa no objeto de conteúdo vence.
Se um WaMediaProcessor com detectMimetype está configurado, o builder o chama (sniffing de magic bytes). @zapo-js/media-utils implementa isso em cima de file-type ^19 — instale file-type para habilitar a detecção.
Caso contrário, o builder lança erro para mensagens image/video/audio/document/ptv.

Stickers usam image/webp por padrão quando nenhum mimetype é definido. Entradas de stream Readable sem mimetype são staged para um arquivo temporário antes da detecção rodar.

Entrada de mídia

O campo media aceita vários tipos de entrada:

type MediaInput = Uint8Array | ArrayBuffer | Readable | string

Prefira um caminho de arquivo (string) ou um stream Readable em vez de um Buffer/Uint8Array. O zapo faz o streaming da mídia pelo pipeline sem bufferizar o arquivo inteiro em memória — passar um caminho ou stream mantém a memória plana independentemente do tamanho do arquivo. Ler um arquivo grande inteiro para um Buffer primeiro anula isso e é desencorajado. (Buffer também é evitado internamente em favor de Uint8Array.)

Imagens

// Preferido — passe um caminho de arquivo; o zapo faz o streaming
await client.message.send(jid, {
  type: 'image',
  media: './photo.jpg',
  mimetype: 'image/jpeg',
  caption: 'A photo'
})

// Ou um stream Readable (ex.: a partir de uma resposta HTTP)
import { createReadStream } from 'node:fs'

await client.message.send(jid, {
  type: 'image',
  media: createReadStream('./photo.jpg'),
  mimetype: 'image/jpeg'
})

Vídeo

await client.message.send(jid, {
  type: 'video',
  media: './clip.mp4',
  mimetype: 'video/mp4',
  caption: 'A clip',
  gifPlayback: false
})

Para uma mensagem redonda de push-to-video (PTV), use type: 'ptv' com o mesmo formato.

Áudio e notas de voz

// Áudio comum
await client.message.send(jid, {
  type: 'audio',
  media: './song.mp3',
  mimetype: 'audio/mpeg'
})

// Nota de voz (push-to-talk)
await client.message.send(jid, {
  type: 'audio',
  media: './voice.ogg',
  mimetype: 'audio/ogg; codecs=opus',
  ptt: true
})

Notas de voz são melhor renderizadas como Opus em um container OGG. Habilite o processamento de mídia para gerar waveforms automaticamente e normalizar notas de voz.

Documentos

await client.message.send(jid, {
  type: 'document',
  media: './report.pdf',
  mimetype: 'application/pdf',
  fileName: 'Q3 Report.pdf',
  caption: 'The quarterly report'
})

Figurinhas

await client.message.send(jid, {
  type: 'sticker',
  media: await readFile('./sticker.webp'),
  mimetype: 'image/webp'
})

Para um pacote de figurinhas completo, use type: 'sticker-pack' com stickers, um trayIcon e os metadados do pacote (stickerPackId, name, publisher).

Visualização única

Envolva imagem/vídeo/áudio como visualização única com a opção de envio:

await client.message.send(jid, {
  type: 'image',
  media: './secret.jpg',
  mimetype: 'image/jpeg'
}, {
  viewOnce: true
})

Baixando mídia recebida

O coordinator de mensagens descriptografa e baixa a mídia de um evento recebido. Três variantes estão disponíveis — prefira as de streaming:

client.on('message', async (event) => {
  if (!event.message?.imageMessage) return

  // Preferido — faz streaming para um arquivo (memória constante)
  await client.message.downloadToFile(event, './incoming.jpg')

  // Ou consuma o stream Readable você mesmo
  const stream = await client.message.download(event)

  // Evite para mídia grande — bufferiza o arquivo inteiro em memória
  const bytes = await client.message.downloadBytes(event)
})

download() / downloadToFile() fazem o streaming da mídia e mantêm a memória plana independentemente do tamanho. downloadBytes() materializa o arquivo inteiro em memória — recorra a ele apenas para mídias pequenas e limite-o com maxBytes.

As três aceitam tanto um WaIncomingMessageEvent quanto um Proto.IMessage bruto, mais WaDownloadMediaOptions opcional (por exemplo maxBytes para limitar downloadBytes).

Sem um client conectado

downloadMediaMessage é uma função livre que espelha o client.message.download mas não precisa de uma sessão pareada. O metadata de mídia encriptada viaja dentro da própria mensagem (já decifrada), então você consegue re-baixar mídia de um evento persistido muito tempo depois do socket original ter ido embora — útil para workers offline, replay de arquivo, ou qualquer coisa que processe mensagens armazenadas sem subir um WaClient.

import { downloadMediaMessage } from 'zapo-js'
import { createWriteStream } from 'node:fs'

const stream = await downloadMediaMessage(event)
stream.pipe(createWriteStream('photo.jpg'))

Aceita um WaIncomingMessageEvent ou um Proto.IMessage bruto, retorna um Readable cujo dono é você (pipe ou .destroy() — um stream não consumido vaza o socket). Verificação MAC + SHA-256 roda conforme os bytes são consumidos, mesma semântica do método do coordinator. Lança quando a mensagem não tem mídia para download.

Opção	Tipo	Notas
`transfer`	`WaMediaTransferClient`	Reutilize um transfer client existente — herda os proxy agents, timeouts e toggle de verificação MAC dele, e evita subir um novo HTTP client por chamada num loop. Um stateless é criado quando omitido (bom para chamadas pontuais).
`proxy`	`WaProxyTransport`	Proxy por chamada para a perna de download do CDN, espelhando o `proxy.mediaDownload` do client. O fetch roda em `node:http`/`node:https`, então só a forma `http.Agent` é honrada — um dispatcher undici é ignorado. Tem precedência sobre o agent default de um `transfer` que você passar.
`signal` / `timeoutMs` / `maxBytes`	(de `WaDownloadMediaOptions`)	Mesma semântica dos métodos do coordinator.

Para acesso de mais baixo nível — quando você quer fazer o fetch ao CDN você mesmo, passar as chaves para outro processo, ou só inspecionar o que é baixável — o resolveMediaPayload retorna as keys + hashes sem fazer I/O:

import { resolveMediaPayload } from 'zapo-js'

const payload = resolveMediaPayload(event.message)
// → WaResolvedMediaPayload | null
// { mediaType, directPath, mediaKey, fileSha256?, fileEncSha256?, mimetype?, fileLength? }

Retorna null quando a mensagem não tem mídia para download, ou quando o proto não carrega directPath / mediaKey. Desencapsula ephemeralMessage, viewOnceMessage / viewOnceMessageV2 e documentWithCaptionMessage antes de resolver. Tipos suportados: image, video (gif quando gifPlayback), audio (ptt quando ptt), document, sticker, ptv.

payload.mediaKey é a seed AES/MAC do blob encriptado — trate como segredo. Não logue, não inclua em mensagens de erro, e não envie para serviço de terceiros a menos que esse seja o ponto inteiro do seu pipeline.

Processamento de mídia

Para mídia adequada, use um processador de mídia. Instale @zapo-js/media-utils e passe um através da opção de client media — ele sonda e processa a mídia (dimensões, duração, miniaturas, waveforms, normalização de notas de voz) antes do upload. Sem ele, a mídia ainda faz upload mas sem esse processamento:

import { createMediaProcessor } from '@zapo-js/media-utils'

const client = new WaClient({
  store,
  sessionId: 'default',
  media: {
    processor: createMediaProcessor(),
    generateThumbnail: true,
    generateWaveform: true,
    normalizeVoiceNote: true
  }
}, logger)

@zapo-js/media-utils invoca ffmpeg/ffprobe e usa sharp. Garanta que esses binários estejam disponíveis no seu ambiente.

Primeiros passos

Conceitos

Guias

Plugins

Referência

Avançado

Engenharia reversa

Resolução de mimetype

Entrada de mídia

Imagens

Vídeo

Áudio e notas de voz

Documentos

Figurinhas

Visualização única

Baixando mídia recebida

Sem um client conectado

Processamento de mídia

​Resolução de mimetype

​Entrada de mídia

​Imagens

​Vídeo

​Áudio e notas de voz

​Documentos

​Figurinhas

​Visualização única

​Baixando mídia recebida

​Sem um client conectado

​Processamento de mídia

Resolução de mimetype

Entrada de mídia

Imagens

Vídeo

Áudio e notas de voz

Documentos

Figurinhas

Visualização única

Baixando mídia recebida

Sem um client conectado

Processamento de mídia