Documentation Index
Fetch the complete documentation index at: https://zapo.to/llms.txt
Use this file to discover all available pages before exploring further.
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 o 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. 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
})
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'
})
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
})
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.
WaIncomingMessageEvent quanto um Proto.IMessage bruto, mais WaDownloadMediaOptions opcional (por exemplo maxBytes para limitar downloadBytes).
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.
