@systemzero/baileys 1.0.5 → 1.0.6

package/README.md

@@ -4,11 +4,12 @@
 
 # @systemzero/baileys
 
-**v1.0.5** · Fork avançado do Baileys com suporte nativo a todos os tipos de mensagens do WhatsApp
+**v1.0.6** · Fork avançado do Baileys com suporte nativo a todos os tipos de mensagens do WhatsApp
 
 [![NPM](https://img.shields.io/npm/v/@systemzero/baileys?color=7c3aed&style=flat-square&label=npm)](https://www.npmjs.com/package/@systemzero/baileys)
 [![License](https://img.shields.io/badge/license-MIT-6366f1?style=flat-square)](LICENSE)
 [![Author](https://img.shields.io/badge/by-Josué%20%3C%2F%3E-ec4899?style=flat-square)](https://t.me/blackhzx)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-7c3aed?style=flat-square)](https://nodejs.org)
 
 </div>
 
@@ -20,13 +21,14 @@
 npm i @systemzero/baileys
 ```
 
-Dependências opcionais para sticker pack e thumbnail:
+Dependências opcionais:
 ```bash
-npm i sharp
-# ou
-npm i @napi-rs/image
+npm i sharp          # conversão de imagem para sticker pack
+npm i @napi-rs/image # alternativa ao sharp
 ```
 
+Requer `ffmpeg` instalado no sistema (com suporte a `libopus`) para conversão automática de áudio PTT e para o sistema anti-fraude de pagamento processar mídia. Confirme com `ffmpeg -encoders | grep opus`.
+
 ---
 
 ## Índice
@@ -39,17 +41,27 @@ npm i @napi-rs/image
 6. [Canais Newsletter](#6-canais-newsletter)
 7. [Enquetes com decrypt](#7-enquetes-com-decrypt)
 8. [AI Rich](#8-ai-rich)
-9. [Grupos](#9-grupos)
-10. [Perfil e privacidade](#10-perfil-e-privacidade)
-11. [Eventos do socket](#11-eventos-do-socket)
-12. [Utilitários](#12-utilitários)
+9. [LID / JID — Sistema avançado](#9-lid--jid--sistema-avançado)
+10. [Username (@usuario)](#10-username-usuario)
+11. [MessageBuilder — Button, ButtonV2, Carousel, AIRich](#11-messagebuilder--button-buttonv2-carousel-airich)
+12. [Botões estendidos (v1.0.6)](#12-botões-estendidos-v106)
+13. [Grupos](#13-grupos)
+14. [Perfil e privacidade](#14-perfil-e-privacidade)
+15. [Eventos do socket](#15-eventos-do-socket)
+16. [Utilitários](#16-utilitários)
+17. [Fixar / Desfixar mensagens](#17-fixar--desfixar-mensagens)
+18. [Resolução de nomes (getName)](#18-resolução-de-nomes-getname)
+19. [PTT real com qualquer formato de entrada](#19-ptt-real-com-qualquer-formato-de-entrada)
+20. [Guard de pagamento stealth (anti-fraude)](#20-guard-de-pagamento-stealth-anti-fraude)
+21. [Bad MAC Handler — sessões Signal](#21-bad-mac-handler--sessões-signal)
+22. [Resolução LID → telefone via grupo](#22-resolução-lid--telefone-via-grupo)
+23. [Versão do WhatsApp sempre atualizada](#23-versão-do-whatsapp-sempre-atualizada)
+24. [WhatsApp Flows — Formulários interativos](#24-whatsapp-flows--formulários-interativos)
 
 ---
 
 ## 1. Conexão
 
-### Setup básico
-
 ```js
 const {
     default: makeWASocket,
@@ -84,13 +96,15 @@ sock.ev.on('connection.update', ({ connection, lastDisconnect }) => {
 })
 ```
 
+> Veja a seção [23](#23-versão-do-whatsapp-sempre-atualizada) para um jeito mais robusto de buscar a versão, que não falha silenciosamente.
+
 ### Pairing Code
 
 ```js
-// Código gerado automaticamente (ex: ABCD-EFGH)
+// Automático
 const code = await sock.requestPairingCode('5511999999999')
 
-// Código personalizado — exatamente 8 caracteres
+// Personalizado — exatamente 8 caracteres
 const code = await sock.requestPairingCode('5511999999999', 'MYBOT001')
 ```
 
@@ -110,7 +124,6 @@ const store = {
     },
     loadMessage: async (jid, id) => store.messages[jid]?.[id] || null
 }
-
 store.bind(sock.ev)
 ```
 
@@ -118,111 +131,52 @@ store.bind(sock.ev)
 
 ## 2. Mensagens de mídia
 
-Todos os campos de mídia aceitam `Buffer`, `{ url: 'https://...' }` ou `{ stream: ReadableStream }`.
-
-### Texto
+Todos os campos de mídia aceitam `Buffer`, `{ url: 'https://...' }` ou `{ stream }`.
 
 ```js
+// Texto
 await sock.sendMessage(jid, { text: 'Olá!' })
 
-// Com menção
+// Texto com menção
 await sock.sendMessage(jid, {
-    text:     '@55119...!',
+    text:     '@5511...!',
     mentions: ['5511999999999@s.whatsapp.net']
 })
-```
-
-### Imagem
-
-```js
-await sock.sendMessage(jid, {
-    image:   { url: 'https://exemplo.com/foto.jpg' },
-    caption: 'Legenda'
-})
-```
 
-### Vídeo
+// Imagem
+await sock.sendMessage(jid, { image: { url: 'https://...' }, caption: 'Legenda' })
 
-```js
-await sock.sendMessage(jid, {
-    video:       { url: 'https://exemplo.com/video.mp4' },
-    caption:     'Legenda',
-    gifPlayback: false   // true envia como GIF silencioso
-})
-```
-
-### Áudio
+// Vídeo
+await sock.sendMessage(jid, { video: buffer, caption: 'Legenda', gifPlayback: false })
 
-```js
-// Música
-await sock.sendMessage(jid, {
-    audio:    buffer,
-    mimetype: 'audio/mpeg',
-    ptt:      false
-})
+// Áudio normal (música)
+await sock.sendMessage(jid, { audio: buffer, mimetype: 'audio/mpeg', ptt: false })
 
-// Nota de voz (PTT)
-await sock.sendMessage(jid, {
-    audio:    buffer,
-    mimetype: 'audio/ogg; codecs=opus',
-    ptt:      true
-})
-```
+// Nota de voz (PTT) — ver seção 19 para conversão automática de qualquer formato
+await sock.sendMessage(jid, { audio: buffer, ptt: true })
 
-### Documento
+// Documento
+await sock.sendMessage(jid, { document: buffer, mimetype: 'application/pdf', fileName: 'doc.pdf' })
 
-```js
-await sock.sendMessage(jid, {
-    document: buffer,
-    mimetype: 'application/pdf',
-    fileName: 'relatorio.pdf',
-    caption:  'Segue o relatório'
-})
-```
-
-### Figurinha
-
-```js
+// Figurinha
 await sock.sendMessage(jid, { sticker: buffer })
-```
-
-### Album (múltiplas mídias agrupadas)
-
-Mínimo 2 itens.
 
-```js
+// Album (mínimo 2 itens)
 await sock.sendMessage(jid, {
-    album: [
-        { image: buffer1 },
-        { image: buffer2, caption: 'Segunda foto' },
-        { video: bufferVideo },
-    ]
+    album: [{ image: buffer1 }, { image: buffer2 }, { video: bufferVideo }]
 })
-```
 
-### Contato
-
-```js
+// Contato
 await sock.sendMessage(jid, {
     contacts: {
         displayName: 'João',
-        contacts: [{
-            vcard: `BEGIN:VCARD\nVERSION:3.0\nFN:João Silva\nTEL:+5511999999999\nEND:VCARD`
-        }]
+        contacts: [{ vcard: 'BEGIN:VCARD\nVERSION:3.0\nFN:João\nTEL:+5511999999999\nEND:VCARD' }]
     }
 })
-```
 
-### Localização
-
-```js
+// Localização
 await sock.sendMessage(jid, {
-    location: {
-        degreesLatitude:  -23.550520,
-        degreesLongitude: -46.633308,
-        name:             'São Paulo',
-        address:          'SP, Brasil'
-    }
+    location: { degreesLatitude: -23.55, degreesLongitude: -46.63, name: 'São Paulo' }
 })
 ```
 
@@ -230,201 +184,67 @@ await sock.sendMessage(jid, {
 
 ## 3. Mensagens especiais
 
-### Reação
-
 ```js
-await sock.sendMessage(jid, {
-    react: { text: '❤️', key: message.key }
-    // text: '' remove a reação
-})
-```
-
-### Deletar mensagem
+// Reação
+await sock.sendMessage(jid, { react: { text: '❤️', key: message.key } })
 
-```js
+// Deletar
 await sock.sendMessage(jid, { delete: message.key })
-```
-
-### Editar mensagem
 
-```js
-await sock.sendMessage(jid, {
-    edit: message.key,
-    text: 'Texto editado'
-})
-```
+// Editar
+await sock.sendMessage(jid, { edit: message.key, text: 'Texto editado' })
 
-### Fixar mensagem
+// Fixar — ver seção 17 para a versão completa
+await sock.sendMessage(jid, { pin: message.key, type: 1 })
 
-```js
-await sock.sendMessage(jid, {
-    pin: {
-        type:       1,           // 1 = fixar, 2 = desfixar
-        time:       86400,       // duração em segundos
-        messageKey: message.key
-    }
-})
-```
-
-### Encaminhar
-
-```js
-const { generateForwardMessageContent, generateWAMessageFromContent } = require('@systemzero/baileys')
-
-const content = generateForwardMessageContent(message, false)
-const msg     = generateWAMessageFromContent(jid, content, { quoted: m })
-await sock.relayMessage(jid, msg.message, { messageId: msg.key.id })
-```
-
-### View Once
-
-```js
+// View Once
 await sock.sendMessage(jid, { image: buffer, viewOnce: true })
-
-// V2
 await sock.sendMessage(jid, { image: buffer, viewOnceV2: true })
 
-// V2 Extension
-await sock.sendMessage(jid, { image: buffer, viewOnceV2Extension: true })
-```
-
-### Spoiler
-
-```js
-await sock.sendMessage(jid, {
-    image:   buffer,
-    caption: 'Spoiler!',
-    spoiler: true
-})
-```
-
-### Status de grupo
-
-```js
-await sock.sendMessage(jid, {
-    image:       buffer,
-    caption:     'Status do grupo',
-    groupStatus: true
-})
-```
-
-### Mensagem efêmera
-
-```js
-await sock.sendMessage(jid, {
-    image:    buffer,
-    ephemeral: true
-})
-```
-
-### Lottie (sticker animado especial)
-
-```js
-await sock.sendMessage(jid, {
-    sticker:  buffer,
-    isLottie: true
-})
-```
-
-### Keep (salvar mensagem)
-
-```js
-await sock.sendMessage(jid, {
-    keep: message.key,
-    type: 1   // 1 = salvar, 2 = remover
-})
-```
-
-### Evento
+// Spoiler
+await sock.sendMessage(jid, { image: buffer, caption: '!', spoiler: true })
 
-```js
-await sock.sendMessage(jid, {
-    event: {
-        isCanceled:  false,
-        name:        'Reunião',
-        description: 'Alinhamento',
-        location:    { name: 'Sala 3', address: 'Rua X, 100' },
-        startTime:   Math.floor(Date.now() / 1000) + 3600,
-        endTime:     Math.floor(Date.now() / 1000) + 7200,
-    }
-})
-```
+// Status de grupo
+await sock.sendMessage(jid, { image: buffer, groupStatus: true })
 
-### Enquete
+// Efêmera
+await sock.sendMessage(jid, { image: buffer, ephemeral: true })
 
-```js
-await sock.sendMessage(jid, {
-    poll: {
-        name:            'Qual seu time?',
-        values:          ['Flamengo', 'Corinthians', 'Palmeiras'],
-        selectableCount: 1   // 0 = múltipla escolha
-    }
-})
-```
+// Lottie sticker
+await sock.sendMessage(jid, { sticker: buffer, isLottie: true })
 
-### Invoice (nota fiscal)
+// Mention All
+await sock.sendMessage(jid, { text: '@all', mentionAll: true })
 
-```js
-await sock.sendMessage(jid, {
-    image:       buffer,
-    invoiceNote: 'Pagamento pedido #1234'
-})
-```
-
-### External Ad Reply
-
-```js
+// External Ad Reply
 await sock.sendMessage(jid, {
     text: 'Confira!',
     externalAdReply: {
-        title:                 'System Zero',
-        body:                  'Descrição do produto',
-        thumbnail:             bufferImagem,
-        mediaType:             1,
-        sourceUrl:             'https://systemzone.store',
+        title: 'Título', body: 'Descrição',
+        thumbnail: bufferImg, mediaType: 1,
+        sourceUrl: 'https://systemzone.store',
         renderLargerThumbnail: true
     }
 })
-```
 
-### Mention All
-
-```js
+// Enquete
 await sock.sendMessage(jid, {
-    text:       '👋 @all',
-    mentionAll: true
+    poll: { name: 'Pergunta?', values: ['A', 'B', 'C'], selectableCount: 1 }
 })
-```
 
-### Convite de pagamento
-
-```js
-await sock.sendMessage(jid, {
-    paymentInviteServiceType: 3
-})
+// Encaminhar
+const { generateForwardMessageContent, generateWAMessageFromContent } = require('@systemzero/baileys')
+const fwd = generateForwardMessageContent(message, false)
+const msg = generateWAMessageFromContent(jid, fwd, { quoted: m })
+await sock.relayMessage(jid, msg.message, { messageId: msg.key.id })
 ```
 
-### Resultado de enquete (snapshot)
-
-```js
-await sock.sendMessage(jid, {
-    pollResult: {
-        name:     'Pergunta?',
-        pollType: 0,   // 0 = poll, 1 = quiz
-        votes: [
-            { name: 'Opção A', voteCount: 12 },
-            { name: 'Opção B', voteCount: 7 },
-        ]
-    }
-})
-```
+> ⚠️ **Removido desta versão do README:** preview de link customizado (`linkPreview` manual) e áudio embutido em rodapé de card interativo (`audioFooter`). Os dois existem no proto do WhatsApp, mas em testes reais (Android e iOS) **não renderizaram corretamente** — o `audioFooter` não mostrou o player de áudio, e o `linkPreview` manual caiu num formato de card genérico em vez do esperado. Não são recursos confiáveis hoje.
 
 ---
 
 ## 4. Botões e interativos
 
-### Estrutura base
-
 ```js
 const { generateWAMessageFromContent, proto } = require('@systemzero/baileys')
 
@@ -433,11 +253,9 @@ const msg = generateWAMessageFromContent(jid, {
         message: {
             interactiveMessage: proto.Message.InteractiveMessage.create({
                 header: { title: 'Título', hasMediaAttachment: false },
-                body:   { text: 'Texto do corpo' },
+                body:   { text: 'Texto' },
                 footer: { text: 'Rodapé' },
-                nativeFlowMessage: {
-                    buttons: [ /* tipos abaixo */ ]
-                }
+                nativeFlowMessage: { buttons: [ /* tipos abaixo */ ] }
             })
         }
     }
@@ -446,178 +264,70 @@ const msg = generateWAMessageFromContent(jid, {
 await sock.relayMessage(jid, msg.message, { messageId: msg.key.id })
 ```
 
-### Tipos de botão
+### Tipos de botão (testados e funcionais)
 
 ```js
 // Resposta rápida
-{ name: 'quick_reply', buttonParamsJson: JSON.stringify({ display_text: 'Confirmar', id: 'confirmar' }) }
+{ name: 'quick_reply', buttonParamsJson: JSON.stringify({ display_text: 'OK', id: 'ok' }) }
 
-// Link externo
+// Link
 { name: 'cta_url', buttonParamsJson: JSON.stringify({ display_text: 'Abrir', url: 'https://systemzone.store' }) }
 
-// Copiar texto
-{ name: 'cta_copy', buttonParamsJson: JSON.stringify({ display_text: 'Copiar código', copy_code: 'PROMO2025' }) }
+// Copiar
+{ name: 'cta_copy', buttonParamsJson: JSON.stringify({ display_text: 'Copiar', copy_code: 'CODIGO' }) }
 
 // Ligar
 { name: 'cta_call', buttonParamsJson: JSON.stringify({ display_text: 'Ligar', phone_number: '5511999999999' }) }
 
-// Webview interno
-{ name: 'cta_webview', buttonParamsJson: JSON.stringify({ title: 'Painel', url: 'https://systemzone.store' }) }
-
-// Lista dropdown com seções
+// Lista dropdown
 {
     name: 'single_select',
     buttonParamsJson: JSON.stringify({
         title: 'Escolher',
-        sections: [{
-            title: 'Categoria',
-            rows: [
-                { header: 'Op 1', title: 'Opção 1', description: 'Desc', id: 'op1' },
-                { header: 'Op 2', title: 'Opção 2', description: 'Desc', id: 'op2' },
-            ]
-        }]
+        sections: [{ title: 'Cat', rows: [
+            { header: 'Op1', title: 'Opção 1', description: 'Desc', id: 'op1' }
+        ]}]
     })
 }
 ```
 
-### Header com imagem
-
-Upload da imagem antes de usar no header:
+### Header com imagem (funciona — confirmado em teste real)
 
 ```js
 const { generateWAMessage, generateMessageIDV2 } = require('@systemzero/baileys')
 
-const uploaded = await generateWAMessage(jid, { image: buffer }, {
-    upload:    sock.waUploadToServer,
-    userJid:   sock.user.id,
-    messageId: generateMessageIDV2(sock.user.id),
-})
-const img = uploaded.message?.imageMessage
-
-// No header:
-header: {
-    title:              '',
-    hasMediaAttachment: true,
-    imageMessage: {
-        url:               img.url,
-        mimetype:          img.mimetype,
-        fileSha256:        img.fileSha256,
-        fileLength:        img.fileLength,
-        mediaKey:          img.mediaKey,
-        fileEncSha256:     img.fileEncSha256,
-        directPath:        img.directPath,
-        mediaKeyTimestamp: img.mediaKeyTimestamp,
-        jpegThumbnail:     img.jpegThumbnail,
-    }
-}
-```
-
-### Catálogo (product no header)
-
-```js
-header: {
-    title:              'Produto',
-    hasMediaAttachment: true,
-    productMessage:     proto.Message.ProductMessage.create({
-        product: proto.Message.ProductMessage.ProductSnapshot.create({
-            productImage:    proto.Message.ImageMessage.create({ ...img }),
-            productId:       'ID-001',
-            title:           'Nome do Produto',
-            description:     'Descrição completa',
-            currencyCode:    'BRL',
-            priceAmount1000: 29990,   // R$ 29,99
-            retailerId:      'minha-loja',
-            url:             'https://loja.com/produto',
-            productImageCount: 1,
-        }),
-        businessOwnerJid: sock.user.id
-    })
-}
-```
-
-### Carousel
-
-```js
+// Forma simplificada e já testada: usar `image` + `caption` direto no sendMessage,
+// junto com nativeFlow — a lib monta o header automaticamente.
 await sock.sendMessage(jid, {
-    cards: [
-        {
-            image:      buffer1,
-            caption:    'Texto do card 1',
-            title:      'Card 1',
-            nativeFlow: [
-                { text: 'Ver mais', id: 'card1' },
-                { text: 'Site', url: 'https://systemzone.store' }
-            ]
-        },
-        {
-            image:      buffer2,
-            caption:    'Texto do card 2',
-            nativeFlow: [{ text: 'Clique', id: 'card2' }]
-        }
-    ],
-    footer: 'Rodapé'
+    image:      { url: 'https://...' },
+    caption:    'Texto do card',
+    nativeFlow: [{ text: 'Botão', id: 'btn1' }]
 })
 ```
 
+> Use `caption`, não `text`, quando quiser header com imagem junto de `nativeFlow` — usar `text` faz a lib pular inteiro o bloco que monta o header.
+
 ### Template Buttons
 
 ```js
 await sock.sendMessage(jid, {
-    text:            'Escolha:',
+    text: 'Escolha:',
     templateButtons: [
-        { text: 'Resposta', id:   'res1' },
-        { text: 'Site',     url:  'https://systemzone.store' },
-        { text: 'Ligar',    call: '5511999999999' },
-    ]
-})
-```
-
-### Sections (lista clássica)
-
-```js
-await sock.sendMessage(jid, {
-    text:       'Selecione',
-    buttonText: 'Ver opções',
-    sections: [{
-        title: 'Categoria',
-        rows: [
-            { title: 'Item 1', description: 'Desc', id: 'item1' },
-            { title: 'Item 2', description: 'Desc', id: 'item2' },
-        ]
-    }]
-})
-```
-
-### Interactive como Template
-
-```js
-await sock.sendMessage(jid, {
-    nativeFlow: [{ text: 'Clique', id: 'btn' }],
-    text:       'Mensagem',
-    interactiveAsTemplate: true
-})
-```
-
-### Botões com imagem no corpo (não no header)
-
-```js
-await sock.sendMessage(jid, {
-    image:   buffer,
-    caption: 'Escolha:',
-    buttons: [
-        { text: 'Opção 1', id: 'op1' },
-        { text: 'Link', url: 'https://systemzone.store' },
+        { text: 'Resposta', id: 'r1' },
+        { text: 'Site', url: 'https://systemzone.store' },
+        { text: 'Ligar', call: '5511999999999' },
     ]
 })
 ```
 
-### Áudio no rodapé de interativo
+### Sections
 
 ```js
 await sock.sendMessage(jid, {
-    text:        'Ouça e escolha:',
-    nativeFlow:  [{ text: 'Opção', id: 'op' }],
-    audioFooter: bufferAudio
+    text: 'Selecione', buttonText: 'Ver opções',
+    sections: [{ title: 'Cat', rows: [
+        { title: 'Item 1', description: 'Desc', id: 'i1' }
+    ]}]
 })
 ```
 
@@ -625,100 +335,55 @@ await sock.sendMessage(jid, {
 
 ## 5. Sticker Pack nativo
 
-Envia um pack de figurinhas que aparece na aba de stickers do WhatsApp, igual a um pack real.
-
 ```js
 await sock.sendMessage(jid, {
-    cover:    { url: 'https://exemplo.com/capa.webp' },
+    cover:    bufferWebP,
     stickers: [
-        { data: buffer1,       emojis: ['😂'] },
-        { data: bufferAnimado, emojis: ['🔥', '💀'] },
-        { data: bufferPng,     emojis: ['🐱'] },    // PNG converte automaticamente
+        { data: bufferWebP,  emojis: ['😂'] },
+        { data: bufferAnima, emojis: ['🔥'] },  // animada
+        { data: bufferPng,   emojis: ['✨'] },   // PNG converte auto
     ],
     name:        'Nome do Pack',
     publisher:   'Autor',
-    description: 'Descrição opcional'
+    description: 'Descrição'
 })
 ```
 
-`cover` aceita `Buffer`, `{ url }` ou `{ stream }`. O mesmo vale para cada `sticker.data`.
-
-Limites: máximo **60 figurinhas** por pack, cada uma com até **1MB**.
+> Tanto `cover` quanto cada item de `stickers[].data` esperam **Buffer**, não `{ url }`. Se você baixou as figurinhas de uma API, baixe o buffer primeiro (`axios.get(url, { responseType: 'arraybuffer' })`) antes de montar o objeto.
 
-Requer `sharp` ou `@napi-rs/image` para conversão de PNG e geração de thumbnail. Sem eles, apenas WebP é aceito.
+Máximo 60 figurinhas, cada uma até 1MB. Requer `sharp` ou `@napi-rs/image` para PNG.
 
 ---
 
 ## 6. Canais Newsletter
 
-### Enviar texto
-
 ```js
+// Texto
 await sock.sendMessage('120363...@newsletter', { text: 'Novidade!' })
-```
-
-### Enviar mídia
-
-`sendMessage` não passa pelo `encodeNewsletterMessage` corretamente para mídia. Use sempre `generateWAMessage` + `relayMessage`:
 
-```js
+// Mídia — sempre via generateWAMessage + relayMessage
 const { generateWAMessage, generateMessageIDV2 } = require('@systemzero/baileys')
 
-const canalJid = '120363...@newsletter'
-
-const fullMsg = await generateWAMessage(canalJid, {
-    image:   buffer,
-    caption: 'Legenda'
-}, {
-    upload:    sock.waUploadToServer,
-    userJid:   sock.user.id,
+const fullMsg = await generateWAMessage(canalJid, { image: buffer, caption: 'Legenda' }, {
+    upload: sock.waUploadToServer, userJid: sock.user.id,
     messageId: generateMessageIDV2(sock.user.id),
 })
+await sock.relayMessage(canalJid, fullMsg.message, { messageId: fullMsg.key.id })
 
-await sock.relayMessage(canalJid, fullMsg.message, {
-    messageId: fullMsg.key.id,
-})
-```
-
-Funciona para `image`, `video`, `audio`, `sticker`, `document`.
-
-### Gerenciar canais
-
-```js
-// Criar
-const canal = await sock.newsletterCreate('Nome do Canal', 'Descrição')
-
-// Seguir / deixar
+// Gerenciar
+const canal = await sock.newsletterCreate('Nome', 'Descrição')
 await sock.newsletterFollow(jid)
 await sock.newsletterUnfollow(jid)
-
-// Silenciar
 await sock.newsletterMute(jid)
 await sock.newsletterUnmute(jid)
-
-// Metadata
 const meta = await sock.newsletterMetadata('jid', jid)
-const meta = await sock.newsletterMetadata('invite', 'CODIGO')
-
-// Atualizar
 await sock.newsletterUpdateName(jid, 'Novo Nome')
 await sock.newsletterUpdateDescription(jid, 'Nova descrição')
 await sock.newsletterUpdatePicture(jid, buffer)
 await sock.newsletterRemovePicture(jid)
-
-// Reagir a mensagem
 await sock.newsletterReactMessage(jid, serverId, '❤️')
-
-// Listar mensagens
 const msgs = await sock.newsletterFetchMessages(jid, 30, 0, 0)
-
-// Admin
-const count    = await sock.newsletterAdminCount(jid)
-await sock.newsletterChangeOwner(jid, novoDonoJid)
-await sock.newsletterDemote(jid, usuarioJid)
 await sock.newsletterDelete(jid)
-
-// Seguidores
 const { subscribers } = await sock.newsletterSubscribers(jid)
 ```
 
@@ -726,56 +391,32 @@ const { subscribers } = await sock.newsletterSubscribers(jid)
 
 ## 7. Enquetes com decrypt
 
-### Criar enquete
-
 ```js
+// Criar
 await sock.sendMessage(jid, {
-    poll: {
-        name:            'Pergunta?',
-        values:          ['A', 'B', 'C'],
-        selectableCount: 1   // 0 = múltipla escolha
-    }
+    poll: { name: 'Pergunta?', values: ['A', 'B', 'C'], selectableCount: 1 }
 })
-```
-
-### Receber e descriptografar votos
-
-No `connect.js`, após `saveCreds`:
 
-```js
+// Receber votos — no connect.js após saveCreds:
 const { getAggregateVotesInPollMessage } = require('@systemzero/baileys/lib/Utils/messages.js')
 
 sock.ev.on('messages.update', async (updates) => {
     for (const { key, update } of updates) {
         if (!update.pollUpdates) continue
-
         const pollMsg = await store.loadMessage(key.remoteJid, key.id)
         if (!pollMsg?.message) continue
-
         const result = getAggregateVotesInPollMessage({
-            message:     pollMsg.message,
-            pollUpdates: update.pollUpdates,
+            message: pollMsg.message, pollUpdates: update.pollUpdates
         })
-
-        // [{ name: 'Opção A', voters: ['5511...@s.whatsapp.net'] }]
-        console.log(result)
-
-        if (!global.pollResults) global.pollResults = {}
-        global.pollResults[key.id] = { options: result, jid: key.remoteJid }
+        // [{ name: 'A', voters: ['5511...@s.whatsapp.net'] }]
     }
 })
 ```
 
-O `getMessage` precisa estar configurado no `makeWASocket` (veja seção 1).
-
 ---
 
 ## 8. AI Rich
 
-Mensagens com formatação avançada: markdown, código, tabelas, hyperlinks clicáveis no texto.
-
-### Direto pelo socket
-
 ```js
 // Texto com hyperlink
 await sock.sendRich(jid, [
@@ -789,231 +430,495 @@ await sock.sendRich(jid, [
 
 // Tabela
 await sock.sendRich(jid, [
-    sock.makeTable([
-        ['Nome',    'Status'],
-        ['Botões',  '✅'],
-        ['Canais',  '✅'],
-    ])
+    sock.makeTable([['Nome', 'Status'], ['Botões', '✅'], ['Canais', '✅']])
 ], null, ['RICH_RESPONSE_TABLE'])
 
 // Lista
-await sock.sendRich(jid, [
-    sock.makeList(['Item 1', 'Item 2', 'Item 3'])
-])
+await sock.sendRich(jid, [sock.makeList(['Item 1', 'Item 2'])])
 
-// Tudo junto
-await sock.sendRich(jid, [
-    sock.makeText('# Título\nConteúdo com [link](https://systemzone.store)'),
-    sock.makeCode('javascript', 'const x = require("@systemzero/baileys")'),
-    sock.makeTable([['Col A', 'Col B'], ['val1', 'val2']]),
-], quotedMsg, ['RICH_RESPONSE_CODE', 'RICH_RESPONSE_TABLE'])
+// Atalhos
+await sock.sendRichText(jid, 'Texto com [link](https://systemzone.store)', quotedMsg)
+await sock.sendRichCode(jid, 'Título', 'javascript', 'const x = 1', quotedMsg)
+await sock.sendRichList(jid, 'Lista', ['A', 'B'], quotedMsg)
 ```
 
-### Atalhos
+---
+
+## 9. LID / JID — Sistema avançado
+
+O WhatsApp usa dois tipos de identificador:
+- **JID** (`@s.whatsapp.net`) — formato baseado em número de telefone
+- **LID** (`@lid`) — identificador opaco, não contém o número de telefone
+
+A partir da v1.0.6, a baileys resolve automaticamente LID↔JID em mensagens recebidas e na metadata de grupo (ver seção 22), via `sharedLidPhoneCache`.
 
 ```js
-await sock.sendRichText(jid, 'Texto com [link](https://systemzone.store)', quotedMsg)
-await sock.sendRichCode(jid, 'Título', 'javascript', 'console.log("hi")', quotedMsg)
-await sock.sendRichList(jid, 'Lista', ['A', 'B', 'C'], quotedMsg)
+const {
+    lidToJid, resolveJid, resolveAll, normalizeJid, validateJid,
+    getSenderInfo, sharedLidPhoneCache, isLidUser, isPnUser,
+    getBotJid, setBotMap
+} = require('@systemzero/baileys')
 ```
 
-### Usando a classe AIRich
+```js
+const jid = lidToJid('123456@lid')
+const { jid, lid } = resolveAll('5511999999999@s.whatsapp.net')
+normalizeJid('5511999999999')         // → '5511999999999@s.whatsapp.net'
+normalizeJid('123456@lid')            // → resolve via cache
+const { isValid, error } = validateJid('5511999999999@s.whatsapp.net')
+const { jid, lid, isGroup, isValid } = getSenderInfo(message)
+```
+
+### Cache bidirecional
+
+O cache é populado automaticamente ao processar mensagens **e** ao buscar metadata de grupo (`groupMetadata`) — esse segundo ponto foi corrigido na v1.0.6, antes o par LID↔telefone que vem pronto na lista de participantes do grupo era descartado.
+
+```js
+sharedLidPhoneCache.set('123456@lid', '5511999999999@s.whatsapp.net') // manual, raro
+const jid = sharedLidPhoneCache.getPhoneForLid('123456@lid')
+const lid = sharedLidPhoneCache.getLidForPhone('5511999999999@s.whatsapp.net')
+console.log('Entradas no cache:', sharedLidPhoneCache.size)
+```
+
+> ⚠️ Atenção com sufixo de dispositivo: identidades do **próprio bot** (`sock.user.id` / `sock.user.lid`) costumam vir como `numero:N@dominio` (ex: `558892659041:10@s.whatsapp.net`). Pra comparar com a lista de `participants` (que não tem sufixo), remova só o `:N`, preservando o domínio: `jid.replace(/:\d+(?=@)/, '')` — **não use** `jid.split(':')[0]`, isso corta o domínio inteiro junto.
+
+---
+
+## 10. Username (@usuario)
 
 ```js
-const { AIRich } = require('@systemzero/baileys/lib/MB.cjs')
+const { resolveUsername, isUsername } = require('@systemzero/baileys')
 
+isUsername('@josue')    // true
+isUsername('josue')     // false
+
+const jid = await resolveUsername('@josue', sock.onWhatsApp.bind(sock))
+if (jid) await sock.sendMessage(jid, { text: 'Olá!' })
+```
+
+---
+
+## 11. MessageBuilder — Button, ButtonV2, Carousel, AIRich
+
+```js
+const { Button, ButtonV2, Carousel, AIRich } = require('@systemzero/baileys/lib/MB.cjs')
+```
+
+> O socket vai sempre no construtor: `new ButtonV2(sock)`
+
+### ButtonV2 — botões clássicos
+
+```js
+const msg = new ButtonV2(sock)
+msg.setTitle('Título')
+msg.setBody('Corpo')
+msg.setFooter('Rodapé')
+msg.setThumbnail('https://exemplo.com/imagem.jpg')
+msg.addButton('✅ Opção 1', 'opcao_1')
+msg.addButton('❌ Opção 2', 'opcao_2')
+await msg.send(jid, { quoted: m })
+```
+
+Capturar clique: `m.body` chega com o id do botão.
+
+### Button — native flow avançado
+
+```js
+const msg = new Button(sock)
+msg.setTitle('Título')
+msg.setBody('Corpo')
+msg.addReply('✅ Confirmar', 'confirmar')
+msg.addUrl('🔗 Abrir site', 'https://systemzone.store')
+msg.addCopy('📋 Copiar código', 'PROMO2025')
+msg.addCall('📞 Ligar', '5511999999999')
+await msg.send(jid, { quoted: m })
+```
+
+### Carousel
+
+```js
+const msg = new Carousel(sock)
+msg.setBody('Escolha um item:')
+msg.card(c => c.image('https://...').title('Card 1').text('Descrição').button('Ver', 'c1'))
+msg.card(c => c.image('https://...').title('Card 2').text('Descrição').button('Ver', 'c2'))
+await msg.send(jid, { quoted: m })
+```
+
+### AIRich
+
+```js
 const msg = new AIRich(sock)
-msg.addText('Texto com [link](https://systemzone.store)')
-msg.addCode('javascript', 'const x = 1')
-msg.addTable([['Col', 'Valor'], ['linha', 'dado']])
+msg.addText('Acesse [System Zero](https://systemzone.store).')
+msg.addCode('javascript', `const baileys = require('@systemzero/baileys')`)
+msg.addTable([['Comando', 'Descrição'], ['!menu', 'Abre o menu']])
 await msg.send(jid, { quoted: m })
 ```
 
 ---
 
-## 9. Grupos
+## 12. Botões estendidos (v1.0.6)
+
+> ⚠️ **Não verificado nesta versão do README.** Os tipos abaixo (`catalog`, `products`, `otp`, `orderDetails`, `flow`, etc) exigem conta **WhatsApp Business API verificada** com catálogo/pagamentos configurados — nenhum deles foi testado numa conta pessoal real. Os tipos mais simples (`reminder`, `address`, `location`, `phoneNumber`, `urlBtn`, `clearChat`) têm chance maior de funcionar em qualquer conta, mas também não foram confirmados em teste real. Trate como documentação do proto, não como garantia de funcionamento. Para formulários reais e testados, veja a seção 24.
+
+```js
+{ text: '⏰ Me lembre', reminder: 'lembrete_id' }
+{ text: '🔕 Cancelar', cancelReminder: 'lembrete_id' }
+{ text: '📍 Enviar endereço', address: true }
+{ text: '📡 Localização', location: true }
+{ text: '🛍️ Ver catálogo', catalog: '5511999999999@s.whatsapp.net' }
+{ text: '📦 Produtos', products: ['prod_id_1'], bizJid: '5511...@s.whatsapp.net' }
+{ text: 'Copiar código', otp: '123456' }
+{ text: '📞 Ligar', phoneNumber: '5511999999999' }
+{ text: '📋 Ver pedido', orderDetails: { order_id: '123', token: 'abc' } }
+{ text: '🗑️ Limpar chat', clearChat: true }
+{ text: '🔗 Abrir', urlBtn: 'https://systemzone.store' }
+```
+
+### isSystemNotification
+
+```js
+sock.ev.on('messages.upsert', async ({ messages }) => {
+    const msg = messages[0]
+    if (msg.isSystemNotification) return // ignora notificação de sistema
+})
+```
+
+---
+
+## 13. Grupos
 
 ```js
-// Criar
 const grupo = await sock.groupCreate('Nome', ['5511...@s.whatsapp.net'])
+const meta  = await sock.groupMetadata(jid)
 
-// Participantes
 await sock.groupParticipantsUpdate(jid, ['5511...@s.whatsapp.net'], 'add')
 await sock.groupParticipantsUpdate(jid, ['5511...@s.whatsapp.net'], 'remove')
 await sock.groupParticipantsUpdate(jid, ['5511...@s.whatsapp.net'], 'promote')
 await sock.groupParticipantsUpdate(jid, ['5511...@s.whatsapp.net'], 'demote')
-
-// Sair
 await sock.groupLeave(jid)
-
-// Nome e descrição
 await sock.groupUpdateSubject(jid, 'Novo Nome')
 await sock.groupUpdateDescription(jid, 'Nova descrição')
 
-// Convite
 const code = await sock.groupInviteCode(jid)
 await sock.groupRevokeInvite(jid)
 await sock.groupAcceptInvite('CODIGO')
-
-// Mensagens efêmeras (0 = desativar)
 await sock.groupToggleEphemeral(jid, 86400)
 
-// Metadata
-const meta   = await sock.groupMetadata(jid)
 const grupos = await sock.groupFetchAllParticipating()
 ```
 
 ---
 
-## 10. Perfil e privacidade
+## 14. Perfil e privacidade
 
 ```js
-// Foto de perfil
 const url = await sock.profilePictureUrl(jid, 'image')
 await sock.updateProfilePicture(jid, buffer)
-
-// Bio
 await sock.updateProfileStatus('🤖 Bot ativo')
 
-// Verificar número
 const [result] = await sock.onWhatsApp('5511999999999')
-// { exists: true, jid: '5511...@s.whatsapp.net' }
 
-// Bloquear / desbloquear
 await sock.updateBlockStatus(jid, 'block')
 await sock.updateBlockStatus(jid, 'unblock')
 
-// Presence
-await sock.sendPresenceUpdate('composing', jid)    // digitando
-await sock.sendPresenceUpdate('recording', jid)    // gravando
-await sock.sendPresenceUpdate('available', jid)    // online
-await sock.sendPresenceUpdate('unavailable')        // offline
-await sock.presenceSubscribe(jid)                   // receber presence de contato
+await sock.sendPresenceUpdate('composing', jid)
+await sock.sendPresenceUpdate('available', jid)
+await sock.presenceSubscribe(jid)
 
-// Marcar como lido
 await sock.readMessages([message.key])
 
-// Privacidade da foto
-await sock.updateProfilePicturePrivacy('all')    // 'all' | 'contacts' | 'none'
-
-// Modificar chat
 await sock.chatModify({ archive: true }, jid)
 await sock.chatModify({ pin: true }, jid)
 await sock.chatModify({ mute: 8 * 60 * 60 * 1000 }, jid)
-await sock.chatModify({ star: { messages: [{ id, fromMe }], star: true } }, jid)
-await sock.chatModify({ clear: { messages: [{ id, fromMe, timestamp }] } }, jid)
 
-// Desconectar
 await sock.logout()
 ```
 
 ---
 
-## 11. Eventos do socket
+## 15. Eventos do socket
 
 ```js
-sock.ev.on('messages.upsert',         ({ messages, type }) => {})
-sock.ev.on('messages.update',          (updates) => {})
-sock.ev.on('messages.delete',          (item) => {})
-sock.ev.on('messages.reaction',        (reactions) => {})
-sock.ev.on('presence.update',          ({ id, presences }) => {})
-sock.ev.on('groups.update',            (updates) => {})
+sock.ev.on('messages.upsert',          ({ messages, type }) => {})
+sock.ev.on('messages.update',           (updates) => {})
+sock.ev.on('messages.delete',           (item) => {})
+sock.ev.on('messages.reaction',         (reactions) => {})
+sock.ev.on('messages.decrypt-failed',   (failInfo) => {}) // ver seção 20
+sock.ev.on('presence.update',           ({ id, presences }) => {})
+sock.ev.on('groups.update',             (updates) => {})
 sock.ev.on('group-participants.update', ({ id, participants, action }) => {})
-sock.ev.on('contacts.update',          (contacts) => {})
-sock.ev.on('chats.update',             (chats) => {})
-sock.ev.on('connection.update',        ({ connection, lastDisconnect, qr }) => {})
-sock.ev.on('creds.update',             saveCreds)
+sock.ev.on('contacts.update',           (contacts) => {})
+sock.ev.on('connection.update',         ({ connection, lastDisconnect, qr }) => {})
+sock.ev.on('creds.update',              saveCreds)
 
-// Chamadas
 sock.ev.on('call', (calls) => {
     for (const call of calls) {
-        if (call.status === 'offer') {
-            sock.rejectCall(call.id, call.from)
-        }
+        if (call.status === 'offer') sock.rejectCall(call.id, call.from)
     }
 })
 ```
 
 ---
 
-## 12. Utilitários
+## 16. Utilitários
+
+```js
+const { downloadMediaMessage, downloadContentFromMessage } = require('@systemzero/baileys')
+const buffer = await downloadMediaMessage(message, 'buffer', {})
+
+const { generateWAMessage, generateWAMessageFromContent, generateMessageIDV2 } = require('@systemzero/baileys')
+
+const {
+    jidNormalizedUser, isJidGroup, isJidNewsletter,
+    isLidUser, isPnUser, isUsername,
+    normalizeJid, resolveAll, getSenderInfo,
+    jidEncode, jidDecode
+} = require('@systemzero/baileys')
+
+// Detectar dispositivo — analisa o FORMATO DO ID DA MENSAGEM, não o JID
+const { getDevice } = require('@systemzero/baileys')
+const device = getDevice(message.key.id) // 'android' | 'ios' | 'web' | 'unknown'
+```
 
-### Download de mídia
+> `getDevice` só funciona em cima de um `message.key.id` real — não dá pra usar pra "descobrir o dispositivo" de alguém sem ter uma mensagem recente dela pra inspecionar.
+
+---
+
+## 17. Fixar / Desfixar mensagens
 
 ```js
-const { downloadMediaMessage } = require('@systemzero/baileys')
+// Fixar (type: 1 = PIN_FOR_ALL)
+await sock.sendMessage(jid, { pin: quotedMsg.key, type: 1 })
 
-const buffer = await downloadMediaMessage(message, 'buffer', {})
-const stream = await downloadMediaMessage(message, 'stream', {})
+// Desfixar (type: 2 = UNPIN_FOR_ALL)
+await sock.sendMessage(jid, { pin: quotedMsg.key, type: 2 })
 ```
 
-### Download manual por stream
+`quotedMsg.key` precisa conter `remoteJid`, `fromMe`, `id` e (em grupos) `participant`.
+
+---
+
+## 18. Resolução de nomes (getName)
 
 ```js
-const { downloadContentFromMessage } = require('@systemzero/baileys')
+const { getName } = require('@systemzero/baileys')
+const nome = getName(msg, contactStore) // contactStore opcional: { [jid]: { name, notify, verifiedName } }
+```
+
+Ordem de prioridade: contato salvo localmente → `verifiedName` → `pushName`/`notify` → resolução `@lid` via cache → número formatado → `"Usuário desconhecido"`. Nunca retorna vazio.
+
+---
 
-const stream = await downloadContentFromMessage(
-    { mediaKey, directPath, url },
-    'image'   // 'image' | 'video' | 'audio' | 'sticker' | 'document'
-)
-const chunks = []
-for await (const chunk of stream) chunks.push(chunk)
-const buffer = Buffer.concat(chunks)
+## 19. PTT real com qualquer formato de entrada
+
+Antes da correção, `ptt: true` só **etiquetava** o mimetype como opus sem converter os bytes de verdade — qualquer entrada que não já fosse opus puro dava "algo errado com o arquivo de áudio" no WhatsApp. Agora a lib transcodifica de verdade via `ffmpeg` quando necessário.
+
+```js
+await sock.sendMessage(jid, {
+    audio: { url: 'https://qualquer-formato.mp3' }, // mp3, m4a, wav, o que for
+    ptt: true
+})
 ```
 
-### Geração de mensagem manual
+A lib detecta se a fonte já é `.opus`/`.ogg` (pela extensão real, não pelo que você declarar em `mimetype`) e só converte quando necessário, pra mono/16kHz — a especificação que o player de voz do WhatsApp espera.
+
+> Requer `ffmpeg` com `libopus` no `PATH` do servidor.
+
+---
+
+## 20. Guard de pagamento stealth (anti-fraude)
+
+A lib emite o evento `messages.decrypt-failed` sempre que uma mensagem de grupo falha na descriptografia (PreKey/CIPHERTEXT) — cobre o golpe de cobrança "invisível": mensagem normal enviada, depois **editada** pra conteúdo de pagamento.
 
 ```js
-const {
-    generateWAMessage,
-    generateWAMessageFromContent,
-    generateMessageIDV2,
-    generateForwardMessageContent
-} = require('@systemzero/baileys')
+const { bindPaymentGuard } = require('@systemzero/baileys')
 
-// Com upload automático de mídia
-const msg = await generateWAMessage(jid, { image: buffer }, {
-    upload:    sock.waUploadToServer,
-    userJid:   sock.user.id,
-    messageId: generateMessageIDV2(sock.user.id),
+bindPaymentGuard(sock, {
+    isPaymentMessage: (webMessage) => { /* sua lógica de detecção */ },
+    recordEnvelope:  (webMessage, isPayment) => { /* seu registro de corroboração */ },
+    treatDecryptFailureAsSuspicious: true,
+    onDetect: (detection) => {
+        // detection.type: 'direct' | 'edited' | 'undecryptable'
+    }
 })
+```
 
-// Sem upload (proto manual)
-const msg = generateWAMessageFromContent(jid, { ... }, { quoted: m })
+| Caminho | Evento | Garantia |
+|---|---|---|
+| Mensagem direta | `messages.upsert` | Roda seu detector no conteúdo normal |
+| Mensagem editada | `messages.update` | Extrai `editedMessage` e roda o mesmo detector |
+| Falha de decrypt | `messages.decrypt-failed` | Nunca ignora em silêncio, mesmo sem conteúdo |
 
-// Enviar o proto
-await sock.relayMessage(jid, msg.message, { messageId: msg.key.id })
+> Falha de decrypt nunca foi lida pelo bot — não existe forma de confirmar que era pagamento. O guard garante que isso nunca passe sem nenhum aviso, não que vai "adivinhar" o conteúdo.
+
+---
+
+## 21. Bad MAC Handler — sessões Signal
+
+```js
+const { BadMacHandler, badMacHandler } = require('@systemzero/baileys')
+
+if (badMacHandler.isBadMacError(error)) {
+    badMacHandler.handleError(error, 'algum-contexto')
+}
+
+// limpa sessões Signal problemáticas, preservando creds.json
+badMacHandler.clearProblematicSessionFiles()
 ```
 
-### Detectar dispositivo
+Erros "Bad MAC" são esperados ocasionalmente em qualquer cliente Signal Protocol (sessão desincronizada do outro lado) — esse handler conta, dá reset automático após um intervalo, e remove só arquivos de sessão por par, nunca as credenciais principais.
+
+---
+
+## 22. Resolução LID → telefone via grupo
 
 ```js
-const { getDevice } = require('@systemzero/baileys')
-const device = getDevice(message.key.id)
-// 'android' | 'ios' | 'web' | 'unknown'
+const { resolveLidPhoneFromGroup } = require('@systemzero/baileys')
+const telefone = await resolveLidPhoneFromGroup(sock, groupJid, lid)
 ```
 
-### JID utils
+Força a resolução de um `@lid` pro telefone real buscando a metadata do grupo (que já entrega o par pronto por participante) — útil quando o cache ainda não tem aquele par.
+
+---
+
+## 23. Versão do WhatsApp sempre atualizada
 
 ```js
-const {
-    jidNormalizedUser,
-    isJidGroup,
-    isJidNewsletter,
-    jidEncode,
-    jidDecode
-} = require('@systemzero/baileys')
+const { getBestWaVersion } = require('@systemzero/baileys')
+const { version, isLatest, source } = await getBestWaVersion()
+```
+
+Tenta `web.whatsapp.com`, depois GitHub, e só aceita um resultado se `isLatest === true` de verdade. Diferente de `fetchLatestWaWebVersion()`/`fetchLatestBaileysVersion()` isoladas, que sempre retornam algo (mesmo em falha, caindo num valor fixo antigo) sem deixar isso óbvio.
+
+---
+
+## 24. WhatsApp Flows — Formulários interativos
+
+> ⚠️ WhatsApp Flows é um recurso de **WhatsApp Business API**, normalmente exigindo um `flow_id` aprovado pela Meta pra sua conta/app específico. O exemplo abaixo é o que está em uso real no System Zero — funciona pro `flow_id` configurado nessa conta, mas **não é garantido que o mesmo `flow_id` funcione pra qualquer outra conta**. Pra criar seu próprio Flow, você precisa cadastrar e aprovar ele no Meta Business Manager.
+
+### Enviando o formulário
+
+```js
+const { generateWAMessageFromContent } = require('@systemzero/baileys')
+
+const formMsg = generateWAMessageFromContent(jid, {
+    viewOnceMessage: {
+        message: {
+            messageContextInfo: {
+                deviceListMetadata: {},
+                deviceListMetadataVersion: 2
+            },
+            interactiveMessage: {
+                body: { text: 'Formulário de teste\n\nPreencha seus dados.' },
+                nativeFlowMessage: {
+                    buttons: [{
+                        name: 'galaxy_message',
+                        buttonParamsJson: JSON.stringify({
+                            flow_message_version: '4',
+                            flow_id: 'SEU_FLOW_ID_AQUI',
+                            flow_action_payload: {
+                                screen: 'contact_details',
+                                data: {
+                                    full_name_visible:    true,
+                                    phone_number_visible: true,
+                                    email_visible:        true,
+                                    offer_name:           'Olá, seja bem-vindo',
+                                    offer_description:    'Sistema de teste'
+                                }
+                            },
+                            well_version: 'V700',
+                            flow_cta:     '__localize:FLOWS_SIGN_UP_BUTTON_TITLE',
+                            flow_action:  'navigate',
+                            flow_token:   'T0ZGRVJfU0lHTlVQ'
+                        })
+                    }],
+                    messageParamsJson: '{}'
+                }
+            }
+        }
+    }
+}, { userJid: sock.user.id })
 
-jidNormalizedUser('5511999999999@s.whatsapp.net')
-isJidGroup('120363...@g.us')            // true
-isJidNewsletter('120363...@newsletter') // true
+await sock.relayMessage(jid, formMsg.message, { messageId: formMsg.key.id })
 ```
 
+### Recebendo a resposta
+
+A resposta do formulário chega como `interactiveResponseMessage`. O `nativeFlowResponseMessage.paramsJson` traz os dados preenchidos dentro de `wa_flow_response_params.response_message` (uma string JSON aninhada — precisa de `JSON.parse` duplo).
+
+```js
+sock.ev.on('messages.upsert', async ({ messages }) => {
+    const m = messages[0]
+    if (m.message?.interactiveResponseMessage) {
+        const nfr = m.message.interactiveResponseMessage.nativeFlowResponseMessage
+
+        if (nfr?.name === 'galaxy_message' && nfr?.paramsJson) {
+            const parsed = JSON.parse(nfr.paramsJson)
+            if (!parsed.wa_flow_response_params) return
+
+            const flowParams  = parsed.wa_flow_response_params
+            const flowId      = flowParams.flow_id || ''
+            const rawResponse = flowParams.response_message || ''
+
+            let screens = []
+            try { screens = JSON.parse(rawResponse).screens || [] } catch {}
+
+            // extrai só os campos preenchidos
+            const campos = {}
+            for (const screen of screens) {
+                for (const comp of (screen.components || [])) {
+                    if (comp.name && comp.value !== undefined && comp.value !== '') {
+                        campos[comp.name] = comp.value
+                    }
+                }
+            }
+
+            // roteia por flow_id — adicione mais formulários aqui
+            if (flowId === 'SEU_FLOW_ID_AQUI') {
+                let resposta = 'Formulário recebido!\n\n'
+                if (campos.full_name)    resposta += `Nome: ${campos.full_name}\n`
+                if (campos.phone_number) resposta += `Telefone: +${campos.phone_number}\n`
+                if (campos.email)        resposta += `Email: ${campos.email}\n`
+                await sock.sendMessage(m.key.remoteJid, { text: resposta }, { quoted: m })
+            }
+        }
+    }
+})
+```
+
+---
+
+## Changelog
+
+### v1.0.6
+- **Fix PTT real** — `ptt: true` agora transcodifica via `ffmpeg` quando necessário, em vez de só etiquetar o mimetype
+- **Fix groupMetadata → sharedLidPhoneCache** — pares LID↔telefone da lista de participantes de grupo agora são registrados no cache (antes eram descartados)
+- **Fix cleanId de identidade própria** — comparação de `sock.user.id`/`sock.user.lid` com sufixo de dispositivo (`:N`) agora preserva o domínio
+- **Guard de pagamento stealth** — `bindPaymentGuard`, evento `messages.decrypt-failed`
+- **Bad MAC Handler** — `BadMacHandler`, `badMacHandler`
+- **getName** — resolução de nome em cascata, nunca vazia
+- **getBestWaVersion** — busca de versão que não falha em silêncio
+- **resolveLidPhoneFromGroup** — força resolução via metadata de grupo
+- **WhatsApp Flows** — suporte documentado a formulários interativos (`nativeFlowResponseMessage`)
+- **isSystemNotification** — flag em mensagens de notificação de sistema
+- Sistema LID/JID avançado com cache bidirecional (`sharedLidPhoneCache`)
+- `lidToJid`, `resolveJid`, `resolveAll`, `normalizeJid`, `validateJid`, `getSenderInfo`
+- Suporte a `@username` — `isUsername`, `resolveUsername`
+
+### v1.0.5
+- Sticker Pack nativo com suporte a animadas e PNG
+- Fix canal newsletter (`extraAttrs` no `plaintext`)
+- Album, Spoiler, ViewOnce V2, Ephemeral, Lottie, Evento
+- Native Flow, Carousel, Template Buttons
+- AI Rich (makeText, makeCode, makeTable, makeList, sendRich)
+- Poll decrypt com `getAggregateVotesInPollMessage`
+- MessageBuilder (`Button`, `ButtonV2`, `Carousel`, `AIRich`)
+
 ---
 
 <div align="center">
 
-**@systemzero/baileys v1.0.5**
+**@systemzero/baileys v1.0.6**
 
 Desenvolvido por [Josué </>](https://t.me/blackhzx) · [Canal WhatsApp](https://whatsapp.com/channel/0029VaqUb9aGk1FxqeKKOd2i) · [systemzone.store](https://systemzone.store)