Como adicionar imagens, vídeos, documentos e botões aos conteúdos da ClaudIA
:::info Em liberação gradual. Imagem já está disponível; vídeo, documento e botões estão sendo liberados projeto por
projeto. Se o rodapé do seu editor mostra apenas "Inserir imagem", a sua operação ainda não entrou na liberação — fale
com a Cloud Humans.
:::
Pré-requisitos
:::warning Disponível apenas nos projetos com ClaudIA ativa no Cloud Chat. A entrega do arquivo e dos botões depende do
canal do Cloud Chat. Se a sua operação usa outro helpdesk (Zendesk, Freshdesk, HubSpot, Intercom etc.), a mídia inserida
no conteúdo não será enviada na conversa.
:::
- ClaudIA ativa na caixa de entrada do projeto: Configurações → Caixas de entrada → sua caixa de entrada → aba
ClaudIA, com status Ativo.
- Botões clicáveis funcionam no WhatsApp e no Web Widget. Nos demais canais as opções chegam como lista de texto — a
mensagem nunca é recusada.
- Arquivos (imagem, vídeo, documento) chegam como mídia nativa nesses mesmos canais.
Passo a passo
Etapa 1 — Abrir o conteúdo no editor
Vá em ClaudIA → Conteúdos → Conteúdos customizados e abra (ou crie) um conteúdo. O rodapé do editor da resposta tem
quatro ações: Inserir imagem, Inserir vídeo, Inserir documento e Inserir botões.
Editor de conteúdo customizado com um vídeo inserido e as quatro ações no rodapé
Etapa 2 — Inserir imagem, vídeo ou documento
Há três formas de inserir:
- Botão no rodapé do editor — abre o seletor de arquivos do seu computador. Funciona para os três tipos.
- Colar com Ctrl+V (ou Cmd+V no Mac) — copie uma imagem ou tire um print e cole direto no editor, na posição do
cursor.
- Arrastar e soltar — arraste o arquivo para dentro do editor; ele entra no ponto onde você soltou.
:::info Colar e arrastar-e-soltar funcionam apenas para imagem. Vídeo e documento entram pelos botões Inserir vídeo e
Inserir documento do rodapé.
:::
O upload acontece na hora e o bloco aparece já renderizado no corpo da resposta: a imagem, o player de vídeo ou um card
com o nome do arquivo. Passando o mouse sobre o bloco você pode reordenar, editar a legenda e remover.
Editor com um documento PDF inserido, exibido como card com o nome do arquivo
Sobre a legenda e o nome do arquivo:
- Em imagem e vídeo, a legenda é o texto que acompanha o arquivo na conversa.
- Em documento, o rótulo é o nome do arquivo — mantenha a extensão (.pdf, .docx, .xlsx). É ela que faz o arquivo abrir
no aplicativo certo no celular do cliente.
Para imagem há ainda um quarto caminho, escrevendo o Markdown direto no conteúdo — veja Caminho alternativo: escrever a
imagem em Markdown no conteúdo.
Etapa 3 — Adicionar botões de resposta rápida
Clique em Inserir botões. Cada linha do grupo tem dois campos:
- Título — o que o cliente lê no botão. Até 20 caracteres; o que passar disso é cortado na entrega.
- Valor — o identificador interno da opção, que o cliente nunca vê. Não aceita espaço, parênteses nem % (esses
caracteres quebrariam a entrega, então o editor os remove e avisa).
Um grupo aceita até 3 botões. Ao chegar em "3 de 3 botões", o Adicionar botão é desabilitado.
Editor com um grupo de três botões de resposta rápida preenchido e o Adicionar botão desabilitado em 3 de 3
:::info Escreva o título como se fosse a resposta do cliente. Quando alguém clica no botão, a ClaudIA recebe o título
como se a pessoa tivesse digitado aquele texto — e responde a partir dele. "Rastrear pedido" funciona bem; "Opção 1" não
dá contexto nenhum para ela.
:::
Todo grupo de botões precisa de um texto imediatamente antes dele. É esse texto que vira a pergunta acima dos botões. Um
grupo que abre a resposta, ou que vem logo depois de uma imagem ou vídeo (porque o arquivo consome o texto anterior como
legenda), é entregue como lista de texto em vez de botões clicáveis.
Etapa 4 — Resolver os avisos antes de publicar
O editor avisa na hora quando a resposta tem algo que quebraria a entrega, e o Publicar e o Agendar ficam desabilitados
até você resolver:
- grupo de botões sem texto imediatamente antes;
- botão com título ou valor vazio;
- mais de 3 botões no mesmo grupo — contando grupos colados um no outro, que são entregues como um só;
- dois botões cujo rótulo fica igual depois do corte de 20 caracteres;
- mais de 10 blocos de mídia na mesma resposta.
Salvar rascunho continua liberado, de propósito: rascunho não é entregue ao cliente, então você não fica preso num
conteúdo que ainda está escrevendo.
Etapa 5 — Testar no Playground e publicar
Use o Playground (no menu lateral da ClaudIA) para simular a conversa e ver a resposta como o cliente veria: o texto em
balões de texto, o arquivo no balão de mídia e os botões clicáveis, na mesma ordem em que estão no conteúdo. É a forma
mais rápida de conferir se o arquivo certo está vinculado à pergunta certa antes de publicar.
Playground da ClaudIA simulando a conversa com a resposta que contém mídia
Caminho alternativo: escrever a imagem em Markdown no conteúdo
Além dos botões do rodapé, dá para colocar a imagem direto no corpo do conteúdo, escrevendo o Markdown da imagem. Vale
quando o arquivo já está hospedado em algum lugar, quando o conteúdo é montado fora do editor, ou quando as ações de
mídia ainda não apareceram no seu projeto.
O formato é :
O que muda em relação ao botão Inserir imagem:
- A URL precisa ser pública. O arquivo é baixado a partir dela na hora do envio: endereço interno, ou que exija login,
é recusado.
- Os mesmos limites valem: PNG, JPEG ou WebP, até 10 MB. GIF e SVG continuam fora.
- O editor não valida nada. Para ele isso é texto, então o aviso da Etapa 4 não aparece: se a URL estiver quebrada ou
o formato não for aceito, você só descobre na entrega — o cliente recebe a legenda e o link em vez da imagem. Teste
no Playground antes de publicar.
É o mesmo mecanismo descrito em Observações: qualquer resposta cuja saída tenha mídia em Markdown, num canal do tipo
Cloud Chat, é entregue como arquivo. Por isso o caminho serve também para fluxos controlados e respostas de agentes.
Ajustes no prompt do projeto
Para a mídia chegar como mídia, o Markdown precisa sobreviver até a resposta final. Se o prompt do projeto proíbe
Markdown ou manda reescrever links, a ClaudIA desmonta o bloco e ele vira texto. E como estes formatos são próprios da
Cloud Humans — não são Markdown padrão — o prompt precisa ensiná-los explicitamente: sem isso a ClaudIA não tem como
saber que ![video:...] ou [Título](button:...) significam algo.
A instrução abaixo resolve os dois problemas de uma vez. Ela lista os formatos e declara precedência sobre as regras que
costumam brigar com eles:
Quando o conteúdo fornecido contiver markdown de mídia ou de botão, reproduza-o exatamente como está escrito, caractere por caractere: não converta em link por extenso e não altere o texto entre colchetes. Formatos a preservar:  e  para imagem,  para vídeo,  para documento, [Título](button:valor) para botão. Esta regra tem precedência sobre a instrução de enviar links de forma completa e por extenso.
:::info Repare que é uma regra de preservação, não de geração: o Markdown vem do conteúdo, e a instrução só impede a
ClaudIA de estragá-lo. Ela existe justamente porque duas instruções comuns de prompt brigam com a mídia — a de "envie
sempre o link completo e por extenso", que transforma o Markdown em URL crua, e a de "nunca utilize Markdown", que apaga
a formatação inteira. Com a precedência declarada, você não precisa abrir exceção dentro de cada uma delas.
:::
Se você não edita o prompt do seu projeto, fale com a Cloud Humans.
Limites e formatos aceitos
| Tipo | Formatos aceitos | Tamanho máximo | | --- | --- | --- | | Imagem | PNG, JPEG, WebP | 10 MB | | Vídeo | MP4 | 16
MB | | Documento | PDF, DOC/DOCX, XLS/XLSX, PPT/PPTX, TXT, CSV | 25 MB |
GIF e SVG não são aceitos. Arquivo fora do formato ou acima do tamanho é recusado no próprio editor, com mensagem na
hora — nada é enviado pela metade.
Botões: até 3 por grupo, título de até 20 caracteres, valor de até 256 caracteres (acento conta em dobro). Só um grupo
clicável por resposta: se a resposta tiver dois grupos separados por texto, o primeiro sai clicável e o segundo como
lista de texto.
Quantidade de mídia: até 10 blocos de imagem/vídeo/documento por resposta. Além disso, a resposta inteira tem um teto de
21 mensagens na entrega — cada trecho de texto, cada arquivo e cada grupo de botões conta como uma mensagem. Uma
resposta acima desse teto é entregue como texto simples, sem os arquivos.
Tamanho da legenda: no WhatsApp, até 1024 caracteres acompanham o arquivo na mesma mensagem; acima disso o texto vai
numa mensagem separada, antes do arquivo.
Como o cliente recebe
No WhatsApp e no Web Widget, o arquivo chega como uma mensagem de verdade — imagem, vídeo com player, documento para
baixar — e não como link. Os botões chegam clicáveis, com a pergunta logo acima deles.
Exemplo de respostas com mídia rica recebidas no Web Widget:
O texto que antecede os botões viaja na mesma mensagem dos botões, então a pergunta nunca se separa das opções. O mesmo
vale para a legenda de um arquivo, quando ela cabe no limite do canal.
Quando o cliente clica em um botão, a ClaudIA recebe o título do botão como se ele tivesse digitado aquele texto, e
responde na sequência. No widget de chat a escolha vale um clique: depois de respondido, um novo clique no mesmo grupo
não gera outra resposta.
Exemplo de respostas com mídia rica recebidas no WhatsApp:
Exemplo de resposta da ClaudIA com imagem recebida no WhatsApp
Exemplos de formato markdown que são aceitos pelo Cloudchat
Os formatos a seguir são usados por baixo dos panos em conteúdos de mídica rica. É importante você saber deles, pois
pode usá-los em Fluxos Controlados e em Especialistas também:
| Recurso | Formato | | --- | --- | | Imagem |  ou  | | Vídeo |
 | | Documento |  | | Botão | [Título](button:valor) |
Imagem, vídeo e documento:
Aqui está a foto do produto:
Veja o vídeo de instalação:
Segue o manual em anexo:
Botões — precisam de uma linha de texto imediatamente antes, que vira o corpo da mensagem:
Como posso te ajudar hoje?
[Rastrear pedido](button:rastrear)
[Falar com humano](button:humano)
[Cancelar pedido](button:cancelar)
Três detalhes que fazem a diferença na prática:
- A legenda vem do texto que está antes do bloco, não do texto entre colchetes. Em , a palavra
"Etiqueta" é descartada — para ter legenda, escreva o texto na linha anterior. Duas exceções: em vídeo, se não
houver texto antes, o que está entre colchetes vira a legenda; em documento, ele vira o nome do arquivo que o
cliente recebe.
- Botão sem texto antes não sai clicável — a resposta chega como lista de texto.
- A URL precisa ser pública. O arquivo é baixado a partir dela na hora do envio: endereço interno, ou que exija login,
é recusado.
Quando a entrega degrada para texto
Nenhuma das situações abaixo recusa a mensagem: a ClaudIA sempre entrega a resposta — só sem o recurso clicável, ou sem
o arquivo.
| Situação | O que o cliente recebe | | --- | --- | | Canal sem suporte a botão (e-mail, Instagram, integrações via API)
| A pergunta seguida das opções em lista de texto | | Grupo de botões sem texto imediatamente antes | As opções em lista
de texto | | Mais de 3 botões no mesmo grupo | As opções em lista de texto | | Segundo grupo de botões na mesma resposta
| O primeiro grupo clicável; o segundo em lista de texto | | Dois botões com o mesmo rótulo (após o corte de 20
caracteres) | O grupo inteiro em lista de texto, com os títulos completos | | Dois botões com o mesmo valor | O grupo
sai clicável, sem a opção repetida | | Resposta acima de 21 mensagens | A resposta em texto simples, sem os arquivos | |
Falha no envio do arquivo | A legenda (quando existe) e o link do arquivo |
Conversa no Cloud Chat em um canal sem suporte a botão: a pergunta e as opções chegam como lista de texto
Se as ações de mídia não aparecem no editor
Se o rodapé do editor não mostra Inserir imagem / vídeo / documento / botões, verifique nesta ordem:
- A ClaudIA está pausada nesse projeto? Em Configurações → Caixas de entrada → sua caixa de entrada → aba ClaudIA, o
status precisa estar Ativo. Pausada, as ações de mídia desaparecem de propósito. Reative e recarregue a tela de
Conteúdos.
- A base de conhecimento está ligada a vários projetos? Basta um deles ter ClaudIA ativa no Cloud Chat.
- Só aparece "Inserir imagem"? Vídeo, documento e botões estão em liberação gradual — fale com a Cloud Humans. Imagem,
enquanto isso, você já consegue enviar escrevendo o Markdown no conteúdo — veja Caminho alternativo: escrever a
imagem em Markdown no conteúdo.
- Projeto antigo? Se a ClaudIA dele foi configurada pela Cloud Humans antes desta tela existir, pode não haver
registro da integração. Fale com a Cloud Humans — é rápido do nosso lado.
- Se nada disso resolver, o helpdesk desse projeto provavelmente não é o Cloud Chat.
Boas práticas
- Um assunto por conteúdo. Se o conteúdo responde a duas perguntas diferentes, prefira dois conteúdos separados, cada
um com o seu arquivo.
- Cuide da legibilidade no celular. A maior parte dos clientes abre a conversa no telefone: prefira imagens com texto
grande e evite tabelas muito largas.
- Mantenha o texto autoexplicativo. A resposta precisa fazer sentido mesmo se o cliente não abrir o arquivo — a mídia
complementa, não substitui a explicação.
- Atualize o arquivo quando a informação mudar. Preço, prazo e condições que aparecem dentro de uma imagem, de um
vídeo ou de um PDF não são atualizados automaticamente quando você edita o texto.
- Vídeo curto e direto. O cliente está numa conversa de suporte, não numa aula: prefira o trecho que resolve, não o
vídeo institucional completo.
- Títulos de botão distinguíveis nos primeiros 20 caracteres. "Rastrear meu pedido agora" e "Rastrear meu pedido
antigo" ficam idênticos depois do corte e derrubam o grupo inteiro para texto.
- Botões como atalho, não como menu. Três opções bem escolhidas convertem melhor que uma lista longa — e o limite do
canal é 3 mesmo.
Observações
- Funciona também em fluxos controlados e respostas de agentes. Qualquer mensagem cuja saída tenha mídia no formato
markdown, num canal do tipo Cloud Chat, é tratada para enviar o arquivo no modelo ideal de cada canal (WhatsApp,
e-mail, Instagram etc.).
- Com mais de um arquivo na mesma resposta, a ordem de chegada não é garantida. Cada parte da resposta é entregue ao
canal como uma mensagem independente, então elas podem chegar fora da ordem em que estão no conteúdo. Se a sequência
importa para o entendimento, não dependa dela: prefira um arquivo por resposta ou deixe a ordem explícita no texto
("na primeira imagem…", "na segunda imagem…"). Pergunta e botões são a exceção — vão sempre na mesma mensagem.
- Veja também: Boas práticas na criação e manutenção de conteúdos da ClaudIA e Como funciona e como configurar a
quebra automática de mensagens
