@adatechnology/conversations-ui 0.1.0-rc.20 → 0.1.0-rc.21

package/src/MediaRenderer.tsx

@@ -1,10 +1,11 @@
 import { useState, type ReactNode } from 'react'
 import { AudioPlayer } from './AudioPlayer'
+import { AudioTranscription } from './AudioTranscription'
 import { FileIcon } from './FileIcon'
 import { useConversationLocales } from './ConversationLocalesProvider'
 import { formatFileSize } from './lib/format'
 import { cn } from './lib/cn'
-import type { MessagePayload } from './types'
+import type { MessagePayload, MessageTranscription } from './types'
 
 /**
  * Rótulo curto do tipo, para a linha de baixo da bolha de documento.
@@ -50,6 +51,13 @@ export interface MediaRendererProps {
   // loadUrl/loadMedia de financiamento-imobiliario-bot/apps/web/src/components/MessageBubble.tsx,
   // porém delegando o fetch ao host em vez de hardcodar `/uploads/:id/download-url`.
   onResolveUrl?: ResolveMediaUrl
+  /**
+   * Pede ao backend a transcrição do áudio desta mensagem. Ausente, o bloco de transcrição só exibe
+   * o que já veio pronto — sem oferecer um botão que o host não sabe atender.
+   *
+   * O que devolver é exibido na hora, sem esperar refetch da lista.
+   */
+  onTranscribeAudio?: () => Promise<MessageTranscription | void>
   /** Aplicado no wrapper de cada tipo de mídia — imagem, vídeo, áudio e documento. */
   className?: string
 }
@@ -77,7 +85,13 @@ function useLazyMediaUrl(message: MessagePayload, onResolveUrl?: ResolveMediaUrl
   return { url, loading, error, load }
 }
 
-export function MediaRenderer({ message, onLightbox, onResolveUrl, className }: MediaRendererProps) {
+export function MediaRenderer({
+  message,
+  onLightbox,
+  onResolveUrl,
+  onTranscribeAudio,
+  className,
+}: MediaRendererProps) {
   const { bubble } = useConversationLocales()
   const eagerSrc = resolveMediaSource(message)
   const lazy = useLazyMediaUrl(message, onResolveUrl)
@@ -149,12 +163,28 @@ export function MediaRenderer({ message, onLightbox, onResolveUrl, className }:
       )
     }
     case 'audio': {
+      /**
+       * Fica fora do ramo de carregamento de propósito: a transcrição não depende dos bytes do
+       * áudio. Ler o que o cliente disse sem baixar e tocar a nota de voz é o caminho rápido do
+       * atendimento — e é justamente o que se perderia se o bloco só aparecesse depois do play.
+       */
+      const transcriptionBlock = (
+        <AudioTranscription
+          transcription={message.transcription}
+          isMine={message.direction === 'outbound'}
+          {...(onTranscribeAudio ? { onTranscribe: onTranscribeAudio } : {})}
+        />
+      )
+
       if (!src && canLazyLoad) {
         return (
-          <LazyMediaButton
-            icon={<svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor" className="translate-x-0.5"><polygon points="5 3 19 12 5 21 5 3" /></svg>}
-            label={lazy.loading ? bubble.mediaLoading : lazy.error ? bubble.mediaRetry : bubble.listenAudio}
-          />
+          <div className="min-w-[200px]">
+            <LazyMediaButton
+              icon={<svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor" className="translate-x-0.5"><polygon points="5 3 19 12 5 21 5 3" /></svg>}
+              label={lazy.loading ? bubble.mediaLoading : lazy.error ? bubble.mediaRetry : bubble.listenAudio}
+            />
+            {transcriptionBlock}
+          </div>
         )
       }
       return (
@@ -162,6 +192,7 @@ export function MediaRenderer({ message, onLightbox, onResolveUrl, className }:
           {src ? <AudioPlayer src={src} isMine={message.direction === 'outbound'} /> : (
             <div className="h-12 bg-gray-200 rounded-lg flex items-center justify-center text-gray-400 text-xs">{bubble.mediaUnavailable}</div>
           )}
+          {transcriptionBlock}
         </div>
       )
     }

package/src/MessageBubble.tsx

@@ -1,6 +1,6 @@
 import { useMemo, useState } from 'react'
 import { Check } from 'lucide-react'
-import type { InteractiveSelection, MessagePayload } from './types'
+import type { InteractiveSelection, MessagePayload, MessageTranscription } from './types'
 import { useConversationLocales } from './ConversationLocalesProvider'
 import { StatusTicks } from './StatusTicks'
 import { MediaRenderer, type ResolveMediaUrl } from './MediaRenderer'
@@ -30,6 +30,12 @@ export interface MessageBubbleProps {
    * no histórico da inbox: o operador vê o que foi oferecido, sem responder no lugar do cliente.
    */
   onInteractiveSelect?: (selection: InteractiveSelection) => void
+  /**
+   * Pede a transcrição do áudio. Ausente, o balão usa `transcribeAudio` do `ConversationsApi` do
+   * contexto — passe apenas para sobrescrever. Sem nenhum dos dois, o bloco de transcrição só exibe
+   * o que já veio pronto do backend.
+   */
+  onTranscribeAudio?: (messageId: string) => Promise<MessageTranscription | void>
   className?: string
 }
 
@@ -51,7 +57,7 @@ const MEDIA_TYPES = new Set(['image', 'audio', 'video', 'document', 'sticker'])
 // tailwind.config do host expondo as cores `whatsapp.*` — ver Wallpaper.tsx e T6.2.
 export function MessageBubble({
   message, isMine, senderName, isFirstInGroup = true, isSelecting = false, isSelected = false, onToggleSelect,
-  onResolveMediaUrl, onInteractiveSelect, className,
+  onResolveMediaUrl, onInteractiveSelect, onTranscribeAudio, className,
 }: MessageBubbleProps) {
   const { bubble, selection } = useConversationLocales()
   const [lightboxSrc, setLightboxSrc] = useState<string | null>(null)
@@ -66,6 +72,18 @@ export function MessageBubble({
     [onResolveMediaUrl, context?.api],
   )
 
+  /**
+   * `undefined` quando nem o host nem o `ConversationsApi` sabem transcrever — é essa ausência que o
+   * bloco de transcrição consulta para decidir se desenha a afordância, mesmo padrão de
+   * `takeover`/`release`.
+   */
+  const requestTranscription = useMemo(() => {
+    const transcribe = onTranscribeAudio ?? context?.api?.transcribeAudio?.bind(context.api)
+    if (!transcribe) return undefined
+    // Devolve o resultado em vez de descartar: é o que o bloco exibe na hora, sem esperar refetch.
+    return () => transcribe(message.id)
+  }, [onTranscribeAudio, context?.api, message.id])
+
   const bubbleColor = BUBBLE_COLOR[message.sender] ?? BUBBLE_COLOR.customer
   const hasError = message.status === 'failed'
   const isMedia = MEDIA_TYPES.has(message.type)
@@ -138,7 +156,12 @@ export function MessageBubble({
         )}
 
         {isMedia ? (
-          <MediaRenderer message={message} onLightbox={setLightboxSrc} onResolveUrl={resolveMediaUrl} />
+          <MediaRenderer
+            message={message}
+            onLightbox={setLightboxSrc}
+            onResolveUrl={resolveMediaUrl}
+            {...(requestTranscription ? { onTranscribeAudio: requestTranscription } : {})}
+          />
         ) : isInteractive && message.payload ? (
           // O texto da mensagem interativa mora dentro do payload (`body.text`), e `content` guarda
           // só uma cópia achatada para busca — renderizar `content` aqui duplicaria o corpo.

package/src/MessageComposer.tsx

@@ -1,4 +1,5 @@
 import { useState, useRef, useCallback, type KeyboardEvent, type ChangeEvent, type ReactNode } from 'react'
+import { AudioRecorderButton } from './AudioRecorderButton'
 import type { ConversationsFeatures } from './types'
 import { cn } from './lib/cn'
 import { EmojiPicker } from './EmojiPicker'
@@ -219,6 +220,24 @@ export const MessageComposer = ({
     }
   }, [text, setText])
 
+  /**
+   * Microfone por padrão, sem o host precisar compor nada.
+   *
+   * Antes o gravador era só um componente exportado e um slot vazio: cada inbox tinha que lembrar de
+   * juntar os dois. Dois produtos, dois resultados — um ligou, o outro não, e a ausência não dava
+   * erro nenhum. Um composer de WhatsApp sem microfone está incompleto, então o default certo é ter.
+   *
+   * Depende de `onAttach` porque áudio gravado é um arquivo para entregar, e microfone que grava sem
+   * ter para onde mandar é pior que microfone nenhum — o operador fala e o áudio evapora. É a mesma
+   * regra de capacidade usada no resto do pacote: sem a porta, a afordância não aparece.
+   *
+   * `idleAction` continua vencendo: quem já compunha o próprio gravador (com rótulos, limite de
+   * duração ou revisão diferentes) não muda de comportamento ao atualizar.
+   */
+  const effectiveIdleAction =
+    idleAction ??
+    (onAttach ? <AudioRecorderButton onRecorded={(file) => onAttach(file)} /> : undefined)
+
   const canSend = text.trim().length > 0 || attachments.length > 0
   const remaining = maxLength ? maxLength - text.length : null
 
@@ -310,8 +329,8 @@ export const MessageComposer = ({
           </>
         )}
 
-        {!canSend && idleAction ? (
-          <div className="flex-shrink-0">{idleAction}</div>
+        {!canSend && effectiveIdleAction ? (
+          <div className="flex-shrink-0">{effectiveIdleAction}</div>
         ) : (
           <button
             onClick={sendMessage}

package/src/Wallpaper.tsx

@@ -8,7 +8,7 @@
  * A classe `cv-wallpaper` continua no elemento para quem já sobrescreve por CSS.
  */
 
-import type { CSSProperties, ReactNode } from 'react'
+import { forwardRef, type CSSProperties, type ReactNode, type UIEvent } from 'react'
 
 import { cn } from './lib/cn'
 import { useIsDarkTheme } from './useDarkMode'
@@ -45,17 +45,31 @@ export interface ConversationWallpaperProps {
   className?: string
   /** Ajusta ou substitui o fundo padrão — para produto com identidade visual própria. */
   style?: CSSProperties
+  /**
+   * Rolagem da área de mensagens. Par do `ref`: é este elemento que rola, então é aqui que
+   * `useScrollToLatestMessage` observa a posição para saber se o operador está acompanhando o fim.
+   */
+  onScroll?: (event: UIEvent<HTMLDivElement>) => void
 }
 
-export function ConversationWallpaper({ children, className, style }: ConversationWallpaperProps) {
-  const isDark = useIsDarkTheme()
-
-  return (
-    <div
-      className={cn('cv-wallpaper', className)}
-      style={{ ...(isDark ? DARK_WALLPAPER : LIGHT_WALLPAPER), ...style }}
-    >
-      {children}
-    </div>
-  )
-}
+/**
+ * `forwardRef` porque quem controla a rolagem é de fora — o hook precisa do elemento para saltar
+ * até a última mensagem. `forwardRef` e não `ref` como prop: o pacote suporta React 18, onde
+ * ref-como-prop ainda não existe.
+ */
+export const ConversationWallpaper = forwardRef<HTMLDivElement, ConversationWallpaperProps>(
+  function ConversationWallpaper({ children, className, style, onScroll }, ref) {
+    const isDark = useIsDarkTheme()
+
+    return (
+      <div
+        ref={ref}
+        onScroll={onScroll}
+        className={cn('cv-wallpaper', className)}
+        style={{ ...(isDark ? DARK_WALLPAPER : LIGHT_WALLPAPER), ...style }}
+      >
+        {children}
+      </div>
+    )
+  },
+)

package/src/conversationTranscript.test.ts

@@ -62,4 +62,61 @@ describe('buildTranscriptFilename', () => {
       `conversa-${NUMBER}-2026-07-27.txt`,
     )
   })
+
+  /**
+   * O áudio saía como `<audio>` no arquivo baixado. Um histórico onde o pedido do cliente aparece
+   * como marcador vazio é inútil justamente para o caso que motiva o download: auditoria e repasse.
+   */
+  it('escreve a transcrição do áudio no lugar do marcador de tipo', () => {
+    const texto = buildTranscriptText({
+      whatsappNumber: '5511999999999',
+      messages: [
+        {
+          id: '1',
+          type: 'audio',
+          direction: 'inbound',
+          sender: 'customer',
+          timestamp: '2026-07-31T12:00:00.000Z',
+          transcription: { status: 'done', text: 'quero dois quilos de arroz' },
+        },
+      ],
+    })
+
+    expect(texto).toContain('[áudio] quero dois quilos de arroz')
+    expect(texto).not.toContain('<audio>')
+  })
+
+  it('mantém o marcador de tipo quando o áudio não foi transcrito', () => {
+    const texto = buildTranscriptText({
+      whatsappNumber: '5511999999999',
+      messages: [
+        { id: '1', type: 'audio', direction: 'inbound', sender: 'customer', timestamp: '2026-07-31T12:00:00.000Z' },
+      ],
+    })
+
+    expect(texto).toContain('<audio>')
+  })
+
+  /**
+   * A rota de export do módulo devolve `createdAt`, não `sentAt` — quem mapeia esperando `sentAt`
+   * entrega `undefined` aqui, e o arquivo saía com "Invalid Date" em todas as linhas.
+   */
+  it('escreve "data indisponível" em vez de Invalid Date quando o horário não vem', () => {
+    const texto = buildTranscriptText({
+      whatsappNumber: '5511999999999',
+      messages: [
+        {
+          id: '1',
+          type: 'text',
+          direction: 'inbound',
+          sender: 'customer',
+          content: 'ola',
+          timestamp: undefined as unknown as string,
+        },
+      ],
+    })
+
+    expect(texto).toContain('data indisponível')
+    expect(texto).not.toContain('Invalid Date')
+  })
 })

package/src/conversationTranscript.ts

@@ -33,16 +33,41 @@ export function buildTranscriptText(params: BuildTranscriptTextParams): string {
   ]
 
   const lines = params.messages.map((message) => {
-    const stamp = new Date(message.timestamp).toLocaleString('pt-BR')
     const author = message.agentName ?? SENDER_LABEL[message.sender]
-    // Mídia sem legenda não tem texto nenhum; marcar o tipo evita uma linha vazia sem explicação.
-    const body = message.content ?? message.caption ?? `<${message.type}>`
-    return `[${stamp}] ${author}: ${body}`
+    return `[${formatStamp(message.timestamp)}] ${author}: ${bodyOf(message)}`
   })
 
   return [...header, ...lines].join('\n')
 }
 
+/**
+ * Corpo da linha no arquivo.
+ *
+ * Áudio transcrito entra com o TEXTO, não como `<audio>`. Quem baixa a conversa quer lê-la, e um
+ * histórico onde o pedido do cliente aparece como marcador vazio é inútil justamente para o caso que
+ * motiva o download: auditoria e repasse. O prefixo `[áudio]` fica na frente para a linha não passar
+ * por mensagem digitada — quem audita precisa saber que aquilo foi falado e transcrito por máquina.
+ */
+function bodyOf(message: MessagePayload): string {
+  const transcript = message.transcription?.text?.trim()
+  if (message.type === 'audio' && transcript) return `[áudio] ${transcript}`
+
+  // Mídia sem legenda não tem texto nenhum; marcar o tipo evita uma linha vazia sem explicação.
+  return message.content ?? message.caption ?? `<${message.type}>`
+}
+
+/**
+ * `Invalid Date` no arquivo é pior do que data ausente: parece dado corrompido e põe em dúvida o
+ * resto do transcript. E acontece de verdade — a rota de export do módulo devolve `createdAt`, não
+ * `sentAt`, então quem mapeia esperando `sentAt` recebe `undefined` aqui.
+ */
+function formatStamp(timestamp: string | undefined): string {
+  if (!timestamp) return 'data indisponível'
+
+  const parsed = new Date(timestamp)
+  return Number.isNaN(parsed.getTime()) ? 'data indisponível' : parsed.toLocaleString('pt-BR')
+}
+
 export function buildTranscriptFilename(whatsappNumber: string, generatedAt: Date): string {
   const stamp = generatedAt.toISOString().slice(0, 10)
   return `conversa-${whatsappNumber}-${stamp}.txt`

package/src/hooks/useScrollToLatestMessage.ts

@@ -0,0 +1,127 @@
+import { useCallback, useLayoutEffect, useRef, useState, type RefObject, type UIEvent } from 'react'
+
+/**
+ * Mantém a conversa no fim, como todo mensageiro.
+ *
+ * Abrir uma conversa no topo do histórico é errado por um motivo simples: o que interessa ao
+ * atendente é a última mensagem, e ele teria que rolar por semanas de conversa para chegar nela.
+ *
+ * Existe no pacote, e não em cada host, porque a regra tem duas sutilezas que se descobre só
+ * errando — o salto instantâneo na troca de conversa e o respeito a quem rolou para trás — e
+ * reimplementá-las em cada inbox garante que uma delas fique de fora.
+ */
+
+/**
+ * Distância do fim, em pixels, dentro da qual ainda consideramos o operador "acompanhando".
+ *
+ * Não é zero porque o navegador arredonda `scrollTop` fracionário em telas com zoom ou densidade
+ * alta: exigir o fim exato faria o painel achar que o operador rolou para trás sem ele ter tocado
+ * em nada, e a próxima mensagem não apareceria.
+ */
+const NEAR_BOTTOM_THRESHOLD_PX = 120
+
+/**
+ * Toda rolagem aqui é `'auto'` — nunca `'smooth'`.
+ *
+ * Tentamos suave para mensagem nova e medimos: em ambiente onde a rolagem suave está desligada, o
+ * `scrollTo({ behavior: 'smooth' })` **não faz nada e não avisa** — a mensagem nova simplesmente não
+ * entra na vista. E não dá para detectar isso pelo `prefers-reduced-motion`: no navegador em que
+ * reproduzimos, a media query respondia `false` e o smooth continuava sendo no-op.
+ *
+ * Trocar uma animação cosmética por garantia de que o operador vê a mensagem é barato: seguir uma
+ * mensagem nova salta a altura de uma bolha, que é quase imperceptível de qualquer forma.
+ */
+const SCROLL_BEHAVIOR: ScrollBehavior = 'auto'
+
+export type UseScrollToLatestMessageParams = {
+  /** Troca de conversa. Muda ⇒ salto instantâneo para o fim. */
+  readonly conversationId: string | undefined
+  /** Quantidade de mensagens carregadas. Cresce ⇒ acompanha o fim, se o operador estiver lá. */
+  readonly messageCount: number
+}
+
+export type UseScrollToLatestMessageResult = {
+  /** Vai no elemento que rola — tipicamente o `ConversationWallpaper`. */
+  readonly containerRef: RefObject<HTMLDivElement | null>
+  /** Ligue no `onScroll` do mesmo elemento: é o que detecta o operador lendo o histórico. */
+  readonly handleScroll: (event: UIEvent<HTMLDivElement>) => void
+  /** `true` quando o operador rolou para trás — serve a um botão "ir para a última". */
+  readonly isAwayFromBottom: boolean
+  readonly scrollToBottom: (behavior?: ScrollBehavior) => void
+}
+
+export function useScrollToLatestMessage({
+  conversationId,
+  messageCount,
+}: UseScrollToLatestMessageParams): UseScrollToLatestMessageResult {
+  const containerRef = useRef<HTMLDivElement | null>(null)
+  const [isAwayFromBottom, setIsAwayFromBottom] = useState(false)
+
+  /**
+   * Espelha `isAwayFromBottom` para o efeito de mensagens novas ler o valor atual sem depender dele.
+   *
+   * Se o efeito dependesse do estado, cada rolagem do operador o re-disparava e o puxava de volta
+   * para o fim — exatamente o que a checagem existe para evitar.
+   */
+  const isAwayFromBottomRef = useRef(false)
+
+  const scrollToBottom = useCallback((behavior: ScrollBehavior = SCROLL_BEHAVIOR) => {
+    const container = containerRef.current
+    if (!container) return
+    container.scrollTo({ top: container.scrollHeight, behavior })
+  }, [])
+
+  const handleScroll = useCallback((event: UIEvent<HTMLDivElement>) => {
+    const target = event.currentTarget
+    const distanceFromBottom = target.scrollHeight - target.scrollTop - target.clientHeight
+    const away = distanceFromBottom > NEAR_BOTTOM_THRESHOLD_PX
+
+    isAwayFromBottomRef.current = away
+    setIsAwayFromBottom((current) => (current === away ? current : away))
+  }, [])
+
+  /**
+   * Qual conversa já recebeu o salto de abertura.
+   *
+   * É o que separa "abriu a conversa" de "chegou mensagem", e não dá para usar só `conversationId`
+   * num efeito próprio: quando a conversa troca, a lista de mensagens ainda está vazia, então um
+   * salto ali rola um container sem conteúdo e não faz nada. O salto real precisa esperar a primeira
+   * leva de mensagens — e foi exatamente isso que deixou a conversa abrindo no topo.
+   */
+  const jumpedForConversationRef = useRef<string | undefined>(undefined)
+
+  useLayoutEffect(() => {
+    const isNewConversation = jumpedForConversationRef.current !== conversationId
+
+    if (isNewConversation) {
+      // Zera antes de qualquer coisa: "rolado para trás" da conversa anterior não pode bloquear o
+      // salto de abertura desta.
+      isAwayFromBottomRef.current = false
+      setIsAwayFromBottom(false)
+
+      // Sem mensagens ainda — o salto acontece quando a primeira leva chegar.
+      if (messageCount === 0) return
+
+      jumpedForConversationRef.current = conversationId
+      /**
+       * `'auto'`, sempre. Animar a rolagem por meses de histórico demora, mostra um borrão de
+       * mensagens antigas que ninguém pediu, e some por completo onde a rolagem suave está desligada
+       * (`prefers-reduced-motion`, alguns navegadores automatizados) — a conversa simplesmente
+       * abriria no topo. Abertura é salto, não animação.
+       */
+      scrollToBottom(SCROLL_BEHAVIOR)
+      return
+    }
+
+    /**
+     * Mensagem nova: acompanha, mas só se o operador já estava no fim.
+     *
+     * Puxar a rolagem de quem está lendo o histórico é pior do que não mostrar a mensagem — ele perde
+     * a posição e não sabe por quê. Quem rolou para trás recebe `isAwayFromBottom` e decide.
+     */
+    if (isAwayFromBottomRef.current) return
+    scrollToBottom(SCROLL_BEHAVIOR)
+  }, [conversationId, messageCount, scrollToBottom])
+
+  return { containerRef, handleScroll, isAwayFromBottom, scrollToBottom }
+}

package/src/index.ts

@@ -3,6 +3,7 @@ export { InteractiveMessage, DEFAULT_INTERACTIVE_MESSAGE_LABELS } from './Intera
 export { ConversationWallpaper } from './Wallpaper'
 export { ConversationLocalesProvider, useConversationLocales } from './ConversationLocalesProvider'
 export { AudioPlayer } from './AudioPlayer'
+export { AudioTranscription } from './AudioTranscription'
 export { EmojiPicker, DEFAULT_EMOJI_PICKER_LABELS } from './EmojiPicker'
 export { EMOJI_CATEGORIES, searchEmojis } from './emojiCatalog'
 export { MessageComposer, DEFAULT_MESSAGE_COMPOSER_LABELS, DEFAULT_ACCEPTED_FILE_TYPES } from './MessageComposer'
@@ -77,6 +78,7 @@ export { ConversationContextPanel, DEFAULT_CONVERSATION_CONTEXT_LABELS } from '.
 export type {
   ConversationContextPanelProps,
   ConversationContextEntry,
+  ConversationContextStatus,
   ConversationContextPanelLabels,
   ConversationContextPanelClassNames,
 } from './ConversationContextPanel'
@@ -108,6 +110,7 @@ export { ConversationsProvider, useConversations } from './providers/Conversatio
 export { WhatsAppTemplateSettingsForm } from './settings/WhatsAppTemplateSettingsForm'
 export { WhatsAppCreateTemplateForm } from './settings/WhatsAppCreateTemplateForm'
 export { WelcomeFarewellForm } from './settings/WelcomeFarewellForm'
+export { TranscriptionSettingsForm } from './settings/TranscriptionSettingsForm'
 export {
   WhatsAppTemplatesSettings,
   TEMPLATE_SETTINGS_TAB,
@@ -118,6 +121,7 @@ export { TopicsForm } from './settings/TopicsForm'
 // Camada headless (T6.9) — hooks de dados/ações independentes de qualquer tela, para o
 // produto montar sua própria UI sobre eles. Requerem <ConversationsProvider> como ancestral.
 export { useConversationMessages } from './hooks/useConversationMessages'
+export { useScrollToLatestMessage } from './hooks/useScrollToLatestMessage'
 export { useConversationList } from './hooks/useConversationList'
 export { useConversationContext } from './hooks/useConversationContext'
 export { useConversationDocuments } from './hooks/useConversationDocuments'
@@ -132,6 +136,7 @@ export { formatTimestamp, formatFileSize, formatDateTime, isSameDay } from './li
 
 export type { MessagePayload, ConversationsUIConfig, ConversationsTheme, ConversationsFeatures } from './types'
 export type { InteractivePayload, InteractiveSection, InteractiveOption, InteractiveSelection } from './types'
+export type { MessageTranscription, TranscriptionStatus, TranscriptionMode } from './types'
 export type {
   ConversationsApi,
   SSEProvider,
@@ -152,6 +157,7 @@ export type { MessageBubbleProps } from './MessageBubble'
 export type { ConversationWallpaperProps } from './Wallpaper'
 export type { ConversationLocales, ConversationLocalesProviderProps } from './ConversationLocalesProvider'
 export type { AudioPlayerProps } from './AudioPlayer'
+export type { AudioTranscriptionProps } from './AudioTranscription'
 export type { EmojiPickerProps, EmojiPickerLabels } from './EmojiPicker'
 export type { EmojiEntry, EmojiCategory } from './emojiCatalog'
 export type { InteractiveMessageProps, InteractiveMessageLabels } from './InteractiveMessage'
@@ -181,6 +187,10 @@ export type {
   WhatsAppCreateTemplateFormLabels,
 } from './settings/WhatsAppCreateTemplateForm'
 export type { WelcomeFarewellFormProps, WelcomeFarewellFormLabels } from './settings/WelcomeFarewellForm'
+export type {
+  TranscriptionSettingsFormProps,
+  TranscriptionSettingsFormLabels,
+} from './settings/TranscriptionSettingsForm'
 export type {
   WhatsAppTemplatesSettingsProps,
   WhatsAppTemplatesSettingsLabels,
@@ -191,6 +201,7 @@ export type { TopicsFormProps, TopicItem, TopicsFormLabels } from './settings/To
 export type { UseConversationMessagesResult } from './hooks/useConversationMessages'
 export type { UseConversationListParams, UseConversationListResult } from './hooks/useConversationList'
 export type { UseConversationContextResult } from './hooks/useConversationContext'
+export type { UseScrollToLatestMessageParams, UseScrollToLatestMessageResult } from './hooks/useScrollToLatestMessage'
 export type { UseConversationDocumentsParams, UseConversationDocumentsResult } from './hooks/useConversationDocuments'
 export type { ConversationRealtimeHandler } from './hooks/useConversationRealtime'
 export type { AsyncResourceState } from './hooks/useAsyncResource'

package/src/preview/ConversationPreview.tsx

@@ -40,6 +40,7 @@ export type ConversationPreviewProps = {
    * 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.
    */
+  /** Destino alternativo do áudio gravado. Sem isto, usa o do próprio `client`. */
   uploadMedia?: (file: File) => Promise<PreviewUploadedMedia>
 }
 
@@ -246,11 +247,19 @@ export function ConversationPreview({
     }
   }
 
+  /**
+   * O cliente do preview sabe subir mídia sozinho; a prop é só para quem quer outro destino.
+   *
+   * Antes isto era `uploadMedia` puro, e o microfone só aparecia no produto que lembrasse de montar
+   * o upload — de onde veio a divergência entre dois simuladores da mesma casa.
+   */
+  const uploadFile = uploadMedia ?? client.uploadMedia
+
   async function handleAttach(file: File): Promise<void> {
-    if (!uploadMedia) return
+    if (!uploadFile) return
     setFailure(undefined)
     try {
-      const uploaded = await uploadMedia(file)
+      const uploaded = await uploadFile(file)
       await client.sendMedia({
         mediaType: mediaTypeOf(uploaded.mimeType ?? file.type),
         mediaId: uploaded.mediaId,
@@ -303,7 +312,7 @@ export function ConversationPreview({
 
       <MessageComposer
         onSend={(text) => void handleSend(text)}
-        onAttach={uploadMedia ? (file) => void handleAttach(file) : undefined}
+        onAttach={uploadFile ? (file) => void handleAttach(file) : undefined}
         /* Gravando, o campo diz o que falta fazer: o botão é um interruptor e o segundo toque é
            que envia — sem esse aviso o operador grava, não vê nada acontecer e conclui que o
            microfone está quebrado. */
@@ -311,7 +320,7 @@ export function ConversationPreview({
           isRecording ? 'Gravando… toque no quadrado para ouvir' : (placeholder ?? 'Escreva como o cliente…')
         }
         idleAction={
-          uploadMedia ? (
+          uploadFile ? (
             <AudioRecorderButton
               onRecorded={(file) => void handleAttach(file)}
               onFailure={(message) => setFailure(message)}

package/src/preview/createPreviewBridgeClient.ts

@@ -16,7 +16,13 @@
  */
 
 import type { InboundMediaType, InteractiveReplyOption } from '@adatechnology/meta-whatsapp-contracts/testing'
-import type { PreviewWebhookClient, SendPreviewMediaParams } from './createPreviewWebhookClient'
+import {
+  createPreviewMediaPoster,
+  defaultMediaUploadUrl,
+  type PreviewWebhookClient,
+  type SendPreviewMediaParams,
+} from './createPreviewWebhookClient'
+import type { PreviewUploadedMedia } from './createPreviewMediaUploader'
 
 /**
  * Comando semântico entregue ao host. É deliberadamente o QUE o cliente fez, não o payload da Meta:
@@ -50,6 +56,18 @@ export type CreatePreviewBridgeClientParams = {
   readonly endpointUrl?: string
   readonly headers?: Readonly<Record<string, string>>
   readonly fetchImplementation?: typeof fetch
+  /**
+   * Rota que guarda o áudio gravado. Por padrão, `/v1/preview/media` na origem do `endpointUrl`.
+   *
+   * Aqui não há assinatura a calcular: a ponte existe justamente para não ter segredo no navegador,
+   * e a rota é protegida pela sessão do painel — os mesmos `headers` do comando valem para o upload.
+   */
+  readonly mediaUploadUrl?: string
+  /**
+   * Substitui o upload embutido. Necessário para host que só passa `sendCommand`: sem `endpointUrl`
+   * não há origem a derivar, e sem destino o gravador não é desenhado.
+   */
+  readonly uploadMedia?: (file: File) => Promise<PreviewUploadedMedia>
 }
 
 function buildFetchSender(params: CreatePreviewBridgeClientParams): SendPreviewInboundCommand {
@@ -72,9 +90,26 @@ function buildFetchSender(params: CreatePreviewBridgeClientParams): SendPreviewI
   }
 }
 
+/** Só existe quando há para onde mandar: rota explícita, ou origem herdada do `endpointUrl`. */
+function resolveBridgeUpload(
+  params: CreatePreviewBridgeClientParams,
+): ((file: File) => Promise<PreviewUploadedMedia>) | undefined {
+  if (params.uploadMedia) return params.uploadMedia
+
+  const url = params.mediaUploadUrl ?? (params.endpointUrl ? defaultMediaUploadUrl(params.endpointUrl) : undefined)
+  if (!url) return undefined
+
+  return createPreviewMediaPoster({
+    url,
+    ...(params.headers ? { headers: async () => params.headers ?? {} } : {}),
+    ...(params.fetchImplementation ? { fetchImplementation: params.fetchImplementation } : {}),
+  })
+}
+
 export function createPreviewBridgeClient(params: CreatePreviewBridgeClientParams): PreviewWebhookClient {
   const send = params.sendCommand ?? buildFetchSender(params)
   const from = params.from
+  const uploadMedia = resolveBridgeUpload(params)
 
   return {
     sendText: (text) => send({ kind: 'text', from, text }),
@@ -82,6 +117,7 @@ export function createPreviewBridgeClient(params: CreatePreviewBridgeClientParam
     sendListReply: (reply) => send({ kind: 'listReply', from, reply }),
     sendAudio: (mediaId) => send({ kind: 'audio', from, mediaId }),
     sendMedia: (media) => send({ kind: 'media', from, ...media }),
+    ...(uploadMedia ? { uploadMedia } : {}),
   }
 }