Traitement des images et documents dans ElevenAgents

Un chef de chantier remarque un manque de matériel sur un site. Il prend une photo, l’envoie à l’agent d’approvisionnement sur WhatsApp, puis confirme l’adresse de livraison à l’oral. L’agent traite la photo, identifie ce qui manque et passe une commande urgente, le tout dans la même conversation. Les workflows en entreprise transportent souvent un contexte que les mots seuls ne suffisent pas à transmettre. Pour résoudre une demande, il peut être nécessaire d’envoyer une photo d’un objet endommagé ou un PDF d’une politique. Transmettre ces fichiers directement à l’agent raccourcit la conversation et accélère la résolution. Quand un client peut montrer au lieu de décrire, l’agent trouve plus vite la solution sans lui demander de changer de canal.Rohlik, l’une des plus grandes plateformes de courses en ligne en Europe, utilise son agent sur téléphone, web, application et WhatsApp en six langues et résout automatiquement 90% des demandes clients. L’entrée multimodale permet d’atteindre ce même taux de résolution même quand le client doit montrer au lieu d’expliquer. ElevenAgents traite les fichiers comme des entrées à part entière, sur le même agent qui gère déjà la voix, WhatsApp, le web et le mobile. Les fichiers arrivent au modèle sous forme de messages natifs, ce qui permet à un seul agent de gérer tous les types d’entrées dans un même fil de discussion.

Cet article explique ce que signifie la multimodalité sur la plateforme, comment les fichiers passent de l’appareil du client au contexte du modèle, ce que chaque canal prend en charge et comment conserver le contexte entre les sessions quand un client revient.

Canaux et entrées

ElevenAgents s’appuie sur les canaux déjà utilisés par les entreprises pour joindre leurs clients : applications web et mobiles, plateforme de support, téléphone, SMS, email, WhatsApp et d’autres. La configuration de l’agent (prompt, modèle, outils, base de connaissances et voix) est définie une fois et partagée sur tous les canaux. Deux éléments varient selon le canal : la couche de transport et les types d’entrées pris en charge. Les applications web et mobiles se connectent via le widget intégrable, l’un des SDK ou le WebSocket Agents. Les conversations téléphoniques passent par l’intégration native Twilio, le SIP trunking ou des intégrations natives basées sur websocket. Les SMS passent par l’intégration native Twilio. WhatsApp se connecte en important un compte WhatsApp Business et en activant l’intégration sur l’agent. Un même agent peut être déployé sur tous ces canaux en même temps.

Les entrées fichiers (images et PDF) sont actuellement prises en charge sur le web, mobile et WhatsApp. Le traitement des entrées dépend du type, pas du canal : une photo et une note vocale reçues sur la même session WhatsApp suivent des parcours techniques différents avant d’arriver au modèle. Quel que soit le canal ou le type d’entrée, tout converge vers la même couche de prétraitement avant d’être transmis au modèle comme contexte natif, où deux chemins sont possibles.

Représentation des entrées : fichier ou en ligne

Quel que soit le type d’entrée ou le canal, la plateforme normalise chaque entrée dans l’une des deux représentations internes avant de la transmettre au modèle. Cette classification détermine comment l’entrée est encodée dans la fenêtre de contexte du modèle et ce que votre intégration doit gérer en amont.

Entrées liées à un fichier

Les images et PDF sont transmis au modèle comme références de fichiers natifs, et non comme résumés texte. La plateforme stocke le fichier, lui attribue un file_id, et lie cet identifiant au tour de l’utilisateur. Un modèle compatible vision ou document reçoit le fichier brut dans sa fenêtre de contexte, et non une version dérivée. L’intégration est simple : il suffit de récupérer le file_id renvoyé par l’endpoint d’upload et de l’inclure dans le message. Si le message est envoyé sans le file_id, le modèle n’a aucune référence au fichier, même si l’upload a réussi. Le stockage du fichier est limité à la conversation. Tout ce qui doit persister au-delà de la session (le fichier lui-même, des champs extraits ou une sortie structurée) doit être géré explicitement par votre intégration. Le mécanisme varie selon le canal et le cas d’usage.

En ligne

La seconde représentation est en ligne et concerne tout le reste. Les voix et notes vocales sont transcrites. Les textes saisis, paroles transcrites, localisations WhatsApp et cartes de contact sont tous normalisés en texte brut dans la transcription avant le passage au modèle. Une localisation devient des coordonnées et une adresse optionnelle ; un contact devient un nom et un numéro de téléphone. Aucun de ces éléments n’est stocké comme fichier ni ne génère de référence de fichier. Ces entrées figurent directement dans la transcription.

Pourquoi cette distinction est importante

Cette séparation détermine où se situe l’effort d’intégration. Le chemin en ligne ne demande rien de votre part pendant la conversation : la plateforme normalise ces entrées en texte, qui figurent directement dans la transcription. Le chemin fichier a une surface d’intégration distincte. Au lieu de convertir le contenu du fichier en texte avant le modèle, l’orchestrateur transmet le fichier brut directement dans la fenêtre de contexte du modèle. Le modèle travaille sur la structure du fichier, et non sur une version texte ou une description, ce qui préserve la disposition spatiale, la mise en page visuelle et le format du document qui seraient sinon perdus. Avec cette distinction en tête, la suite de l’article détaille la mise en œuvre : comment configurer l’agent, comment les fichiers circulent sur chaque canal et comment conserver le contexte entre les sessions.

Configurer l’entrée multimodale

L’activation de l’entrée multimodale commence avec la même configuration d’agent sur le web, mobile et WhatsApp. Ensuite, la façon dont un fichier est envoyé et récupéré dépend du canal.

Activer l’entrée fichier

Deux paramètres doivent être activés dans la configuration de l’agent pour que l’entrée fichier fonctionne. D’abord, définissez conversation_config.conversation.file_input.enabled sur True, soit via l’API lors de la création de l’agent, soit dans Paramètres > Paramètres avancés > Entrée fichier dans le tableau de bord. Ensuite, l’agent doit être configuré avec un modèle compatible vision et document. Le paramètre seul ne suffit pas si le modèle ne peut pas traiter les images ou documents ; les deux doivent être activés avant de tester.

SDK et WebSocket

L’entrée fichier sur le web ou mobile nécessite un client de chat personnalisé basé sur le SDK ou une connexion Agents websocket brute. Le flux est identique sur les trois, et l’ordre est impératif : le fichier doit être uploadé avant l’envoi du message, car le message fait référence à l’identifiant retourné par l’upload.

Uploadez d’abord le fichier :

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  

Voir la documentation d’upload de fichier pour la requête et la réponse complètes :

Ensuite, envoyez un message sur la connexion qui fait référence au file_id retourné :

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

Les SDK simplifient l’upload et la référence en une seule opération, gérant l’identifiant du fichier en interne. Voir la spécification multimodal_message pour le format complet du message. Puisque votre application effectue l’upload, le fichier est déjà disponible à ce moment-là. Si vous n’en avez besoin que pour la conversation en cours, l’upload et la référence suffisent. Si vous devez le conserver au-delà de la session, le plus simple est de le stocker dans votre application au moment de l’upload. Il peut aussi être récupéré ensuite via le webhook post-call, expliqué dans la section sur le contexte entre les sessions.

WhatsApp

Sur WhatsApp, votre application n’intervient pas dans l’upload. Quand un client envoie une image, un document ou un sticker, le fichier va d’abord sur l’infrastructure de Meta. Meta notifie ElevenLabs via le webhook de l’API WhatsApp Business, et ElevenLabs utilise vos identifiants WhatsApp Business connectés pour télécharger le fichier de serveur à serveur, en stocke une copie et l’attache à la conversation comme pour un upload web ou SDK. L’agent le reçoit comme entrée multimodale et la transcription enregistre un événement file_input.

Votre application ne gère donc jamais l’upload ni ne détient le fichier directement. Il n’y a pas de récupération possible au moment de l’upload comme sur le web ou mobile. Le fichier arrive dans votre système via le file_url du webhook post-call, qui pointe vers la copie stockée par ElevenLabs. L’URL média de Meta sert uniquement à l’ingestion et n’est jamais exposée à l’extérieur. Les modalités de récupération, y compris les contraintes de temps pour le téléchargement, sont détaillées dans la section sur le contexte entre les sessions.

Sur WhatsApp, le client envoie le fichier dans le chat. ElevenLabs le récupère depuis Meta, le stocke et attache le file_id côté plateforme. Il n’y a donc pas d’étape d’upload côté client. Contrairement au web et mobile, votre application n’appelle pas POST /v1/convai/conversations/{id}/files ni n’envoie de multimodal_message via WebSocket. ElevenLabs gère la livraison, le stockage et le tour de l’agent.

Conserver le contexte entre les sessions

ElevenAgents traite chaque conversation séparément. Rien de ce qu’un client envoie, ni de ce que l’agent résout pendant une conversation, n’est transmis automatiquement à la suivante. L’agent transmet à votre système tout ce qui concerne une conversation terminée via le webhook post-call, mais la mémoire qui relie les conversations se trouve hors de ElevenLabs. C’est à vous d’assurer la continuité.

Cette séparation architecturale mérite d’être prise en compte. Les conversations où l’entrée multimodale est la plus utile (un client photographie un objet endommagé, envoie un document, partage une localisation) ne sont souvent pas résolues en une seule session. Un client qui envoie la photo d’une pièce cassée et programme un rappel s’attend à ce que l’agent s’en souvienne lors du rappel. Sans gestion explicite du contexte, l’agent recommence à zéro à chaque fois et le client doit tout répéter. La solution se fait en deux temps. À la fin d’une conversation, le webhook post-call transmet la transcription, les résultats d’analyse, les champs de collecte de données que vous avez définis et les URLs des fichiers passés pendant la session. Votre backend stocke ce qui est pertinent avec un identifiant client durable comme un numéro de téléphone, un ID utilisateur ou une clé de compte. Quand ce client revient, votre application injecte le contexte stocké au début de la session via des variables dynamiques, pour que l’agent commence la conversation avec ce qu’il sait déjà. Pour les entrées fichiers, l’URL du fichier dans le webhook pointe vers la copie stockée par ElevenLabs et c’est le seul moyen de la récupérer après la fin de la conversation. La copie de la plateforme est limitée à la session, donc si vous avez besoin du fichier pour une future conversation ou dans vos propres systèmes, vous devez le télécharger depuis le webhook avant la fermeture de la fenêtre. La rapidité d’action dépend de la politique de rétention, détaillée dans la documentation de référence. Le webhook sort l’état, les variables dynamiques le réinjectent. Tout le reste est à la charge de votre système, et c’est là que se situe le vrai travail d’intégration pour les cas où les clients reviennent, relancent ou poursuivent une résolution en cours.

L’injection de contexte dépend du canal

Le mécanisme d’injection varie selon le canal, mais le principe reste le même. Pour la téléphonie, ElevenLabs appelle votre serveur avant de connecter l’appel, ce qui vous permet d’identifier l’appelant par son numéro et de renvoyer des variables dynamiques comme le nom, l’ID de commande ou le niveau de compte avant que l’agent ne parle. Sur WhatsApp, un webhook pré-message est déclenché à chaque message entrant, ce qui vous permet d’enrichir le message avec l’identité et le contexte métier de vos systèmes avant que l’agent ne le traite. Sinon, les mêmes champs sont transmis dans conversation_initiation_client_data à l’ouverture de la session. ElevenAgents ne fusionne pas les sessions de différents canaux dans un même fil. Une conversation WhatsApp et une conversation web sont deux sessions distinctes, même pour un même client. Mais comme la sortie du webhook et l’injection de variables dynamiques fonctionnent de la même façon sur tous les canaux, une seule couche de persistance suffit pour tous. Une fois en place, elle couvre tous les canaux utilisés par l’agent. L’injection de contexte concerne les données textuelles : noms, ID de commande, résumés, champs structurés. Les fichiers sont un cas à part et nécessitent une approche différente.

Transférer les fichiers d’une session à l’autre

Les fichiers sont limités à une session et ne persistent pas automatiquement. Ce qu’il faut transférer dépend de si la prochaine conversation a besoin de l’information issue d’un fichier ou du fichier lui-même. Dans la plupart des cas, seule l’information suffit. L’agent interprète un fichier uploadé au moment où il arrive, mais n’enregistre pas automatiquement cette interprétation de façon durable. La sortie structurée provient des données post-call : la transcription, le résumé de la transcription et les champs de collecte de données que vous définissez. Si un client envoie la photo d’un joint de porte fissuré et revient une semaine plus tard pour suivre la réclamation, l’agent n’a pas besoin de la photo à nouveau. Il doit savoir que la réclamation concerne un joint de porte fissuré. Vous extrayez cette information des données post-call, la stockez avec l’identifiant client et l’injectez comme variable dynamique lors du retour du client. Un court résumé ou quelques champs structurés suffisent généralement.

Si vous avez besoin du fichier original, pour vos archives, la conformité ou d’autres systèmes, le webhook post-call est la voie de récupération. Chaque fichier uploadé apparaît dans la transcription comme un événement file_input avec une URL signée. Cette URL est valable quinze minutes, donc téléchargez et stockez le fichier dès la réception du webhook, sans attendre. Si vous ratez cette fenêtre alors que la conversation existe encore, l’API GET conversation fournit de nouvelles URLs en secours. Prévoyez que file_input puisse être absent dans certains cas comme le mode zéro-rétention, au lieu de supposer que chaque tour avec fichier aura une URL.

Voilà pour le cycle complet : un fichier entre dans la session, le modèle l’utilise en natif, la sortie structurée part via le webhook, et votre couche de persistance décide de ce que l’agent saura la prochaine fois.

Conclusion

La même configuration d’agent accepte images et PDF sur le web, mobile et WhatsApp, sans besoin de développement séparé par canal. Les fichiers sont normalisés, liés au tour et transmis au modèle comme blocs natifs, ce qui préserve la mise en page, la structure visuelle et le format du document. Le contexte entre les sessions suit le même schéma sur chaque canal : le webhook post-call sort l’état, les variables dynamiques le réinjectent.

Si vous développez sur ElevenLabs Agents et souhaitez que votre agent traite images et documents en plus de la voix et du texte, activez l’entrée multimodale et dites-nous ce que vous en pensez.