How to add images, videos, documents and buttons to ClaudIA's contents
:::info Gradual rollout. Image is already available; video, document and buttons are being enabled project by project.
If your editor's footer only shows "Inserir imagem" (Insert image), your operation is not part of the rollout yet — talk
to Cloud Humans.
:::
Prerequisites
:::warning Available only for projects with ClaudIA active on Cloud Chat. Delivering the file and the buttons depends on
the Cloud Chat channel. If your operation uses another helpdesk (Zendesk, Freshdesk, HubSpot, Intercom, etc.), the media
inserted into the content will not be sent in the conversation.
:::
- ClaudIA active in the project's inbox: "Configurações" (Settings) → "Caixas de entrada" (Inboxes) → your inbox →
ClaudIA tab, with status "Ativo" (Active).
- Clickable buttons work on WhatsApp and the Web Widget. On other channels the options arrive as a text list — the
message is never rejected.
- Files (image, video, document) arrive as native media on those same channels.
Step by step
Step 1 — Open the content in the editor
Go to ClaudIA → "Conteúdos" (Contents) → "Conteúdos customizados" (Custom contents) and open (or create) a content. The
answer editor's footer has four actions: "Inserir imagem" (Insert image), "Inserir vídeo" (Insert video), "Inserir
documento" (Insert document) and "Inserir botões" (Insert buttons).
Custom content editor with a video inserted and the four actions in the footer
Step 2 — Insert an image, video or document
There are three ways to insert:
- Button in the editor footer — opens your computer's file picker. Works for all three types.
- Paste with Ctrl+V (or Cmd+V on Mac) — copy an image or take a screenshot and paste it straight into the editor, at
the cursor position.
- Drag and drop — drag the file into the editor; it is inserted at the point where you dropped it.
:::info Pasting and drag-and-drop work for images only. Video and document are inserted through the Inserir vídeo and
Inserir documento buttons in the footer.
:::
The upload happens right away and the block shows up already rendered in the body of the answer: the image, the video
player or a card with the file name. Hovering over the block you can reorder, edit the caption and remove it.
Editor with a PDF document inserted, displayed as a card with the file name
About the caption and the file name:
- For image and video, the caption is the text that accompanies the file in the conversation.
- For document, the label is the file name — keep the extension (.pdf, .docx, .xlsx). That is what makes the file open
in the right app on the customer's phone.
For images there is also a fourth path, writing the Markdown directly in the content — see Alternative path: writing the
image in Markdown in the content.
Step 3 — Add quick reply buttons
Click Inserir botões (Insert buttons). Each row in the group has two fields:
- "Título" (Title) — what the customer reads on the button. Up to 20 characters; anything beyond that is cut off on
delivery.
- "Valor" (Value) — the internal identifier of the option, which the customer never sees. It does not accept spaces,
parentheses or % (these characters would break delivery, so the editor removes them and warns you).
A group accepts up to 3 buttons. When it reaches "3 de 3 botões" (3 of 3 buttons), "Adicionar botão" (Add button) is
disabled.
Editor with a group of three quick reply buttons filled in and Add button disabled at 3 of 3
:::info Write the title as if it were the customer's reply. When someone clicks the button, ClaudIA receives the title
as if the person had typed that text — and answers based on it. "Track order" works well; "Option 1" gives her no
context at all.
:::
Every button group needs a text immediately before it. That text becomes the question above the buttons. A group that
opens the answer, or that comes right after an image or video (because the file consumes the previous text as its
caption), is delivered as a text list instead of clickable buttons.
Step 4 — Resolve the warnings before publishing
The editor warns you immediately when the answer has something that would break delivery, and "Publicar" (Publish) and
"Agendar" (Schedule) stay disabled until you resolve it:
- button group without text immediately before it;
- button with an empty title or value;
- more than 3 buttons in the same group — counting groups stuck to one another, which are delivered as one;
- two buttons whose label becomes identical after the 20-character cut;
- more than 10 media blocks in the same answer.
"Salvar rascunho" (Save draft) remains available, on purpose: a draft is not delivered to the customer, so you are not
stuck on a content you are still writing.
Step 5 — Test in the Playground and publish
Use the Playground (in ClaudIA's side menu) to simulate the conversation and see the answer as the customer would see
it: the text in text bubbles, the file in the media bubble and the clickable buttons, in the same order they appear in
the content. It is the fastest way to check whether the right file is linked to the right question before publishing.
ClaudIA Playground simulating the conversation with the answer that contains media
Alternative path: writing the image in Markdown in the content
Besides the footer buttons, you can place the image directly in the body of the content by writing the image's Markdown.
This is useful when the file is already hosted somewhere, when the content is assembled outside the editor, or when the
media actions have not yet appeared in your project.
The format is :
What changes compared to the Inserir imagem button:
- The URL must be public. The file is downloaded from it at sending time: an internal address, or one that requires
login, is rejected.
- The same limits apply: PNG, JPEG or WebP, up to 10 MB. GIF and SVG are still not accepted.
- The editor validates nothing. To it this is text, so the Step 4 warning does not appear: if the URL is broken or the
format is not accepted, you only find out on delivery — the customer receives the caption and the link instead of
the image. Test in the Playground before publishing.
It is the same mechanism described in Notes: any answer whose output contains media in Markdown, on a Cloud Chat
channel, is delivered as a file. That is why this path also works for controlled flows and agent answers.
Adjustments to the project prompt
For the media to arrive as media, the Markdown needs to survive until the final answer. If the project prompt forbids
Markdown or tells ClaudIA to rewrite links, ClaudIA breaks the block apart and it becomes text. And since these formats
are specific to Cloud Humans — they are not standard Markdown — the prompt needs to teach them explicitly: without that,
ClaudIA has no way of knowing that ![video:...] or [Title](button:...) mean something.
The instruction below solves both problems at once. It lists the formats and declares precedence over the rules that
usually conflict with them:
When the provided content contains media or button markdown, reproduce it exactly as written, character by character: do not convert it into a spelled-out link and do not change the text between brackets. Formats to preserve:  and  for image,  for video,  for document, [Title](button:value) for button. This rule takes precedence over the instruction to send links in full and spelled out.
:::info Note that this is a preservation rule, not a generation rule: the Markdown comes from the content, and the
instruction only prevents ClaudIA from breaking it. It exists precisely because two common prompt instructions conflict
with media — "always send the full, spelled-out link", which turns the Markdown into a raw URL, and "never use
Markdown", which wipes out the formatting entirely. With the precedence declared, you do not need to open an exception
inside each of them.
:::
If you do not edit your project's prompt, talk to Cloud Humans.
Limits and accepted formats
| Type | Accepted formats | Maximum size | | --- | --- | --- | | Image | PNG, JPEG, WebP | 10 MB | | Video | MP4 | 16 MB
| | Document | PDF, DOC/DOCX, XLS/XLSX, PPT/PPTX, TXT, CSV | 25 MB |
GIF and SVG are not accepted. A file in the wrong format or above the size limit is rejected in the editor itself, with
an immediate message — nothing is sent halfway.
Buttons: up to 3 per group, title of up to 20 characters, value of up to 256 characters (accented characters count
double). Only one clickable group per answer: if the answer has two groups separated by text, the first one is clickable
and the second one is sent as a text list.
Amount of media: up to 10 blocks of image/video/document per answer. In addition, the whole answer has a ceiling of 21
messages on delivery — each piece of text, each file and each button group counts as one message. An answer above that
ceiling is delivered as plain text, without the files.
Caption length: on WhatsApp, up to 1024 characters accompany the file in the same message; beyond that, the text goes in
a separate message, before the file.
How the customer receives it
On WhatsApp and the Web Widget, the file arrives as a real message — image, video with player, document to download —
and not as a link. Buttons arrive clickable, with the question right above them.
Example of answers with rich media received on the Web Widget:
The text that precedes the buttons travels in the same message as the buttons, so the question is never separated from
the options. The same applies to a file's caption, when it fits within the channel's limit.
When the customer clicks a button, ClaudIA receives the button's title as if they had typed that text, and answers next.
In the chat widget the choice is one click: once answered, a new click on the same group does not generate another
answer.
Example of answers with rich media received on WhatsApp:
Example of a ClaudIA answer with an image received on WhatsApp
Examples of markdown formats accepted by Cloudchat
The following formats are used under the hood in rich media contents. It is important that you know them, because you
can also use them in "Fluxos Controlados" (Controlled Flows) and in "Especialistas" (Specialists):
| Feature | Format | | --- | --- | | Image |  or  | | Video | 
| | Document |  | | Button | [Title](button:value) |
Image, video and document:
Here is the product photo:
Watch the installation video:
Please find the manual attached:
Buttons — they need a line of text immediately before them, which becomes the body of the message:
How can I help you today?
[Track order](button:rastrear)
[Talk to a human](button:humano)
[Cancel order](button:cancelar)
Three details that make a difference in practice:
- The caption comes from the text before the block, not from the text between brackets. In , the word
"Label" is discarded — to have a caption, write the text on the previous line. Two exceptions: for video, if there
is no text before it, what is between brackets becomes the caption; for document, it becomes the file name the
customer receives.
- A button without text before it is not clickable — the answer arrives as a text list.
- The URL must be public. The file is downloaded from it at sending time: an internal address, or one that requires
login, is rejected.
When delivery degrades to text
None of the situations below rejects the message: ClaudIA always delivers the answer — just without the clickable
feature, or without the file.
| Situation | What the customer receives | | --- | --- | | Channel without button support (email, Instagram, API
integrations) | The question followed by the options as a text list | | Button group without text immediately before it
| The options as a text list | | More than 3 buttons in the same group | The options as a text list | | Second button
group in the same answer | The first group clickable; the second as a text list | | Two buttons with the same label
(after the 20-character cut) | The entire group as a text list, with the full titles | | Two buttons with the same value
| The group is clickable, without the repeated option | | Answer above 21 messages | The answer in plain text, without
the files | | File sending failure | The caption (when there is one) and the file link |
Conversation in Cloud Chat on a channel without button support: the question and the options arrive as a text list
If the media actions do not appear in the editor
If the editor footer does not show Inserir imagem / vídeo / documento / botões (Insert image / video / document /
buttons), check in this order:
- Is ClaudIA paused in this project? In Configurações (Settings) → Caixas de entrada (Inboxes) → your inbox → ClaudIA
tab, the status must be Ativo (Active). When paused, the media actions disappear on purpose. Reactivate it and
reload the Conteúdos (Contents) screen.
- Is the knowledge base linked to several projects? It is enough for one of them to have ClaudIA active on Cloud Chat.
- Only "Inserir imagem" appears? Video, document and buttons are in gradual rollout — talk to Cloud Humans. Meanwhile,
you can already send images by writing the Markdown in the content — see Alternative path: writing the image in
Markdown in the content.
- Older project? If its ClaudIA was set up by Cloud Humans before this screen existed, there may be no record of the
integration. Talk to Cloud Humans — it is quick on our side.
- If none of this solves it, this project's helpdesk is probably not Cloud Chat.
Best practices
- One topic per content. If the content answers two different questions, prefer two separate contents, each with its
own file.
- Take care of readability on mobile. Most customers open the conversation on their phone: prefer images with large
text and avoid very wide tables.
- Keep the text self-explanatory. The answer needs to make sense even if the customer does not open the file — the
media complements the explanation, it does not replace it.
- Update the file when the information changes. Prices, deadlines and conditions shown inside an image, a video or a
PDF are not updated automatically when you edit the text.
- Short, to-the-point videos. The customer is in a support conversation, not in a class: prefer the excerpt that
solves the issue, not the full institutional video.
- Button titles distinguishable within the first 20 characters. "Check my order status now" and "Check my order status
later" become identical after the cut and drop the entire group to text.
- Buttons as a shortcut, not as a menu. Three well-chosen options convert better than a long list — and the channel's
limit is 3 anyway.
Notes
- It also works in controlled flows and agent answers. Any message whose output contains media in markdown format, on
a Cloud Chat channel, is processed to send the file in the ideal format for each channel (WhatsApp, email,
Instagram, etc.).
- With more than one file in the same answer, the order of arrival is not guaranteed. Each part of the answer is
delivered to the channel as an independent message, so they may arrive out of the order in which they appear in the
content. If the sequence matters for understanding, do not rely on it: prefer one file per answer or make the order
explicit in the text ("in the first image…", "in the second image…"). Question and buttons are the exception — they
always go in the same message.
- See also: Best practices for creating and maintaining ClaudIA's contents and How automatic message splitting works
and how to configure it
