feat(builder): inherit the chat disappearing timer on every send

Author: zeative

docs/content/message-payload.mdx

@@ -300,9 +300,10 @@ A few values come from your `Client` config rather than the raw message:
 - **`isSpam` is reserved** and always `false` today. Use `forwardCount >= 5` for chain-message detection.
 - **Answer only live messages.** After a reconnect WhatsApp replays everything you missed. Guard with
   `if (ctx.isOld) return` unless you deliberately want to process the backlog.
-- **`ctx.reply()` inherits the disappearing timer automatically.** An answer in a disappearing chat
-  disappears with it. Only `client.send(...)` needs `.disappearing(ctx.ephemeralDuration)` passed by
-  hand — without it WhatsApp marks the message *"this message won't disappear"*.
+- **Disappearing timers are inherited automatically.** zaileys learns each chat's timer from its
+  inbound messages, so `ctx.reply()` **and** every `client.send(...)` into that chat — text, media,
+  stickers, albums — carry it without you asking. Pass `.disappearing(seconds)` only to override it.
+  Messages sent without the timer are the ones WhatsApp flags *"this message won't disappear"*.
 - **`senderUsername` is usually `null` — WhatsApp sends the phone number _or_ the username, never
   both.** A username is the fallback handle for a sender whose number you cannot see, so it stays
   `null` for anyone whose phone number your account already knows (which is most people). It arrives

docs/content/sending-messages.mdx

@@ -647,6 +647,15 @@ Send as an ephemeral/disappearing message. Takes a **positive integer** number o
 await client.send(to).text('self-destructs in a day').disappearing(86400)
 ```
 
+<Callout type="info">
+**You rarely need this.** zaileys learns each chat's disappearing timer from the messages it
+receives, and every send into that chat inherits it automatically — replies, media, stickers,
+albums alike. Call `.disappearing()` only to override the chat's own timer.
+
+A message sent *without* the chat's timer is what makes WhatsApp show
+*"this message won't disappear"* beside it.
+</Callout>
+
 ### `.to(recipient)`
 
 Reassign the recipient on an `init`-state builder before adding content (rarely needed since

src/builder/builder.ts

@@ -119,10 +119,11 @@ export class MessageBuilder<State extends BuilderState> {
     recipient: string,
     resolveRecipient?: (raw: string) => Promise<string>,
     recordSent?: (message: WAMessage) => void,
+    inheritDisappearing?: (jid: string) => number | undefined,
   ): MessageBuilder<'init'> {
     return new MessageBuilder<'init'>(
       socket,
-      createInternalState(recipient, resolveRecipient, recordSent),
+      createInternalState(recipient, resolveRecipient, recordSent, inheritDisappearing),
     )
   }
 
@@ -349,6 +350,11 @@ export class MessageBuilder<State extends BuilderState> {
         this.internal.recipient = await this.internal.resolveRecipient(this.internal.recipient)
         delete this.internal.resolveRecipient
       }
+      /** Resolved once here so text, media, album and relay sends all inherit the chat's timer. */
+      if (this.internal.disappearingSeconds === undefined) {
+        const inherited = this.internal.inheritDisappearing?.(this.internal.recipient)
+        if (inherited !== undefined && inherited > 0) this.internal.disappearingSeconds = inherited
+      }
       if (this.internal.statusJidList !== undefined && this.internal.recipient !== STATUS_BROADCAST_JID) {
         throw new ZaileysBuilderError(
           'INVALID_RECIPIENT',

src/builder/state.ts

@@ -13,14 +13,18 @@ export type BuilderInternalState = {
   disappearingSeconds?: number
   resolveRecipient?: (raw: string) => Promise<string>
   recordSent?: (message: WAMessage) => void
+  /** The chat's own disappearing timer, applied when the caller did not set one. */
+  inheritDisappearing?: (jid: string) => number | undefined
 }
 
 export const createInternalState = (
   recipient: string,
   resolveRecipient?: (raw: string) => Promise<string>,
   recordSent?: (message: WAMessage) => void,
+  inheritDisappearing?: (jid: string) => number | undefined,
 ): BuilderInternalState => ({
   recipient,
   ...(resolveRecipient ? { resolveRecipient } : {}),
   ...(recordSent ? { recordSent } : {}),
+  ...(inheritDisappearing ? { inheritDisappearing } : {}),
 })

src/client/client.ts

@@ -210,6 +210,8 @@ export class Client extends TypedEventEmitter<ClientEventMap> {
   private readonly presenceThrottle: PresenceThrottleOptions | undefined
   private readonly scheduleLimiter: RateLimiter | undefined
   private authExhausted = false
+  /** Each chat's disappearing timer, learned from inbound messages so outbound sends can inherit it. */
+  private readonly chatExpiration = new Map<string, number>()
   private _socket: BaileysSocket | undefined
   private reconnectTimer: ReturnType<typeof setTimeout> | undefined
   private listenerCleanup: SocketCleanup[] = []
@@ -269,6 +271,7 @@ export class Client extends TypedEventEmitter<ClientEventMap> {
     this.qrTerminal = options.qrTerminal ?? true
     this.statusLog = options.statusLog ?? true
     if (this.statusLog) suppressLibsignalNoise()
+    this.on('message', (msg) => this.rememberChatExpiration(msg))
     this.reconnectOptions = options.reconnect ?? {}
     this.baileysExtra = options.baileys ?? {}
     this.auth = options.auth ?? new FileAuthStore({ basePath: `./.zaileys/auth/${this.sessionId}` })
@@ -873,10 +876,31 @@ export class Client extends TypedEventEmitter<ClientEventMap> {
     const recordSent = (message: WAMessage): void => {
       void this.store.saveMessage(message).catch((err) => this.logger.warn(err, 'recordSent failed'))
     }
+    const inherit = (jid: string): number | undefined => this.chatExpiration.get(jid)
     if (this._provider === 'cloud' || isJid(to)) {
-      return MessageBuilder.create(socket, to, undefined, recordSent)
+      return MessageBuilder.create(socket, to, undefined, recordSent, inherit)
+    }
+    return MessageBuilder.create(
+      socket,
+      to,
+      (raw) => this.resolveRecipient(raw),
+      recordSent,
+      inherit,
+    )
+  }
+
+  private rememberChatExpiration(msg: MessageContext): void {
+    const room = msg.roomId
+    if (room === null) return
+    if (msg.ephemeralDuration === null) {
+      this.chatExpiration.delete(room)
+      return
+    }
+    if (this.chatExpiration.size >= 500 && !this.chatExpiration.has(room)) {
+      const oldest = this.chatExpiration.keys().next().value
+      if (oldest !== undefined) this.chatExpiration.delete(oldest)
     }
-    return MessageBuilder.create(socket, to, (raw) => this.resolveRecipient(raw), recordSent)
+    this.chatExpiration.set(room, msg.ephemeralDuration)
   }
 
   edit(key: WAMessageKey): EditBuilder {

tests/client/reply-lifetime.test.ts

@@ -24,6 +24,7 @@ const msg = (expiration?: number): MessageContext =>
     senderId: SENDER,
     roomId: SENDER,
     isGroup: false,
+    ephemeralDuration: expiration ?? null,
     message: () => quoted(expiration),
   }) as unknown as MessageContext
 
@@ -68,3 +69,45 @@ describe('replies inherit the disappearing timer', () => {
     expect(optionsOf(sendMessage).ephemeralExpiration).toBeUndefined()
   })
 })
+
+describe('every send into a disappearing chat inherits its timer', () => {
+  /** Teaches the client the chat's timer the way a real inbound message would. */
+  const learn = (client: Client, seconds: number): void => {
+    client.emit('message', msg(seconds))
+  }
+
+  it('applies it to a plain text send, not just a reply', async () => {
+    const { client, sendMessage } = connected()
+    learn(client, 86400)
+    await client.send(SENDER).text('halo')
+    expect(optionsOf(sendMessage).ephemeralExpiration).toBe(86400)
+  })
+
+  it('applies it to media — the sticker case', async () => {
+    const { client, sendMessage } = connected()
+    learn(client, 604800)
+    await client.send(SENDER).image(Buffer.from('jpeg'))
+    expect(optionsOf(sendMessage).ephemeralExpiration).toBe(604800)
+  })
+
+  it('never overrides a timer the caller set explicitly', async () => {
+    const { client, sendMessage } = connected()
+    learn(client, 604800)
+    await client.send(SENDER).text('halo').disappearing(60)
+    expect(optionsOf(sendMessage).ephemeralExpiration).toBe(60)
+  })
+
+  it('adds nothing for a chat it has never seen', async () => {
+    const { client, sendMessage } = connected()
+    await client.send('628999@s.whatsapp.net').text('halo')
+    expect(optionsOf(sendMessage).ephemeralExpiration).toBeUndefined()
+  })
+
+  it('forgets the timer once the chat stops disappearing', async () => {
+    const { client, sendMessage } = connected()
+    learn(client, 604800)
+    client.emit('message', msg())
+    await client.send(SENDER).text('halo')
+    expect(optionsOf(sendMessage).ephemeralExpiration).toBeUndefined()
+  })
+})