@adatechnology/conversations-ui 0.1.0-rc.6 → 0.1.0-rc.7

package/src/preview/ConversationPreview.tsx

@@ -13,13 +13,14 @@
  */
 
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import type { MessagePayload } from '../types'
+import type { InteractiveSelection, MessagePayload } from '../types'
 import type { SSEProvider } from '../providers/types'
 import { MessageBubble } from '../MessageBubble'
 import { MessageComposer } from '../MessageComposer'
 import { DateDivider } from '../DateDivider'
 import { ConversationWallpaper } from '../Wallpaper'
-import type { PreviewWebhookClient } from './createPreviewWebhookClient'
+import type { PreviewWebhookClient, SendPreviewMediaParams } from './createPreviewWebhookClient'
+import { AudioRecorderButton } from './AudioRecorderButton'
 
 export type ConversationPreviewProps = {
   client: PreviewWebhookClient
@@ -27,12 +28,43 @@ export type ConversationPreviewProps = {
   conversationId: string
   loadMessages: (conversationId: string) => Promise<MessagePayload[]>
   placeholder?: string
+  /**
+   * Recarrega o transcript a cada N ms. Serve a host SEM stream: a resposta do bot é assíncrona, e
+   * sem SSE nem polling ela só apareceria no próximo envio — o sintoma é "às vezes ele não
+   * responde". Ausente, não faz polling (host com SSE não precisa).
+   */
+  pollIntervalMs?: number
+  /**
+   * Como transformar um arquivo do disco (ou o áudio gravado) na referência que o webhook carrega.
+   * O caminho da Meta entrega mídia por `id`, e quem sabe hospedar o arquivo é o host — a SDK não
+   * inventa um endpoint de upload. Ausente, o compositor não oferece anexo nem gravação: melhor um
+   * botão que não existe do que um que falha ao ser tocado.
+   */
+  uploadMedia?: (file: File) => Promise<PreviewUploadedMedia>
+}
+
+export type PreviewUploadedMedia = {
+  readonly mediaId: string
+  readonly mimeType?: string
+  readonly filename?: string
+}
+
+/** Deriva o tipo de mídia do WhatsApp a partir do MIME do arquivo escolhido. */
+export function mediaTypeOf(mimeType: string): SendPreviewMediaParams['mediaType'] {
+  if (mimeType.startsWith('image/')) return 'image'
+  if (mimeType.startsWith('video/')) return 'video'
+  if (mimeType.startsWith('audio/')) return 'audio'
+  return 'document'
 }
 
 // Mesma janela usada pelo WhatsApp para colar bolhas do mesmo autor: acima disso, a mensagem
 // recomeça um grupo (com rabicho e espaçamento maior).
 const GROUPING_WINDOW_MS = 5 * 60 * 1000
 
+// Escalonado, não um atraso fixo: a maioria das respostas chega em ~300ms, mas fluxo que consulta
+// catálogo ou IA demora mais — e recarregar três vezes é mais barato que a conversa parecer morta.
+const FOLLOW_UP_REFRESH_MS = [400, 1200, 3000]
+
 type RenderedMessage = {
   readonly message: MessagePayload
   readonly isFirstInGroup: boolean
@@ -55,26 +87,79 @@ function decorate(messages: readonly MessagePayload[]): RenderedMessage[] {
   })
 }
 
+/**
+ * Status HTTP do erro, quando o host o preserva.
+ *
+ * O contrato não exige um tipo de erro — cada host tem o seu —, então a leitura é estrutural: basta
+ * carregar `status` (ou `statusCode`) para ser classificável. Host que joga `new Error(texto)` cai no
+ * caminho genérico, que ainda é melhor que silêncio.
+ */
+function statusOf(error: unknown): number | undefined {
+  if (typeof error !== 'object' || error === null) return undefined
+  const candidate = error as { status?: unknown; statusCode?: unknown }
+  const value = candidate.status ?? candidate.statusCode
+  return typeof value === 'number' ? value : undefined
+}
+
+export function isNotFound(error: unknown): boolean {
+  return statusOf(error) === 404
+}
+
+export function describeLoadFailure(error: unknown): string {
+  const status = statusOf(error)
+  // 401/403 no simulador quase sempre é a aba sem sessão: `sessionStorage` é por aba, e link com
+  // `rel="noreferrer"` abre contexto novo que não herda o token do painel.
+  if (status === 401 || status === 403) {
+    return 'Sem sessão de administrador nesta aba: a mensagem é entregue no webhook, mas o transcript não pode ser lido. Entre no painel nesta mesma aba e reabra o simulador.'
+  }
+  if (error instanceof Error && error.message) return `Não foi possível ler o transcript: ${error.message}`
+  return 'Não foi possível ler o transcript da conversa.'
+}
+
 export function ConversationPreview({
   client,
   sse,
   conversationId,
   loadMessages,
   placeholder,
+  pollIntervalMs,
+  uploadMedia,
 }: ConversationPreviewProps) {
   const [messages, setMessages] = useState<MessagePayload[]>([])
   const [failure, setFailure] = useState<string | undefined>(undefined)
+  const [loadFailure, setLoadFailure] = useState<string | undefined>(undefined)
+  // Mensagens que o servidor ainda não devolveu. Sem isto, quem não consegue LER a conversa (sessão
+  // ausente, API fora) digita, envia com sucesso e não vê absolutamente nada mudar — o preview fica
+  // indistinguível de quebrado. São descartadas assim que uma leitura dá certo: aí quem manda na
+  // tela é o servidor, que já tem a mensagem gravada.
+  const [pendingLocal, setPendingLocal] = useState<MessagePayload[]>([])
   const loadMessagesRef = useRef(loadMessages)
   const bottomRef = useRef<HTMLDivElement>(null)
   loadMessagesRef.current = loadMessages
 
   const refresh = useCallback(async (): Promise<void> => {
     try {
-      setMessages(await loadMessagesRef.current(conversationId))
-    } catch {
-      // Conversa que ainda não existe é o estado normal do primeiro contato — a API responde erro
-      // e a tela deve mostrar o transcript vazio, não uma falha.
-      setMessages([])
+      const loaded = await loadMessagesRef.current(conversationId)
+      setMessages(loaded)
+      setLoadFailure(undefined)
+      // Só descarta o eco quando o servidor de fato devolveu conversa: lista vazia é "não consegui
+      // ver nada" (sessão ausente, primeiro contato), e limpar aí apagava da tela a mensagem que o
+      // usuário acabou de mandar — o sintoma que este eco existe para evitar.
+      if (loaded.length > 0) setPendingLocal([])
+    } catch (error) {
+      // Conversa que ainda não existe é o estado normal do primeiro contato — transcript vazio, sem
+      // alarme. QUALQUER outra falha precisa aparecer: engolir todas era o que transformava sessão
+      // expirada (401) em silêncio absoluto, com a thread limpa e o operador concluindo que o envio
+      // não funcionou — quando a mensagem tinha sido entregue no webhook.
+      if (isNotFound(error)) {
+        setMessages([])
+        setLoadFailure(undefined)
+        return
+      }
+
+      // Não limpa o que já está na tela: perder o histórico por causa de um refresh que falhou é
+      // dano maior que o próprio erro.
+      setLoadFailure(describeLoadFailure(error))
     }
   }, [conversationId])
 
@@ -95,19 +180,47 @@ export function ConversationPreview({
     }
   }, [sse, conversationId, refresh])
 
+  useEffect(() => {
+    if (!pollIntervalMs) return
+    const timer = setInterval(() => void refresh(), pollIntervalMs)
+    return () => clearInterval(timer)
+  }, [pollIntervalMs, refresh])
+
   useEffect(() => {
     bottomRef.current?.scrollIntoView({ behavior: 'smooth' })
   }, [messages])
 
-  const rendered = useMemo(() => decorate(messages), [messages])
+  const rendered = useMemo(() => decorate([...messages, ...pendingLocal]), [messages, pendingLocal])
+
+  async function refreshWithFollowUps(): Promise<void> {
+    await refresh()
+    for (const atraso of FOLLOW_UP_REFRESH_MS) {
+      setTimeout(() => void refresh(), atraso)
+    }
+  }
 
   async function handleSend(text: string): Promise<void> {
     setFailure(undefined)
     try {
       await client.sendText(text)
-      // O bot responde de forma assíncrona e o ping do SSE cobre isso; este refresh é para a
-      // própria mensagem enviada aparecer na hora, sem esperar o ciclo de evento.
-      await refresh()
+      setPendingLocal((current) => [
+        ...current,
+        {
+          id: `local-${current.length}-${text.length}`,
+          type: 'text',
+          content: text,
+          // Do ponto de vista do servidor, mensagem do cliente é inbound — é assim que ela aparece
+          // como "minha" nesta visão.
+          direction: 'inbound',
+          sender: 'customer',
+          timestamp: new Date().toISOString(),
+          status: 'sent',
+        },
+      ])
+      // O bot responde de forma assíncrona: gravar a resposta leva algumas centenas de ms depois do
+      // 200 do webhook. Um refresh único aqui frequentemente chegava ANTES dela, e a conversa ficava
+      // com a pergunta sem resposta até o envio seguinte.
+      await refreshWithFollowUps()
     } catch (error) {
       // A recusa mais provável é assinatura inválida (segredo divergente do que a API valida), e
       // ela precisa aparecer na tela: silenciada, o sintoma vira "mandei e não aconteceu nada".
@@ -115,6 +228,37 @@ export function ConversationPreview({
     }
   }
 
+  async function handleInteractiveSelect(selection: InteractiveSelection): Promise<void> {
+    setFailure(undefined)
+    const reply = { id: selection.option.id, title: selection.option.title }
+    try {
+      // Botão e lista são payloads diferentes para a Meta (`button_reply` × `list_reply`), e o
+      // roteador do fluxo lê campos distintos: tratar os dois como um só faria o menu responder no
+      // simulador e falhar no aparelho do cliente.
+      await (selection.kind === 'button' ? client.sendButtonReply(reply) : client.sendListReply(reply))
+      await refreshWithFollowUps()
+    } catch (error) {
+      setFailure(error instanceof Error ? error.message : 'Falha ao entregar a resposta no webhook.')
+    }
+  }
+
+  async function handleAttach(file: File): Promise<void> {
+    if (!uploadMedia) return
+    setFailure(undefined)
+    try {
+      const uploaded = await uploadMedia(file)
+      await client.sendMedia({
+        mediaType: mediaTypeOf(uploaded.mimeType ?? file.type),
+        mediaId: uploaded.mediaId,
+        mimeType: uploaded.mimeType ?? file.type,
+        filename: uploaded.filename ?? file.name,
+      })
+      await refreshWithFollowUps()
+    } catch (error) {
+      setFailure(error instanceof Error ? error.message : 'Falha ao enviar o arquivo.')
+    }
+  }
+
   return (
     <div className="flex h-full min-h-0 flex-col">
       <ConversationWallpaper className="flex-1 min-h-0 overflow-y-auto px-4 py-3">
@@ -127,6 +271,11 @@ export function ConversationPreview({
               // vista do servidor.
               isMine={message.direction === 'inbound'}
               isFirstInGroup={isFirstInGroup}
+              // Só o que o bot ofereceu é tocável: reoferecer as opções da própria mensagem do
+              // cliente deixaria o menu clicável para sempre, o que o WhatsApp não faz.
+              onInteractiveSelect={
+                message.direction === 'outbound' ? (selection) => void handleInteractiveSelect(selection) : undefined
+              }
             />
           </div>
         ))}
@@ -139,10 +288,30 @@ export function ConversationPreview({
         </p>
       ) : null}
 
-      <MessageComposer
-        onSend={(text) => void handleSend(text)}
-        placeholder={placeholder ?? 'Escreva como o cliente…'}
-      />
+      {/* Separado da falha de ENVIO: são causas diferentes e confundi-las manda o operador
+          investigar assinatura de webhook quando o problema é sessão. Amarelo, não vermelho — a
+          mensagem foi entregue; o que faltou foi poder ler a conversa de volta. */}
+      {loadFailure ? (
+        <p role="status" className="px-4 py-2 text-sm text-amber-700 dark:text-amber-400">
+          {loadFailure}
+        </p>
+      ) : null}
+
+      <div className="flex items-end gap-1">
+        <div className="min-w-0 flex-1">
+          <MessageComposer
+            onSend={(text) => void handleSend(text)}
+            onAttach={uploadMedia ? (file) => void handleAttach(file) : undefined}
+            placeholder={placeholder ?? 'Escreva como o cliente…'}
+          />
+        </div>
+        {uploadMedia ? (
+          <AudioRecorderButton
+            onRecorded={(file) => void handleAttach(file)}
+            onFailure={(message) => setFailure(message)}
+          />
+        ) : null}
+      </div>
     </div>
   )
 }

package/src/preview/audioRecorderFormat.test.ts

@@ -0,0 +1,67 @@
+import { afterEach, describe, expect, it } from 'bun:test'
+
+import { resolveRecordingFormat } from './AudioRecorderButton'
+import { DEFAULT_ACCEPTED_FILE_TYPES } from '../MessageComposer'
+
+const originalMediaRecorder = (globalThis as Record<string, unknown>).MediaRecorder
+
+function stubMediaRecorder(supported: readonly string[] | undefined): void {
+  const stub = supported ? { isTypeSupported: (mimeType: string) => supported.includes(mimeType) } : {}
+  ;(globalThis as Record<string, unknown>).MediaRecorder = stub
+}
+
+afterEach(() => {
+  ;(globalThis as Record<string, unknown>).MediaRecorder = originalMediaRecorder
+})
+
+describe('resolveRecordingFormat', () => {
+  it('prefere ogg/opus, que o WhatsApp aceita, sobre webm', () => {
+    stubMediaRecorder(['audio/ogg;codecs=opus', 'audio/webm'])
+
+    expect(resolveRecordingFormat()?.uploadMimeType).toBe('audio/ogg')
+  })
+
+  it('cai para mp4 no navegador que não grava ogg', () => {
+    stubMediaRecorder(['audio/mp4', 'audio/webm'])
+
+    const format = resolveRecordingFormat()
+    expect(format?.uploadMimeType).toBe('audio/mp4')
+    expect(format?.extension).toBe('m4a')
+  })
+
+  it('devolve indefinido quando o navegador não grava nenhum formato', () => {
+    stubMediaRecorder([])
+
+    expect(resolveRecordingFormat()).toBeUndefined()
+  })
+
+  it('devolve indefinido sem MediaRecorder no ambiente', () => {
+    ;(globalThis as Record<string, unknown>).MediaRecorder = undefined
+
+    expect(resolveRecordingFormat()).toBeUndefined()
+  })
+})
+
+describe('DEFAULT_ACCEPTED_FILE_TYPES', () => {
+  it('cobre Word, Excel e PowerPoint nos dois formatos, legado e OpenXML', () => {
+    const accepted = DEFAULT_ACCEPTED_FILE_TYPES.split(',')
+
+    expect(accepted).toContain('application/msword')
+    expect(accepted).toContain('application/vnd.openxmlformats-officedocument.wordprocessingml.document')
+    expect(accepted).toContain('application/vnd.ms-excel')
+    expect(accepted).toContain('application/vnd.openxmlformats-officedocument.spreadsheetml.sheet')
+    expect(accepted).toContain('application/vnd.ms-powerpoint')
+    expect(accepted).toContain('application/vnd.openxmlformats-officedocument.presentationml.presentation')
+  })
+
+  it('cobre texto, PDF, áudio e vídeo, e não oferece formato que o WhatsApp recusa', () => {
+    const accepted = DEFAULT_ACCEPTED_FILE_TYPES.split(',')
+
+    expect(accepted).toContain('application/pdf')
+    expect(accepted).toContain('text/plain')
+    expect(accepted).toContain('audio/ogg')
+    expect(accepted).toContain('video/mp4')
+    expect(DEFAULT_ACCEPTED_FILE_TYPES).not.toContain('.zip')
+    expect(DEFAULT_ACCEPTED_FILE_TYPES).not.toContain('.rtf')
+  })
+})

package/src/preview/conversationPreviewFailures.test.ts

@@ -0,0 +1,64 @@
+/**
+ * Guarda a classificação de falha do simulador do cliente.
+ *
+ * O defeito que motivou o arquivo: o `refresh` tratava QUALQUER erro ao ler o transcript como
+ * "conversa ainda não existe", mostrava thread vazia e não dizia nada. Com sessão ausente (401) o
+ * sintoma era o pior possível — a mensagem ia para o webhook, era aceita, e a tela ficava igual.
+ * Quem olhava concluía que o envio estava quebrado.
+ */
+
+import { describe, expect, it } from 'bun:test'
+
+import { describeLoadFailure, isNotFound } from './ConversationPreview'
+
+class HttpError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+  ) {
+    super(message)
+  }
+}
+
+describe('isNotFound', () => {
+  // Primeiro contato: a conversa não existe e transcript vazio é o estado correto, sem alarme.
+  it('reconhece 404 como conversa inexistente', () => {
+    expect(isNotFound(new HttpError('Conversa não encontrada', 404))).toBe(true)
+  })
+
+  it('não confunde 401 com conversa inexistente', () => {
+    expect(isNotFound(new HttpError('Unauthorized', 401))).toBe(false)
+  })
+
+  it('erro sem status não é tratado como inexistente', () => {
+    expect(isNotFound(new Error('Failed to fetch'))).toBe(false)
+    expect(isNotFound(undefined)).toBe(false)
+  })
+
+  // Aceita `statusCode` também: nem todo host nomeia o campo igual.
+  it('lê statusCode quando é esse o nome do campo', () => {
+    expect(isNotFound({ statusCode: 404 })).toBe(true)
+  })
+})
+
+describe('describeLoadFailure', () => {
+  it('explica que falta sessão e que a mensagem FOI entregue', () => {
+    const mensagem = describeLoadFailure(new HttpError('Unauthorized', 401))
+
+    expect(mensagem).toContain('Sem sessão')
+    // O ponto central: não deixar o operador achar que o envio falhou.
+    expect(mensagem).toContain('entregue no webhook')
+  })
+
+  it('trata 403 igual a 401', () => {
+    expect(describeLoadFailure(new HttpError('Forbidden', 403))).toContain('Sem sessão')
+  })
+
+  it('preserva a mensagem do host em falha genérica', () => {
+    expect(describeLoadFailure(new HttpError('API fora do ar', 500))).toContain('API fora do ar')
+  })
+
+  it('tem texto para erro sem mensagem', () => {
+    expect(describeLoadFailure({}).length).toBeGreaterThan(0)
+  })
+})

package/src/preview/createPreviewWebhookClient.ts

@@ -14,8 +14,10 @@
 import {
   buildInboundAudioPayload,
   buildInboundInteractivePayload,
+  buildInboundMediaPayload,
   buildInboundTextPayload,
   serializeWebhookPayload,
+  type InboundMediaType,
   type InteractiveReplyOption,
 } from '@adatechnology/meta-whatsapp-contracts/testing'
 
@@ -24,6 +26,20 @@ export type PreviewWebhookClient = {
   sendButtonReply(reply: InteractiveReplyOption): Promise<void>
   sendListReply(reply: InteractiveReplyOption): Promise<void>
   sendAudio(mediaId: string): Promise<void>
+  sendMedia(params: SendPreviewMediaParams): Promise<void>
+}
+
+export type SendPreviewMediaParams = {
+  readonly mediaType: InboundMediaType
+  /**
+   * Id que o host já usa para buscar o arquivo. Não é bytes: o webhook da Meta entrega mídia por
+   * referência, e o consumidor baixa depois — mandar base64 aqui simularia um payload que a Meta
+   * nunca produz, e o caminho testado deixaria de ser o de produção.
+   */
+  readonly mediaId: string
+  readonly mimeType?: string
+  readonly filename?: string
+  readonly caption?: string
 }
 
 export type CreatePreviewWebhookClientParams = {
@@ -57,7 +73,15 @@ export function assertPreviewEnvironment(isProduction: boolean): void {
   if (isProduction) throw new PreviewInProductionError()
 }
 
-async function signWithWebCrypto(params: { rawBody: string; appSecret: string }): Promise<string> {
+/**
+ * Assina um texto qualquer com o app secret, no mesmo formato do header da Meta.
+ *
+ * Exportada porque o preview precisa provar identidade em MAIS de um lugar: além de entregar a
+ * mensagem no webhook, ele lê o transcript de volta — e ler pela API de admin exigia uma sessão que
+ * a aba do simulador não tem. Assinar a leitura com o segredo que ele já carrega resolve sem token
+ * de admin e sem rota aberta.
+ */
+export async function signPreviewPayload(params: { rawBody: string; appSecret: string }): Promise<string> {
   const encoder = new TextEncoder()
   const key = await globalThis.crypto.subtle.importKey(
     'raw',
@@ -71,6 +95,8 @@ async function signWithWebCrypto(params: { rawBody: string; appSecret: string })
   return `sha256=${[...new Uint8Array(signature)].map((byte) => byte.toString(16).padStart(2, '0')).join('')}`
 }
 
+const signWithWebCrypto = signPreviewPayload
+
 export function createPreviewWebhookClient(params: CreatePreviewWebhookClientParams): PreviewWebhookClient {
   const sendPayload = async (payload: ReturnType<typeof buildInboundTextPayload>): Promise<void> => {
     // Serializa uma vez só: assinar um texto e enviar outro (mesmo com o conteúdo igual) derruba a
@@ -95,5 +121,6 @@ export function createPreviewWebhookClient(params: CreatePreviewWebhookClientPar
     sendButtonReply: (reply) => sendPayload(buildInboundInteractivePayload({ ...envelope, buttonReply: reply })),
     sendListReply: (reply) => sendPayload(buildInboundInteractivePayload({ ...envelope, listReply: reply })),
     sendAudio: (mediaId) => sendPayload(buildInboundAudioPayload({ ...envelope, mediaId })),
+    sendMedia: (media) => sendPayload(buildInboundMediaPayload({ ...envelope, ...media })),
   }
 }

package/src/preview/index.ts

@@ -26,15 +26,24 @@ export type { CreateMockSSEProviderParams } from './createMockSSEProvider'
 export { PREVIEW_CONVERSATIONS, PREVIEW_MESSAGES, PREVIEW_DOCUMENTS } from './previewFixtures'
 
 export { ConversationPreview } from './ConversationPreview'
-export type { ConversationPreviewProps } from './ConversationPreview'
+export { mediaTypeOf } from './ConversationPreview'
+export type { ConversationPreviewProps, PreviewUploadedMedia } from './ConversationPreview'
+
+export { AudioRecorderButton, DEFAULT_AUDIO_RECORDER_BUTTON_LABELS } from './AudioRecorderButton'
+export type { AudioRecorderButtonProps, AudioRecorderButtonLabels } from './AudioRecorderButton'
 
 export {
   createPreviewWebhookClient,
+  signPreviewPayload,
   assertPreviewEnvironment,
   PreviewInProductionError,
   PreviewWebhookRejectedError,
 } from './createPreviewWebhookClient'
-export type { PreviewWebhookClient, CreatePreviewWebhookClientParams } from './createPreviewWebhookClient'
+export type {
+  PreviewWebhookClient,
+  CreatePreviewWebhookClientParams,
+  SendPreviewMediaParams,
+} from './createPreviewWebhookClient'
 
 export { startPreviewScript, DEFAULT_PREVIEW_SCRIPT } from './startPreviewScript'
 export type { PreviewScriptStep, StartPreviewScriptParams } from './startPreviewScript'

package/src/preview/mediaTypeOf.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'bun:test'
+import { mediaTypeOf } from './ConversationPreview'
+
+describe('mediaTypeOf', () => {
+  it('deriva imagem, vídeo e áudio pelo prefixo do MIME', () => {
+    expect(mediaTypeOf('image/jpeg')).toBe('image')
+    expect(mediaTypeOf('video/mp4')).toBe('video')
+    expect(mediaTypeOf('audio/webm')).toBe('audio')
+  })
+
+  it('trata o resto como documento, inclusive MIME desconhecido', () => {
+    expect(mediaTypeOf('application/pdf')).toBe('document')
+    expect(mediaTypeOf('')).toBe('document')
+  })
+})

package/src/types.ts

@@ -20,9 +20,46 @@ export interface ConversationsFeatures {
   darkMode?: boolean
 }
 
+/**
+ * Recorte do bloco `interactive` da Meta que a UI precisa para desenhar o menu. Fica solto (e não
+ * espelhando o contrato inteiro) porque o que chega do banco é o payload cru já enviado ao
+ * WhatsApp: qualquer campo que a UI não conheça é ignorado, nunca causa erro de render.
+ */
+export interface InteractiveOption {
+  id: string
+  title: string
+  description?: string
+}
+
+export interface InteractiveSection {
+  title?: string
+  rows?: InteractiveOption[]
+}
+
+export interface InteractivePayload {
+  type?: 'button' | 'list' | string
+  header?: { text?: string }
+  body?: { text?: string }
+  footer?: { text?: string }
+  action?: {
+    /** Rótulo do botão que abre a lista — só existe em `type: 'list'`. */
+    button?: string
+    sections?: InteractiveSection[]
+    buttons?: { reply?: InteractiveOption }[]
+  }
+}
+
+/** Como o cliente respondeu a um menu: por botão ou por item de lista. */
+export type InteractiveSelection = {
+  readonly kind: 'button' | 'list'
+  readonly option: InteractiveOption
+}
+
 export interface MessagePayload {
   id: string
-  type: 'text' | 'image' | 'video' | 'audio' | 'document' | 'sticker' | 'template'
+  type: 'text' | 'image' | 'video' | 'audio' | 'document' | 'sticker' | 'template' | 'interactive'
+  /** Payload cru da mensagem. Em `type: 'interactive'`, carrega o menu que o cliente vê. */
+  payload?: InteractivePayload | null
   content?: string
   caption?: string
   mediaUrl?: string