# Message

Uma mensagem de conversa com um assistente: quem fala, o conteúdo, as ações de
copiar e tentar de novo, e o indicador de que o texto ainda está chegando. Com
`variant="chat"`, é também a mensagem de uma conversa entre pessoas, com balão
dos dois lados. Vive em `@rivocode/ui/ai`.

```tsx
import { Message } from '@rivocode/ui/ai'

<Message role="user">Quanto gastei em agosto?</Message>
<Message role="assistant" copyValue={answer} onRetry={retry}>
  {answer}
</Message>
```

## O papel decide o desenho

- `user` é o balão à direita, no fundo do acento.
- `assistant` é o texto corrido à esquerda, sem balão: é onde mora a resposta
  longa, a lista e a tabela, e balão aperta tudo isso.
- `system` é a linha discreta no centro, para "Conversa iniciada às 14h02" e
  para o aviso de que o contexto mudou.

Cada mensagem sai como um `article` com o nome de quem fala ("Você",
"Assistente", "Sistema"), e o leitor de tela anda de uma para a outra por aí.
`author` troca o nome, para o assistente que tem nome próprio.

`avatar` recebe o `Avatar` da casa e fica do lado de quem fala. Em `system` ele
não sai.

## Chat entre pessoas

`variant="chat"` é a conversa entre duas pessoas: o atendimento com o cliente,
o recado entre a loja e o entregador. A resposta longa de modelo, que pede
texto corrido, não existe aqui, e as duas falas viram balão.

- `user` é quem está lendo a tela: balão à direita, no acento tênue, como no
  modo do assistente.
- `assistant` é a outra pessoa: balão à esquerda, no neutro `surface-hover`,
  com a ponta do lado dela.
- `system` continua a linha do centro, para "Hoje" e "Marina entrou na
  conversa".

O lado continua saindo do `role`, e não de uma prop nova: a conversa tem dois
lados e uma linha de aviso, que são exatamente os três papéis, e uma segunda
prop para dizer "é minha" abriria a combinação sem sentido de `role="system"`
do lado direito. O nome é o que muda: sem `author`, a outra pessoa sai
"Contato" para o leitor de tela, e não "Assistente". Passe o nome dela.

```tsx
<Message variant="chat" role="assistant" author="Marina Costa" avatar={<Avatar size="sm" fallback="MC" />}>
  O pedido 4821 já saiu para entrega?
</Message>
<Message variant="chat" role="user">
  Saiu agora há pouco. Chega até as 18h.
</Message>
```

`streaming` sem conteúdo vira o "digitando" da outra pessoa, e `error` com
`onRetry` é a mensagem que não foi enviada. O link escrito no balão da outra
pessoa usa `text-accent-text`, e o par está medido nos dois temas.

**A hora e o status moram no balão.** `time` é a hora já escrita ("14:32"),
que a tela formata no fuso e no idioma dela, e `status` é onde a mensagem está
no caminho: `sending` (o relógio), `sent` (um tique), `delivered` (dois),
`read` (dois no tom de acento) e `failed` (o alerta no tom de perigo). Os dois
saem juntos no canto de baixo do balão, em letra pequena. A cor nunca é o único
sinal: o leitor de tela ouve a palavra ("Enviada", "Lida"), que se troca em
`labels` pela mesma chave do status.

```tsx
<Message variant="chat" role="user" time="14:32" status="read">
  Saiu agora há pouco. Chega até as 18h.
</Message>
<Message variant="chat" role="assistant" author="Marina Costa" time="14:35">
  Obrigada!
</Message>
```

O status é da mensagem de quem está lendo; a da outra pessoa leva só a hora.
Com `failed`, a linha de falha aparece embaixo do balão, à vista: o `error`
quando vem, com o motivo ("Número sem WhatsApp"), ou "Não enviada" sem ele. O
`onRetry` põe o tentar de novo ao lado.

```tsx
<Message variant="chat" role="user" time="14:36" status="failed" error="Número sem WhatsApp" onRetry={reenviar}>
  O boleto vence amanhã.
</Message>
```

**Mensagem de voz.** Com um `AudioPlayer variant="bubble"` como filho direto,
a hora e os tiques entram na linha da duração do player, à direita, como no
WhatsApp, e o balão não desenha a linha própria embaixo:

```tsx
<Message variant="chat" role="user" time="14:32" status="read">
  <AudioPlayer variant="bubble" src={voz.url} peaks={voz.peaks} duration={voz.segundos} />
</Message>
```

O `Message` passa a hora pelo `meta` do player. O que ele olha é a prop
`variant="bubble"` no filho direto, e não o tipo: um componente seu que
embrulha o `AudioPlayer` (para buscar os picos, por exemplo) recebe o `meta`
se também declarar `variant="bubble"` e repassar o `meta` ao player. Sem essa
prop no filho direto, a linha da hora volta para baixo do balão.

**Foto e vídeo.** Com uma `MessageMedia` como filho direto, o balão aperta a
borda em volta da mídia e a hora com os tiques aparece uma vez só: por cima da
mídia, no canto de baixo, numa pílula escura que lê sobre foto clara ou
escura, quando não há legenda; e depois da legenda, quando ela vem no
`caption`. Nunca nos dois lugares.

**Documento e localização.** A `MessageMedia` com `kind="document"` ou
`kind="location"` é um cartão, e não uma foto: a hora vai embaixo dele, na cor
de sempre, ou depois da legenda. No documento, a legenda igual ao nome do
arquivo, que o WhatsApp manda quando não há legenda, não aparece.

A `MessageMedia` é reconhecida pela PEÇA, e não por prop: ela tem de ser a
filha direta, sem componente seu no meio. Embrulhada, ela perde a hora por
cima e a borda apertada, e o balão volta a desenhar a linha da hora embaixo.
E tem de ser a filha **única**: um `{cond ? <X /> : null}` ao lado, mesmo
quando dá `null`, já faz dos filhos uma lista, e a hora some da mídia. O mesmo
vale para o `AudioPlayer variant="bubble"`.

```tsx
<Message variant="chat" role="assistant" author="Marina Costa" time="14:32">
  <MessageMedia kind="video" src={video.url} poster={video.capa} duration={12} onOpen={abrirVideo} />
</Message>
<Message variant="chat" role="user" time="14:33" status="read">
  <MessageMedia kind="image" src={foto.url} width={1600} height={1000} caption="Fachada nova da loja" onOpen={abrirFoto} />
</Message>
```

O nome de quem fala não aparece escrito no balão: num fio de duas pessoas o
lado já diz. Conversa de grupo, em que o nome precisa estar na tela, é
`Timeline`.

## Responder

`replyTo` é a mensagem que esta responde: a citação sai no topo do balão, com
a barra de acento à esquerda, o autor em acento e o trecho em `fg-muted`,
cortado em duas linhas. O leitor de tela ouve "Resposta a Marina Costa: …"
antes do texto.

Tocar na citação leva até a original e a destaca por um instante. Dentro de
uma `Conversation`, isso é da peça: dê a cada mensagem o `messageId`, e a
citação cujo `replyTo.id` aponta para ele vira botão sozinha. O toque rola a
conversa até a original, centrada, põe o foco nela e a pinta em `selected` por
um segundo e meio; com movimento reduzido, a rolagem é seca e a cor some sem
transição. O leitor de tela não ouve aviso novo: ouve a mensagem em que o foco
caiu.

`onReplyPress` continua, e é chamado com o `id` além do pulo: é para o que a
peça não alcança, como a original que ainda não foi carregada. Carregue o
histórico e chame o `scrollToMessage(id)` do `actionsRef` da `Conversation`,
que devolve `false` enquanto a original não estiver na árvore. Fora de uma
`Conversation`, só o `onReplyPress` torna a citação botão.

`onReply` liga a ação "Responder", ao lado do copiar e do tentar de novo. A
peça não guarda a resposta: quem chamou põe o `replyTo` no `PromptInput`, que
mostra a citação em cima do campo com o xis para desistir, e limpa ao enviar.

```tsx
const [replying, setReplying] = useState<MessageReply>()

<Conversation className="h-[32rem]">
  <Message variant="chat" role="assistant" author="Marina Costa" messageId="m-41">
    Consegue mandar a foto da fachada?
  </Message>
  <Message
    variant="chat"
    role="user"
    messageId="m-42"
    time="14:31"
    status="read"
    replyTo={{ author: 'Marina Costa', text: 'Consegue mandar a foto da fachada?', id: 'm-41' }}
  >
    Mando já, estou na frente da loja.
  </Message>
</Conversation>
<Message
  variant="chat"
  role="assistant"
  author="Marina Costa"
  time="14:32"
  onReply={() => setReplying({ author: 'Marina Costa', text: 'Fachada pronta!', id: 'm-43' })}
>
  Fachada pronta!
</Message>
<PromptInput replyTo={replying} onCancelReply={() => setReplying(undefined)} onSubmit={enviar} />
```

## O menu do botão direito

`contextMenu` abre um menu com as ações que a mensagem já mostra, e só as
ligadas: "Copiar" com o `copyValue`, "Tentar de novo" com o `onRetry` e
"Responder" com o `onReply` e "Baixar" com o `download` da `MessageMedia`
filha direta, com os mesmos `labels` dos botões. Abre no botão
direito, no toque longo da tela de toque e, no teclado, no Shift+F10 ou na
tecla de menu com o foco num dos botões da mensagem. Os botões continuam: o
menu acelera o que já está neles, e nunca é o único caminho. As `actions`
próprias não entram nele. Sem nenhuma dessas ações, e enquanto há
`streaming`, o botão direito é o do navegador.

```tsx
<Message variant="chat" role="assistant" author="Marina Costa" copyValue={texto} onReply={responder} contextMenu>
  {texto}
</Message>
```

**Baixar a mídia** é o `download` da `MessageMedia`, e não uma prop da
`Message`: quem sabe o endereço e o cabeçalho é a mídia. Com ele, a `Message`
põe o botão Baixar nas ações, ao lado do responder, e o item no menu. No
`kind="document"` o botão é o do próprio cartão, e não se repete nas ações. Enquanto
busca, o botão gira e diz "Baixando…"; a falha sai embaixo do balão, no tom de
perigo, e é anunciada, e o fim da promessa sai no mesmo lugar, em texto
discreto ("Arquivo salvo."). Os textos são `labels.download`,
`labels.downloading`, `labels.downloaded` e `labels.downloadError`, que aceita
também a função do erro, para dizer o motivo; `downloaded: ""` cala o sucesso.

```tsx
<Message variant="chat" role="user" time="14:33" onReply={responder} contextMenu>
  <MessageMedia kind="video" src={video.url} poster={video.capa} duration={12} onOpen={abrir} download />
</Message>
```

## O conteúdo é seu

`children` é o que aparece, e a peça não interpreta nada: quem usa renderiza o
markdown com a biblioteca que já tem, e passa o resultado. Isso é de propósito.
Markdown de modelo traz tabela, código e link, e cada produto decide o que
aceita.

```tsx
<Message role="assistant" copyValue={raw}>
  {renderMarkdown(raw)}
</Message>
```

## Chegando

`streaming` diz que o texto ainda está chegando. Três coisas mudam:

- os três pontos aparecem depois do texto (ou sozinhos, antes do primeiro
  pedaço), e param de pulsar quando o sistema pede menos movimento;
- a mensagem anuncia `aria-busy`, e o leitor de tela espera ela terminar em
  vez de ler cada pedaço que chega;
- as ações somem: copiar meia resposta e pedir outra enquanto a primeira nem
  terminou são os dois toques que ninguém quer.

## Ações e erro

`copyValue` liga o botão de copiar, com o texto que vai para a área de
transferência. Passe o texto cru (o markdown, e não o que ele desenha), porque
é isso que a pessoa cola em outro lugar. `onRetry` liga o "Tentar de novo".
`actions` recebe os botões próprios, depois dos dois: gostei, não gostei,
salvar.

`error` é a resposta que falhou. A frase sai embaixo do conteúdo, com ícone e
no tom de perigo, e as ações aparecem mesmo sem conteúdo nenhum.

```tsx
<Message
  role="assistant"
  error="A resposta foi interrompida. Tente de novo."
  onRetry={retry}
>
  {partial}
</Message>
```

## Partes

`classNames` alcança `avatar`, `bubble` (o balão do `user`, e a coluna do
`assistant`; no `chat`, o balão dos dois), `reply` (a citação do `replyTo`),
`content`, `indicator`, `error`, `actions` e `meta` (a linha da hora e do
status).

## Quando não usar

- **Conteúdo que não é turno de conversa** é `Card`. Um resumo gerado por IA
  numa tela de painel é um cartão com um `AILabel`, e não uma mensagem: não há
  quem pergunte nem a quem responder.
- **Linha de lista com ícone, texto e ação** é `Item`. Um histórico de
  conversas antigas, com o título de cada uma, é lista de `Item`; a `Message` é
  o que aparece depois que a pessoa abre uma delas.
- **Comentário de grupo**, com data e autor, é `Timeline`. A `Message`, mesmo
  no `chat`, pressupõe dois lados alternando, e o alinhamento por papel perde o
  sentido num fio de cinco pessoas.

## No React Native

Traduz, no caminho próprio `@rivocode/ui-native/ai`, com o mesmo `role`, o mesmo alinhamento, o mesmo `variant`, `author`, `avatar`, `streaming`, `onRetry`, `actions`, `error`, `time` e `status`. A marca do status é o mesmo ícone do lucide do web: o `Clock` em `sending`, o `Check` em `sent`, o `CheckCheck` em `delivered` e em `read`, este no tom de acento, e o `CircleAlert` em `failed`. O leitor ouve a hora e a palavra juntas ("14:32, Lida"). Em `streaming` a mensagem anuncia `busy` e esconde as ações, como no web, e no `variant="chat"` os dois balões saem com as mesmas cores e a outra pessoa sem `author` se chama "Contato".

**Copiar é seu.** O web copia sozinho pelo `copyValue`; aqui a peça tem `onCopy`, porque a área de transferência do celular é o `expo-clipboard`, peer que mora em `@rivocode/ui-native/clipboard` e que o caminho de IA não pode cobrar de quem não copia nada. Texto solto em `children` vira `Text` no corpo da casa; nó entra como veio, para quem renderiza markdown.

**Áudio no balão, como no web.** Com um `AudioPlayer variant="bubble"` como filho direto, a hora e o status entram no `meta` do player, ao lado da duração, e o balão não desenha a linha própria. Com uma `MessageMedia` como filho direto, a hora vai por cima da foto e do vídeo sem legenda, embaixo do cartão do documento e da localização, e depois da legenda com ela, uma vez só.

**Responder é arrastar.** `replyTo` e `onReplyPress` desenham a citação no topo do balão como no web. O `onReply`, que no web é a ação "Responder" ao lado do copiar, aqui é o gesto dos mensageiros: arrastar o balão para a direita, pelo `PanResponder` do core. O balão segue o dedo, resiste depois de 56 pt, e soltando além disso a peça chama o `onReply`; ele volta com mola, e sem mola quando o sistema pede para reduzir movimento. O gesto só começa com o dedo na horizontal, para não brigar com a rolagem da conversa. Quem não arrasta tem a ação de acessibilidade "Responder" no texto e na linha da hora (`labels.reply` troca o nome).

**A citação leva até a original sem `messageId`.** Dentro da `Conversation`, a identidade de cada mensagem já é a chave do `keyExtractor`: a citação cujo `replyTo.id` é a chave de um item vira botão sozinha, e o toque rola a lista até ele. A citação que aponta para fora de `items` só é botão com `onReplyPress`.

**Sem menu do toque longo.** O `contextMenu` do web acelera o que já está nos botões; aqui o arrastar e a ação de acessibilidade "Responder" cobrem o responder, e copiar e tentar de novo continuam nos botões. Toque longo no balão disputaria o gesto com a seleção de texto e com o arrastar.

As partes vestem pelo mesmo `classNames` do web: `avatar`, `bubble`, `reply`, `content`, `indicator`, `error` e `actions`. `content` veste o `Text` que embrulha o texto solto; nó que chega pronto entra como veio.

**No iOS e no Android.** No Android 13 ou mais novo, o próprio sistema mostra uma confirmação ao copiar, além do aviso “Copiado” da peça. O aviso da peça fica nos dois para o iOS, que não mostra nada.

## Importação

```tsx
import { Message } from '@rivocode/ui/ai'
```

## Exemplos

### Os três papéis

```tsx
import { Avatar } from '@rivocode/ui'
import { Conversation, Message } from '@rivocode/ui/ai'

const ANSWER =
  'Em agosto você gastou R$ 4.820,00, 12% a menos que em julho. Mercado e transporte somam metade do total, e a fatura do cartão vence na sexta.'

export function Roles() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-6">
      <Message role="system">Conversa iniciada às 14h02.</Message>
      <Message role="user">Quanto gastei em agosto?</Message>
      <Message
        role="assistant"
        avatar={<Avatar size="sm" fallback="R" />}
        copyValue={ANSWER}
        onRetry={() => {}}
      >
        {ANSWER}
      </Message>
    </div>
  )
}
```

### Chegando

```tsx
import { Avatar } from '@rivocode/ui'
import { Conversation, Message } from '@rivocode/ui/ai'

export function Streaming() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-6">
      <Message role="assistant" avatar={<Avatar size="sm" fallback="R" />} streaming>
        Em agosto você gastou R$ 4.820,00
      </Message>
      <Message role="assistant" avatar={<Avatar size="sm" fallback="R" />} streaming />
    </div>
  )
}
```

### Com erro

```tsx
import { Avatar } from '@rivocode/ui'
import { Conversation, Message } from '@rivocode/ui/ai'

export function WithError() {
  return (
    <div className="w-full max-w-xl">
      <Message
        role="assistant"
        avatar={<Avatar size="sm" fallback="R" />}
        error="A resposta foi interrompida. Tente de novo."
        onRetry={() => {}}
      >
        Em agosto você gastou
      </Message>
    </div>
  )
}
```

### Chat entre pessoas

```tsx
import { Avatar } from '@rivocode/ui'
import { Conversation, Message } from '@rivocode/ui/ai'

export function PeopleChat() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      <Message variant="chat" role="system">
        Hoje
      </Message>
      <Message
        variant="chat"
        role="assistant"
        author="Marina Costa"
        avatar={<Avatar size="sm" fallback="MC" />}
      >
        Oi! O pedido 4821 já saiu para entrega?
      </Message>
      <Message variant="chat" role="user">
        Saiu agora há pouco. Chega até as 18h.
      </Message>
      <Message
        variant="chat"
        role="assistant"
        author="Marina Costa"
        avatar={<Avatar size="sm" fallback="MC" />}
        streaming
      />
    </div>
  )
}
```

### Respondendo uma mensagem

```tsx
import { Avatar } from '@rivocode/ui'
import { Conversation, Message } from '@rivocode/ui/ai'

export function Reply() {
  return (
    <Conversation className="w-full max-w-xl" classNames={{ content: 'gap-3' }}>
      <Message
        variant="chat"
        role="assistant"
        author="Marina Costa"
        time="14:30"
        messageId="m-41"
        copyValue="Consegue mandar a foto da fachada?"
        onReply={() => {}}
        contextMenu
      >
        Consegue mandar a foto da fachada?
      </Message>
      <Message
        variant="chat"
        role="user"
        time="14:31"
        status="read"
        messageId="m-42"
        replyTo={{ author: 'Marina Costa', text: 'Consegue mandar a foto da fachada?', id: 'm-41' }}
      >
        Mando já, estou na frente da loja.
      </Message>
    </Conversation>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `role` | `MessageRole` | sim |  | - | Quem fala. |
| `actions` | `ReactNode` |  |  | - | Os botoes proprios, depois do copiar e do tentar de novo: gostei, nao gostei. |
| `author` | `string` |  |  | - | O nome de quem fala, para o leitor de tela, que ouve cada mensagem como um artigo com esse nome. |
| `avatar` | `ReactNode` |  |  | - | O `Avatar` ao lado da mensagem. |
| `classNames` | `Partial<Record<"actions" \| "avatar" \| "bubble" \| "content" \| "error" \| "indicator" \| "meta" \| "reply", string>>` |  |  | - |  |
| `contextMenu` | `boolean` |  | `false` | - | Abre, no botao direito, no toque longo e na tecla de menu, um menu com as mesmas acoes ligadas: copiar, tentar de novo, responder e baixar (o `download` da `MessageMedia` filha direta). |
| `copyValue` | `string` |  |  | - | Liga o botao de copiar, com este texto. |
| `error` | `ReactNode` |  |  | - | A resposta falhou: a frase sai embaixo do conteudo, com icone e no tom de perigo, e as acoes aparecem mesmo sem conteudo. |
| `labels` | `({ copy?: string \| undefined; copied?: string \| undefined; retry?: string \| undefined; reply?: string \| undefined; download?: string \| undefined; downloading?: string \| undefined; downloadError?: DownloadErrorLabel \| undefined; downloaded?: string \| undefined; thinking?: string \| undefined; quote?: ((author: string,...` |  |  | - | Os textos da peca: `copy`, `copied`, `retry`, `reply` e `download` sao os nomes dos botoes de acao ("Copiar", "Copiado", "Tentar de novo", "Responder" e "Baixar"), `downloading` o do Baixar enquanto busca ("Baixando…"), `downloadError` a linha que diz que o download falhou (um texto, ou uma funcao do erro que diz o motivo), `downloaded` a que diz que ele acabou ("Arquivo salvo.", e `""` a cala), `thinking` a frase que brilha em `streaming` antes de o texto chegar ("Pensando…"), e `quote` o que o leitor de tela ouve da citacao. |
| `messageId` | `string` |  |  | - | A identidade da mensagem na conversa: o `id` que as respostas a ela levam no `replyTo`. |
| `onReply` | `(() => void)` |  |  | - | Liga a acao "Responder", ao lado do copiar e do tentar de novo. |
| `onReplyPress` | `((id: string \| undefined) => void)` |  |  | - | Torna a citacao um botao, chamado com o `id` do `replyTo`. |
| `onRetry` | `(() => void)` |  |  | - | Liga o botao de tentar de novo, que pede outra resposta. |
| `replyTo` | `MessageReply` |  |  | - | A mensagem que esta responde: a citacao no topo do balao, com a barra de acento, o autor e o trecho cortado em duas linhas. |
| `status` | `MessageStatus` |  |  | - | Onde a mensagem esta no caminho, ao lado da `time`: `sending` o relogio, `sent` um tique, `delivered` dois, `read` dois no tom de acento, e `failed` o alerta no tom de perigo. |
| `streaming` | `boolean` |  | `false` | - | O texto ainda esta chegando: a mensagem anuncia `aria-busy`, para o leitor de tela ler quando ela terminar e nao a cada pedaco, mostra o indicador e esconde as acoes. |
| `time` | `string` |  |  | - | A hora da mensagem, ja escrita ("14:32"), no canto de baixo do balao, em letra pequena. |
| `variant` | `"assistant" \| "chat"` |  | `"assistant"` | - | O desenho da conversa. |

Além dessas: repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Ver também

- [AILabel](/componentes/ai-label.md)
- [Conversation](/componentes/conversation.md)
- [MessageMedia](/componentes/message-media.md)
- [PromptInput](/componentes/prompt-input.md)
- [ShimmerText](/componentes/shimmer-text.md)
- [ToolCall](/componentes/tool-call.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
