在 ElevenAgents 中处理图片和文档

一名现场主管发现工地材料短缺。他拍下照片，通过 WhatsApp 发给采购智能体，并用语音确认送货地址。智能体处理照片、识别缺少的物料并下达加急订单，全部在一次对话中完成。企业工作流程经常包含仅靠文字无法传达的上下文。解决请求所需的信息，可能是一张受损物品的照片，也可能是一份政策 PDF。直接将其交给智能体能缩短对话，加快解决速度。客户可以展示而非描述时，智能体无需让他们切换渠道，就能更快排查问题。Rohlik是欧洲最大的在线杂货平台之一，使用 6 种语言在电话、网页、App 和 WhatsApp 上部署智能体，自动解决 90% 的客户咨询。多模态输入将同样的解决率延伸至客户需要展示而非说明的场景。ElevenAgents 将文件视为一等输入，可由处理语音、WhatsApp、网页和移动端的同一智能体处理。文件会以原生消息传递给底层模型，因此一个智能体就能在同一对话线程中处理所有输入类型。 

本文将介绍多模态在平台中的含义、文件如何从客户设备进入模型上下文、各渠道支持哪些功能，以及客户再次联系时如何跨会话保留上下文。

渠道与输入 

ElevenAgents 围绕企业现有的客户触达渠道构建，包括网页和移动应用、支持平台、电话、SMS、电子邮件、WhatsApp 等。智能体配置（提示词、模型、工具、知识库和音色）只需定义一次，即可在所有渠道共享。不同渠道只有两点差异：传输层及其支持的输入类型。网页和移动应用可通过嵌入式小组件、任一 SDK 或 Agents WebSocket 连接。电话对话可通过原生 Twilio、SIP 中继或原生基于 WebSocket 的集成连接。SMS 通过原生 Twilio 集成连接。WhatsApp 可通过导入 WhatsApp Business 账户并在智能体中启用集成来连接。一个智能体可同时部署在所有这些传输方式上。

目前，网页、移动端和 WhatsApp 均支持文件输入（图片和 PDF）。输入处理由类型而非渠道驱动：同一 WhatsApp 会话中收到的照片和语音留言，会在到达模型前经过完全不同的处理流程。无论渠道或输入类型如何，所有输入都会先汇集到同一个预处理层，再作为原生上下文传递给模型，并遵循两种路径之一。

输入表示：文件支持型与内联型

无论输入类型或渠道如何，平台都会先将每项输入标准化为两种内部表示之一，再传递给模型。该分类决定输入如何编码到模型的上下文窗口中，以及集成在上游需要处理什么。

文件支持型输入

图片和 PDF 以原生文件引用而非文本摘要传递给模型。平台存储文件，为其分配一个 file_id，并将该标识符绑定到用户回合。支持视觉或文档处理的模型会在上下文窗口中接收原始文件，而非派生表示。集成要求很简单：获取上传端点返回的 file_id，并将其包含在消息负载中。如果发送消息时未附带 file_id，无论上传是否成功，模型都不会获得文件引用。文件存储仅限于该对话。因此，任何需要在会话结束后保留的内容（文件本身、提取字段或结构化输出）都必须由集成显式处理。具体方式因渠道和使用场景而异。

内联型

第二种表示是内联型，涵盖其他所有输入。语音和语音留言会被转录。输入的文字、转录后的语音、WhatsApp 位置图钉和联系人卡片，都会在模型运行前标准化为对话记录中的纯文本。位置图钉会变为坐标和可选地址；联系人会变为姓名和电话号码。这些内容不会存为文件，也不会生成文件引用，而是直接保存在对话记录中。

为何这一区分很重要

这种划分决定集成工作的重点。对话期间，内联路径无需额外处理：平台会将这些输入标准化为文本，并直接存入对话记录。文件支持型路径则有独立的集成接口。编排器不会在模型运行前将文件内容转为文本，而是将原始文件直接传入模型上下文窗口。模型基于文件结构而非派生文本表示或描述进行处理，从而保留原本可能丢失的空间关系、视觉布局和文档格式。了解这一区别后，本文接下来将介绍具体实现：如何配置智能体、文件如何经过各渠道，以及如何跨会话保留上下文。

设置多模态输入 

在网页、移动端和 WhatsApp 上启用多模态输入时，首先使用相同的智能体配置。之后，文件如何上传以及如何获取，取决于所用渠道。

启用文件输入

文件输入生效前，智能体配置中必须完成两项设置。首先，将 conversation_config.conversation.file_input.enabled 设为 True，可在创建智能体时通过 API 设置，或在控制台的 设置 > 高级设置 > 文件输入中设置。其次，智能体必须配置支持视觉和文档处理的模型。如果底层模型无法处理图片或文档块，仅设置此标记不会生效；测试前必须完成这两项设置。

SDK 和 WebSocket

网页或移动端的文件输入需要基于 SDK 构建自定义聊天客户端，或使用原始 Agents WebSocket 连接。三者流程完全相同，且顺序必须严格遵守：必须先上传文件再发送消息，因为消息负载引用的是上传后返回的标识符。

先上传文件：

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

response = client.conversational_ai.conversations.files.create(
    conversation_id="your_conversation_id",
    file=open("example_file.jpg", "rb"),
)

file_id = response.file_id  

完整请求和响应请参阅文件上传：

然后通过连接发送一条引用返回的 file_id 的消息：

{ 
	"type": "multimodal_message",
	"text": { 
		"type": "user_message", 
		"text": "What does this show?" 
	 },
	"file": { 
		"type": "file_input", 
		"file_id": "<file_id>" 
 	}
}

SDK 会将上传和引用步骤封装为一次调用，并在内部处理文件标识符。完整消息格式请参阅 multimodal_message 规范。由于应用负责上传，此时文件已在应用中。如果只需用于当前对话，上传文件并引用该标识符即可。如果需要在会话结束后保留文件，最简洁的方式是在上传时由应用存储。之后也可以通过通话后 webhook 获取，详见“跨会话保留上下文”部分。

WhatsApp

在 WhatsApp 中，应用不参与上传。客户发送图片、文档或贴纸时，文件会先进入 Meta 的基础设施。Meta 会通过 WhatsApp Business API webhook 通知 ElevenLabs，ElevenLabs 随后使用已连接的 WhatsApp Business 账户凭据，以服务器到服务器的方式下载文件、存储副本，并像网页或 SDK 上传一样将其附加到对话中。智能体会将其作为多模态输入接收，对话记录中则会记录一个 file_input 事件。

由于应用从不处理上传，因此不会直接持有文件。与网页和移动端不同，无法在上传时获取文件。文件会通过通话后 webhook 中的 file_url 进入系统，该 URL 指向 ElevenLabs 存储的副本。Meta 的媒体 URL 仅用于接收文件，绝不会对外暴露。获取机制（包括下载时限）详见“跨会话保留上下文”部分。

在 WhatsApp 中，客户会在聊天中发送文件。ElevenLabs 从 Meta 获取并存储文件，并在平台端附加 file_id。这意味着没有客户端上传步骤。不同于网页和移动端，应用无需调用 POST /v1/convai/conversations/{id}/files，也无需通过 WebSocket 发送 multimodal_message。ElevenLabs 会处理传送、存储和智能体回合。

跨会话保留上下文

ElevenAgents 会独立处理每个对话。客户发送的内容，以及智能体在对话中解决的问题，都不会自动带入下一次对话。智能体会通过通话后 webhook 将已完成对话中的全部内容交给系统，但跨对话的记忆位于 ElevenLabs 边界之外。连续性需要由你负责。

这一架构边界值得在设计时审慎考虑。多模态输入最重要的对话场景（例如客户拍摄受损物品、上传保单文件或分享位置）通常无法在一次会话中解决。发送了损坏零件照片并预约回电的客户，会期待智能体在回电时记得这张照片。若没有显式的上下文管理，智能体每次都会从零开始，客户只能重复说明。对应模式包含两部分。对话结束时，通话后 webhook 会传递对话记录、分析结果、你定义的所有结构化数据收集字段，以及会话中所有文件的 URL。后端会根据电话号码、用户 ID 或账户键等持久客户标识符，存储相关内容。客户再次联系时，应用会在会话开始时通过动态变量注入已存储的上下文，让智能体带着已有信息开始对话。对于文件支持型输入，webhook 负载中的文件 URL 指向 ElevenLabs 存储的副本，也是对话结束后唯一的获取路径。平台副本仅限于该会话，因此如果后续对话或自有系统需要该文件，必须在该期限结束前从 webhook 负载下载。具体时限取决于保留策略，详见参考文档。webhook 将状态传出，动态变量将其传回。两者之间的所有工作都由系统负责；对于客户会再次联系、升级问题或在解决过程中继续处理的使用场景，这正是实际集成工作的核心。

上下文注入取决于渠道

注入机制因渠道而异，但底层模式一致。对于电话，ElevenLabs 会在电话接通前调用服务器，让你可以根据号码查询来电者，并在智能体开口前返回姓名、订单 ID 或账户等级等动态变量。在 WhatsApp 中，每条入站消息都会触发消息前 webhook，让你能在智能体处理前，用系统中的身份和业务上下文补充消息。其他情况下，会话开启时通过 conversation_initiation_client_data传递相同字段。ElevenAgents 不会将跨渠道会话合并为同一线程。即使涉及同一位客户，WhatsApp 对话和网页对话也是独立会话。但由于 webhook 输出和动态变量注入在所有渠道中的工作方式完全相同，一个持久化层即可处理所有渠道。构建一次，即可覆盖智能体运行的每个渠道。上下文注入适用于文本形式的数据：姓名、订单 ID、摘要和结构化字段。文件则需单独采用不同的方法。

延续文件信息

文件仅限于单次对话，不会自动保留。需要延续什么，取决于下次对话需要的是文件中的信息，还是文件本身。大多数情况下，只需保留信息。智能体会在上传文件到达的回合中解读它，但不会自动将该解读写入任何持久存储。结构化输出来自通话后数据：对话记录、对话摘要以及你定义的任何数据收集结果字段。如果客户发送了一张开裂门封条的照片，一周后回来跟进索赔，智能体不需要再次查看照片，而是需要知道该索赔涉及开裂的门封条。你可以从通话后数据中提取这一信息，根据客户标识符存储，并在客户再次联系时作为动态变量注入。通常，简短摘要或几个结构化字段就足够了。

如果确实需要原始文件，用于自有记录、合规或下游系统，则通话后 webhook 是获取路径。每个上传的文件都会以带有签名文件 URL 的 file_input 事件形式出现在对话记录中。该 URL 有效期为 15 分钟，因此应在收到 webhook 时下载并存储文件，而非延后处理。如果错过该时间窗口但对话仍存在，可使用 GET conversation API 重新获取新的 URL 作为备用方案。应考虑到某些情况下（例如零保留模式）可能不存在 file_input，而不要假定每个文件支持型回合都会附带 URL。

至此便涵盖了完整生命周期：文件进入会话，模型以原生方式处理文件，结构化输出通过 webhook 传出，而持久化层决定智能体下次知道什么。

结语

同一份智能体配置无需针对每个渠道单独构建，即可在网页、移动端和 WhatsApp 上接收图片和 PDF。文件会被标准化、绑定到对应回合，并作为原生块而非文本摘要传递给模型，因此空间布局、视觉结构和文档格式都能完整传达给模型。所有渠道的跨会话上下文都遵循相同模式：通话后 webhook 将状态传出，动态变量将其传回。

如果你正在使用 ElevenLabs Agents 构建智能体，并希望它能结合语音和文本处理图片与文档，请启用多模态输入，并告诉我们你的使用体验。