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
})

Pré-upload e reuso

Às vezes você quer encriptar e uploadar mídia uma vez e depois referenciar o mesmo descriptor em múltiplos envios — um asset de broadcast, uma resposta pronta, ou pra construir um payload proto bruto na mão. client.message.upload(source, options) roda o fluxo de encrypt / media_conn / upload CDN / parse que o send usa, mas retorna o descriptor sem enviar nada.

import { readFile } from 'node:fs/promises'

const media = await client.message.upload(await readFile('./photo.jpg'), {
  type: 'image',
  mimetype: 'image/jpeg'
})

// Envia como uma mensagem de imagem espalhando o descriptor no proto:
await client.message.send(jid, {
  imageMessage: {
    url: media.url,
    directPath: media.directPath,
    mediaKey: media.mediaKey,
    fileSha256: media.fileSha256,
    fileEncSha256: media.fileEncSha256,
    fileLength: media.fileLength,
    mediaKeyTimestamp: media.mediaKeyTimestamp,
    mimetype: media.mimetype
  }
})

O upload roda contra sua sessão conectada (o host token vem de um IQ media_conn). Sources Uint8Array pegam o fast path de zero-temp-file; um path de arquivo ou stream Readable é encaminhado por temp file pra que o pass de encrypt consiga hashear deterministicamente.

`WaUploadMediaOptions`

Campo	Tipo	Notas
`type`	`'image' \| 'video' \| 'audio' \| 'document' \| 'sticker' \| 'ptv' \| 'gif' \| 'ptt'`	Obrigatório. Define o contexto de criptografia e o path de upload no CDN. Tipos desconhecidos lançam erro antes de a encryption rodar.
`mimetype`	`string`	`Content-Type` para o upload, ecoado no resultado pro proto da mensagem.
`mediaKey`	`Uint8Array`	Reutiliza uma media key de 32 bytes existente em vez de gerar uma nova.
`sidecar`	`boolean`	Sobrescreve o streaming sidecar. Default `true` pra `video` / `ptv` / `audio` / `gif` / `ptt`, off pro resto.
`firstFrameLength`	`number`	Tamanho do primeiro frame de sticker animado; necessário pra computar o sidecar do primeiro frame.
`timeoutMs`	`number`	Sobrescrita de timeout de transfer por upload.
`signal`	`AbortSignal`	Signal de cancelamento encaminhado pra request do CDN.

`WaMediaUploadResult`

Campo	Tipo	Notas
`url`	`string`	URL absoluta do ciphertext no CDN.
`directPath`	`string`	Path host-relativo — casa com um media host ou alimenta `downloadMediaMessage`.
`mediaKey`	`Uint8Array`	A media key de 32 bytes usada pra encriptar. Reutilize num call subsequente ao `upload` se quer um descriptor estável.
`fileSha256`	`Uint8Array`	SHA-256 do plaintext.
`fileEncSha256`	`Uint8Array`	SHA-256 do `ciphertext‖mac` encriptado.
`fileLength`	`number`	Tamanho em bytes do plaintext.
`mediaKeyTimestamp`	`number`	Segundos Unix quando a media key foi cunhada; pertence ao proto da mensagem.
`mimetype`	`string?`	Echo da opção quando informada.
`metadataUrl`	`string?`	URL de metadata do server (video).
`streamingSidecar`	`Uint8Array?`	Streaming sidecar pra playback com seek, quando computado.
`firstFrameSidecar` / `firstFrameLength`	`Uint8Array?` / `number?`	Echoes de sidecar do primeiro frame de sticker animado.

mediaKey é material sensível — trate como senha. Não logue, não envie pra terceiros, e não persista em store sem criptografia. Qualquer um com a key consegue decifrar o blob no CDN.

Crypto & transfer standalone

Pra fluxos que precisam rodar encrypt/decrypt fora de uma sessão — um worker em background processando ciphertext armazenado, um relay custom — WaMediaCrypto e WaMediaTransferClient (mais seus tipos de result e options) são re-exportados da raiz do package:

import { WaMediaCrypto, WaMediaTransferClient } from 'zapo-js'

Mesmas primitivas que os fluxos de upload / download usam; o método do coordinator só as encapsula com o handshake media_conn amarrado à sessão.

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.

Pedindo um reupload

O CDN dropa blobs antigos de mídia — um download* numa mensagem que veio de history sync pode responder 404/410 bem depois do envio original. client.message.requestMediaReupload() roda o round-trip que o WhatsApp Web usa pra recuperar: encripta um recibo server-error com a media key da mensagem, envia como ack e espera a notificação mediaretry que o device primário do remetente responde. No success só o directPath muda — media key, hashes e length da mensagem original continuam válidos, então baixar com o novo path espalhado funciona.

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

  try {
    await client.message.downloadToFile(event, './incoming.jpg')
  } catch {
    // Blob antigo expirou — pede pro remetente re-servir
    const retry = await client.message.requestMediaReupload(event)
    if (retry.result !== 'success') {
      console.warn('reupload', retry.result) // 'not_found' | 'decryption_error' | 'general_error'
      return
    }
    await client.message.downloadToFile(
      { imageMessage: { ...image, directPath: retry.directPath } },
      './incoming.jpg'
    )
  }
})

Passe uma WaMediaRetryRequest explícita ({ messageId, chatJid, mediaKey, fromMe, participant? }) quando você tem os ids e a media key mas não a mensagem decodada — a forma com evento extrai isso pra você e rejeita mensagens de newsletter mais mensagens sem mídia baixável. options.timeoutMs limita a espera pela notificação; o coordinator não lança em not_found / general_error (o remetente não tem mais o arquivo, ou o primário não conseguiu re-selar) — cheque result.result em 'success' | 'not_found' | 'decryption_error' | 'general_error'.

Requests são deduplicados por messageId: chamadas concorrentes pra mesma mensagem compartilham um único round-trip e um único recibo server-error.

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

Pré-upload e reuso

`WaUploadMediaOptions`

`WaMediaUploadResult`

Crypto & transfer standalone

Baixando mídia recebida

Sem um client conectado

Pedindo um reupload

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

​Pré-upload e reuso

​WaUploadMediaOptions

​WaMediaUploadResult

​Crypto & transfer standalone

​Baixando mídia recebida

​Sem um client conectado

​Pedindo um reupload

​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

Pré-upload e reuso

`WaUploadMediaOptions`

`WaMediaUploadResult`

Crypto & transfer standalone

Baixando mídia recebida

Sem um client conectado

Pedindo um reupload

Processamento de mídia