Two separate capabilities. Images people send — a photo attached in a web chat, a web call or a WhatsApp message — need no setting; they work when the agent’s model has vision: true in GET /v1/catalog. Screen share — the agent watches the caller’s screen live — is config.vision_input.screenshare, on web voice and video calls.

​
Images people send

Web chats, web voice and video calls, and WhatsApp messages; a phone call carries no files. Check the vision flag on the llm or realtime catalog entry before picking a model — there is nothing to configure afterwards. On a chat, images go in files on POST /v1/chats/{chat_id}/messages with the caption; they become one turn:
What an agent whose model has vision: false does:
  • On a chat or WhatsApp the photo is stored all the same, and the model is shown [Image — you can't view images; ask them to describe it in text] in its place, so it asks them to describe it. Publishing warns (… cannot read images, so photos and scanned PDF pages people send are kept but not seen), and also when a primary that reads images has a fallback that does not — images stop working after a failover.
  • On a web call the browser is told this agent's model cannot read images.
Attaching from the browser: web call features.

​
WhatsApp

A photo someone sends your number is stored on their message like a web chat image, caption as its text (Twilio senders; Gupshup media is not read yet). Nothing is refused — they already sent it. A file that could not be received (over 20 MB, a fifth file in one message, or a failed download) is listed with its reason in the item’s attachments_not_kept; the message is kept and answered, and the model is told it could not be received. The rule holds wherever a thread is replayed: a later agent reading the conversation (context: transcript), a voice call with the same person included, sees earlier photos if its model has vision: true, and the placeholder if not.

​
Documents

A PDF or Word (.docx) file sent on a chat or on WhatsApp is read before the agent’s next turn, on any model. Its text reaches the model as the person’s own words, and each file is named with its id, which a tool’s File parameter takes.
  • PDF. The text of every page. A page with almost no text is a scan: the model sees it as an image when it has vision: true, and otherwise is told it is a scan it cannot view.
  • Word. Paragraphs and tables in order, headers and footers once each. Tracked deletions are left out. Pictures inside the file are counted, not read: the agent is told how many there are.
  • Not read: a legacy .doc, a password-protected PDF, one over 100 pages or 10 scanned pages, or text over 100,000 characters. The file is still stored, the item’s document says status: "unreadable" with the reason, and the agent is told why so it can ask for what it needs. Nothing is truncated.
Any other file — a voice note, a video, a spreadsheet — is stored on the item for you, and the agent is told it arrived and that it cannot open it. A voice note or video plays in the dashboard; everything else downloads.

​
Screen share

On each caller turn the model is shown only the newest frame (fitted to 1280 px), so cost per turn stays flat over a long call. Each frame is billed as image input on your LLM key, every turn. When nobody is sharing, the agent is told so and asked to request a share if it needs one. A paragraph explaining the live view is added to the prompt only on calls that can deliver frames.

​
Rules

  1. Web voice and video calls only. The same agent on a phone number never sees a screen. Enabling it on a text agent is refused.
  2. Cascade only. Enabling it with realtime set is refused: a realtime agent cannot watch a screen share.
  3. The LLM and its fallback must both have vision: true. Otherwise publish fails with an error naming the model.
  4. The caller’s page must publish the track. The dashboard test call and the SDK’s useTalqingScreenShare do; your own page must call getDisplayMedia from a click. The agent cannot start a share — write the prompt so it asks.
  5. Preemptive generation is forced off on any agent with screen share enabled, voice or video. See turn handling.

​
Screen recording

With record: true, the share is stored as a 1 fps H.264 video covering the whole call (black where nobody shared), kept and purged like the call recording. Fetch it from GET /v1/calls/{session_id}/screen-recording; the call detail has a screen_recording block whose state is none (recording off) or not_shared (on, nobody shared) when there is no file. See recording.

​
Next

Web call features

Attaching photos and starting a share from your page.

Models

Reading vision in the catalog.