Como adicionar imagens, vídeos, documentos e botões aos conteúdos da ClaudIA

Pré-requisitos

• 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.

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.

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.

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.

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.

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 é ![descrição da imagem](URL da imagem):

![Etiqueta de devolução preenchida](https://exemplo.com/imagens/etiqueta-devolucao.png)

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: ![legenda](url) e ![image:legenda](url) para imagem, ![video:legenda](url) para vídeo, ![doc:nome-do-arquivo.ext](url) 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.

Se você não edita o prompt do seu projeto, fale com a Cloud Humans.

Limites e formatos aceitos

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:

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:

Imagem, vídeo e documento:

Aqui está a foto do produto:
![](https://exemplo.com/produto.png)

Veja o vídeo de instalação:
![video:instalacao](https://exemplo.com/instalacao.mp4)

Segue o manual em anexo:
![doc:manual.pdf](https://exemplo.com/manual.pdf)

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 ![Etiqueta](url), 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.

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