Traitement des images et documents dans ElevenAgents

Un chef de chantier constate une pénurie de matériaux sur un site. Il la photographie, envoie l’image à l’agent chargé des achats sur WhatsApp et confirme l’adresse de livraison à la voix. L’agent traite la photo, identifie les éléments manquants et passe une commande urgente, le tout dans une seule conversation. Les flux de travail en entreprise comportent régulièrement un contexte que les mots seuls ne peuvent transmettre. Les informations nécessaires pour traiter une demande peuvent prendre la forme d’une photo d’un article endommagé ou d’un PDF de police. Les transmettre directement à l’agent raccourcit la conversation et accélère le traitement. Lorsqu’un client peut montrer plutôt que décrire, l’agent résout le problème plus vite sans lui demander de changer de canal. Rohlik, l’une des plus grandes plateformes d’épicerie en ligne d’Europe, déploie son agent par téléphone, sur le web, dans l’application et sur WhatsApp, en six langues, et résout automatiquement 90 % des demandes clients. L’entrée multimodale étend ce même taux de résolution aux situations où le client doit montrer plutôt qu’expliquer. ElevenAgents traite les fichiers comme des entrées de premier plan pour le même agent qui gère déjà la voix, WhatsApp, le web et le mobile. Les fichiers parviennent au modèle sous-jacent sous forme de messages natifs ; un seul agent peut donc gérer tous les types d’entrée dans un même fil de conversation. 

Cet article explique ce que recouvre la multimodalité sur la plateforme, comment les fichiers passent de l’appareil d’un client au contexte du modèle, ce que chaque canal prend en charge et comment conserver le contexte d’une session à l’autre lorsqu’un client revient.

Canaux et entrées 

ElevenAgents s’appuie sur les canaux que les entreprises utilisent déjà pour joindre leurs clients : applications web et mobiles, plateforme d’assistance, téléphone, SMS, e-mail, WhatsApp et autres. La configuration de l’agent (prompt, modèle, outils, base de connaissances et voix) est définie une seule fois et partagée entre tous les canaux. Deux éléments varient selon le canal : la couche de transport et les types d’entrée pris en charge. Les applications web et mobiles se connectent via le widget intégrable, l’un des SDK ou l’Agents WebSocket. Les conversations téléphoniques se connectent via Twilio natif, le trunking SIP ou des intégrations natives basées sur WebSocket. Les SMS se connectent via l’intégration Twilio native. 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é simultanément sur tous ces transports.

Les entrées de fichiers (images et PDF) sont actuellement prises en charge sur le web, mobile et WhatsApp. Le traitement des entrées dépend du type, et non du canal : une photo et un message vocal reçus dans une même session WhatsApp suivent des pipelines entièrement différents avant d’atteindre le modèle. Quel que soit le canal ou le type d’entrée, toutes les entrées convergent vers la même couche de prétraitement avant d’être transmises au modèle comme contexte natif, où elles suivent l’une de deux voies.

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

Quel que soit le type d’entrée ou le canal, la plateforme normalise chaque entrée selon l’une de 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 basées sur des fichiers

Les images et les PDF sont transmis au modèle sous forme de références de fichiers natives, et non de résumés textuels. La plateforme stocke le fichier, lui attribue un file_id et associe cet identifiant au tour de l’utilisateur. Un modèle capable de traiter les images ou les documents reçoit le fichier brut dans sa fenêtre de contexte plutôt qu’une représentation dérivée. L’exigence d’intégration est simple : récupérez le file_id renvoyé par le point de terminaison d’importation et incluez-le dans la charge utile du message. Si le message est envoyé sans le file_id, le modèle n’a aucune référence au fichier, même si son importation a réussi. Le stockage des fichiers est limité à la conversation. Tout ce qui doit persister au-delà de la session — le fichier lui-même, les champs extraits ou une sortie structurée — doit donc ê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 couvre tout le reste. La voix et les messages vocaux sont transcrits. Le texte saisi, la parole transcrite, les repères de localisation WhatsApp et les cartes de contact sont tous normalisés en texte brut dans la transcription avant l’exécution du modèle. Un repère de localisation devient des coordonnées et une adresse facultative ; un contact devient un nom et un numéro de téléphone. Aucun de ces éléments n’est stocké comme fichier et aucun ne produit de référence de fichier. Ces entrées sont directement présentes dans la transcription.

Pourquoi cette distinction compte

Cette séparation détermine où concentrer vos efforts d’intégration. La voie en ligne ne requiert aucune action de votre part pendant la conversation : la plateforme normalise ces entrées en texte, directement dans la transcription. La voie basée sur des fichiers dispose d’une surface d’intégration distincte. Au lieu de convertir le contenu d’un fichier en texte avant l’exécution du modèle, l’orchestrateur transmet le fichier brut directement dans sa fenêtre de contexte. Le modèle exploite la structure du fichier plutôt qu’une représentation ou une description textuelle dérivée, ce qui préserve les relations spatiales, la mise en page visuelle et le formatage du document qui seraient autrement perdus. Avec cette distinction en tête, la suite de cet article aborde l’implémentation : comment configurer l’agent, comment les fichiers circulent dans chaque canal et comment conserver le contexte d’une session à l’autre.

Configurer les entrées multimodales 

L’activation des entrées multimodales commence par une même configuration d’agent sur le web, mobile et WhatsApp. Ensuite, le mode d’importation d’un fichier et sa récupération dépendent du canal.

Activer les entrées de fichiers

Deux paramètres doivent être définis dans la configuration de l’agent pour que les entrées de fichiers fonctionnent. Définissez d’abord conversation_config.conversation.file_input.enabled sur True, soit via l’API lors de la création de l’agent, soit dans Settings > Advanced Settings > File Input du Dashboard. Ensuite, l’agent doit être configuré avec un modèle capable de traiter les images et les documents. Le paramètre seul ne fait rien si le modèle sous-jacent ne peut pas traiter les blocs d’images ou de documents ; les deux doivent être définis avant les tests.

SDK et WebSocket

Les entrées de fichiers sur le web ou mobile nécessitent un client de chat personnalisé construit avec le SDK ou une connexion Agents WebSocket brute. Le flux est identique dans les trois cas, et l’ordre des opérations est impératif : le fichier doit être importé avant l’envoi du message, car la charge utile du message fait référence à l’identifiant renvoyé lors de l’importation.

Importez 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  

Consultez l’importation de fichier pour la requête et la réponse complètes :

Envoyez ensuite via la connexion un message faisant référence au file_id renvoyé :

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

Les SDK regroupent les étapes d’importation et de référencement en un seul appel, en gérant l’identifiant du fichier en interne. Consultez la spécification multimodal_message pour connaître le format complet du message. Puisque votre application importe le fichier, elle le détient déjà à ce stade. Si vous en avez uniquement besoin pour la conversation en cours, il suffit de l’importer et de référencer son identifiant. Si vous devez le conserver au-delà de la session, la meilleure approche consiste à le stocker depuis votre application lors de l’importation. Vous pouvez aussi le récupérer ultérieurement par le webhook post-appel, présenté dans la section consacrée au contexte entre les sessions.

WhatsApp

Sur WhatsApp, votre application n’intervient pas dans l’importation. Lorsqu’un client envoie une image, un document ou un sticker, le fichier est d’abord transmis à l’infrastructure de Meta. Meta avertit ElevenLabs via le webhook de l’API WhatsApp Business, puis ElevenLabs utilise les identifiants de votre compte WhatsApp Business connecté pour télécharger le fichier de serveur à serveur, en stocke sa propre copie et l’associe à la conversation comme lors d’un import depuis le web ou un SDK. L’agent le reçoit comme entrée multimodale et la transcription enregistre un événement file_input.

Comme votre application ne gère jamais l’importation, elle ne détient jamais directement le fichier. Il n’existe pas de moyen de le capturer au moment de l’importation, contrairement au web et au mobile. Le fichier parvient à votre système via le file_url du webhook post-appel, qui pointe vers la copie stockée par ElevenLabs. L’URL média de Meta est utilisée uniquement pour l’ingestion et n’est jamais exposée à l’extérieur. Les mécanismes de récupération, y compris les contraintes de délai de téléchargement, sont décrits dans la section consacrée au contexte entre les sessions.

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

Conserver le contexte entre les sessions

ElevenAgents traite chaque conversation indépendamment. Rien de ce qu’un client envoie, ni de ce que l’agent résout durant une conversation, n’est automatiquement reporté dans la suivante. L’agent transmet à votre système tous les éléments d’une conversation terminée via le webhook post-appel, mais la mémoire qui s’étend d’une conversation à l’autre reste en dehors du périmètre d’ElevenLabs. C’est à vous d’assurer la continuité.

Il vaut la peine de concevoir délibérément autour de cette limite architecturale. Les conversations où les entrées multimodales comptent le plus — un client qui photographie un article endommagé, importe un document de police ou partage une localisation — ne se résolvent souvent pas 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 se souvienne de la photo lorsqu’il rappelle. Sans gestion explicite du contexte, l’agent repart de zéro à chaque fois et le client doit se répéter. Le modèle qui répond à ce besoin comporte deux volets. À la fin d’une conversation, le webhook post-appel transmet la transcription, les résultats d’analyse, les champs de collecte de données structurées que vous avez définis et les URL des fichiers ayant transité durant la session. Votre backend stocke les éléments pertinents sous un identifiant client durable, tel qu’un numéro de téléphone, un ID utilisateur ou une clé de compte. Lorsque ce client revient, votre application injecte le contexte stocké au début de la session via des variables dynamiques ; l’agent entame ainsi la conversation avec ce qu’il sait déjà. Pour les entrées basées sur des fichiers, l’URL du fichier dans la charge utile du webhook pointe vers la copie stockée par ElevenLabs et constitue le seul moyen de récupération après la fermeture de la conversation. La copie de la plateforme est limitée à la session ; si vous avez besoin du fichier dans une conversation future ou dans vos propres systèmes, vous devez le télécharger depuis la charge utile du webhook avant l’expiration de cette période. Le délai dont vous disposez dépend de la politique de conservation, décrite dans la documentation de référence. Le webhook fait sortir l’état. Les variables dynamiques le réinjectent. Tout ce qui se trouve entre les deux relève de votre système : c’est là que se situe l’essentiel du travail d’intégration pour tout cas d’usage où les clients reviennent, font remonter une demande ou reprennent un traitement en cours.

L’injection du contexte dépend du canal

Le mécanisme d’injection varie selon le canal, mais le modèle sous-jacent reste le même. Pour la téléphonie, ElevenLabs appelle votre serveur avant la connexion de l’appel, ce qui vous permet de rechercher l’appelant par son numéro et de renvoyer des variables dynamiques telles que son nom, l’ID de commande ou le niveau de compte avant que l’agent ne parle. Sur WhatsApp, un webhook pré-message se déclenche à chaque message entrant, ce qui vous permet de l’enrichir avec des informations d’identité et de contexte métier provenant de vos systèmes avant son traitement par l’agent. Sinon, les mêmes champs sont transmis dans conversation_initiation_client_data à l’ouverture de la session. ElevenAgents ne fusionne pas les sessions entre les canaux dans un même fil. Une conversation WhatsApp et une conversation web sont des sessions distinctes, même lorsqu’elles concernent le même client. Toutefois, comme la sortie du webhook et l’injection de variables dynamiques fonctionnent de manière identique sur tous les canaux, une seule couche de persistance les gère tous. Construisez-la une seule fois et elle couvrira tous les canaux sur lesquels l’agent est déployé. L’injection de contexte gère les données sous forme de texte : noms, ID de commande, résumés et champs structurés. Les fichiers constituent un cas distinct et exigent une autre approche.

Conserver les fichiers pour la suite

Les fichiers sont limités à une conversation et ne persistent pas automatiquement. Ce qu’il faut conserver dépend de si la conversation suivante nécessite les informations contenues dans un fichier ou le fichier lui-même. Dans la plupart des cas, seules les informations sont nécessaires. L’agent interprète un fichier importé au moment où il arrive, mais n’enregistre pas automatiquement cette interprétation dans un emplacement durable. La sortie structurée provient des données post-appel : la transcription, son résumé et les champs de résultats 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 son dossier, l’agent n’a pas besoin de la photo à nouveau. Il doit savoir que le dossier concerne un joint de porte fissuré. Vous extrayez cette information des données post-appel, la stockez sous l’identifiant client et l’injectez comme variable dynamique à son retour. Un court résumé ou quelques champs structurés suffisent généralement.

Lorsque vous avez besoin du fichier d’origine, pour vos propres dossiers, la conformité ou des systèmes en aval, le webhook post-appel est le moyen de récupération. Chaque fichier importé apparaît dans la transcription comme un événement file_input avec une URL de fichier signée. Cette URL est valide pendant quinze minutes ; téléchargez et stockez donc le fichier à l’arrivée du webhook plutôt que de reporter cette opération. Si vous manquez ce créneau alors que la conversation existe encore, l’API GET de conversation émet de nouvelles URL en solution de repli. Prévoyez que file_input puisse être absent dans certains cas, comme le mode sans conservation, plutôt que de supposer que chaque tour basé sur un fichier comporte une URL.

Cela couvre l’ensemble du cycle de vie : un fichier entre dans la session, le modèle l’exploite nativement, la sortie structurée est transmise 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 les images et les PDF sur le web, mobile et WhatsApp, sans développement distinct pour chaque canal. Les fichiers sont normalisés, associés au tour et transmis au modèle sous forme de blocs natifs plutôt que de résumés textuels ; la mise en page spatiale, la structure visuelle et le formatage des documents parviennent donc intacts au modèle. Le contexte entre les sessions suit le même modèle sur tous les canaux : le webhook post-appel fait sortir l’état, les variables dynamiques le réinjectent.

Si vous développez avec ElevenLabs Agents et souhaitez que votre agent traite des images et des documents en plus de la voix et du texte, activez les entrées multimodales et partagez-nous votre avis.