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 workflows d’entreprise comportent souvent un contexte que les mots seuls ne peuvent transmettre. Les informations nécessaires pour résoudre une demande peuvent être fournies sous 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 la résolution. Lorsqu’un client peut montrer plutôt que décrire, l’agent diagnostique le problème plus vite sans lui demander de changer de canal. Rohlik, l’une des plus grandes plateformes européennes de courses alimentaires en ligne, déploie son agent par téléphone, sur le web, dans son 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 à part entière dans 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 gère ainsi chaque type d’entrée au sein d’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 prend en charge chaque canal et comment conserver le contexte entre les sessions lorsqu’un client revient.

Canaux et entrées 

ElevenAgents s’appuie sur les canaux que les entreprises utilisent déjà pour contacter leurs clients : applications web et mobiles, plateforme de support, 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 de leur type, non du canal : une photo et un message vocal reçus dans la 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 entrées en ligne

Quel que soit le type d’entrée ou le canal, la plateforme normalise chaque entrée dans 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 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. La règle 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 l’importation a réussi. Le stockage des fichiers est limité à la conversation. Tout élément 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 épingles 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. Une épingle de localisation devient des coordonnées et, éventuellement, une adresse ; 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ù concentrer vos efforts d’intégration. La voie en ligne ne vous demande rien pendant la conversation : la plateforme normalise ces entrées en texte, qui figure directement dans la transcription. La voie basée sur des fichiers présente une surface d’intégration distincte. Au lieu de convertir le contenu du fichier en texte avant l’exécution du modèle, l’orchestrateur transmet le fichier brut directement dans la fenêtre de contexte du modèle. Le modèle opère sur la structure du fichier plutôt que sur une représentation ou une description textuelle dérivée, préservant les relations spatiales, la mise en page visuelle et le formatage des documents qui seraient autrement perdus. Fort de cette distinction, le reste de cet article aborde l’implémentation : comment configurer l’agent, comment les fichiers transitent par chaque canal et comment conserver le contexte entre les sessions.

Configurer l’entrée multimodale 

L’activation de l’entrée multimodale commence par la même configuration d’agent sur le web, mobile et WhatsApp. Ensuite, la manière dont un fichier est importé et récupéré dépend du canal.

Activer l’entrée de fichiers

Deux paramètres doivent être définis dans la configuration de l’agent pour que l’entrée de fichiers 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 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 suffit pas 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

L’entrée de fichiers sur le web ou mobile requiert un client de chat personnalisé basé sur le SDK ou une connexion WebSocket Agents brute. Le flux est identique pour les trois, 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é par 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 connaître la requête et la réponse complètes :

Envoyez ensuite un message via la connexion qui fait 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érence en un seul appel, en gérant l’identifiant du fichier en interne. Consultez la spécification multimodal_message pour le format complet du message. Puisque votre application effectue l’importation, elle dispose déjà du fichier à ce stade. Si vous en avez besoin uniquement pour la conversation en cours, il suffit de l’importer et d’en référencer l’identifiant. Si vous devez le conserver au-delà de la session, la meilleure approche consiste à le stocker depuis votre application au moment de l’importation. Vous pouvez également le récupérer ultérieurement via le webhook post-appel, abordé dans la section consacrée au contexte entre les sessions.

WhatsApp

Sur WhatsApp, votre application ne participe pas à l’importation. Lorsqu’un client envoie une image, un document ou un sticker, le fichier transite d’abord par l’infrastructure de Meta. Meta notifie 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’une importation sur le web ou via un SDK. L’agent le reçoit comme entrée multimodale et la transcription enregistre un événement file_input.

Puisque votre application ne gère jamais l’importation, elle ne détient jamais directement le fichier. Il n’existe pas de moyen de le récupérer au moment de l’importation comme sur le web et 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 du média 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 abordés 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 mobile, votre application n’appelle pas POST /v1/convai/conversations/{id}/files et n’envoie pas 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 indépendamment. Rien de ce qu’envoie un client, ni de ce que l’agent résout pendant 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 se situe en dehors du périmètre d’ElevenLabs. La continuité vous appartient.

Cette frontière architecturale mérite d’être prise en compte dès la conception. Les conversations pour lesquelles l’entrée multimodale est la plus utile — 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 une photo d’une pièce cassée et planifie 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. Lorsqu’une conversation se termine, 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é pendant la session. Votre backend stocke les éléments pertinents associés à un identifiant client pérenne, comme 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émarrage de la session via des variables dynamiques, afin que l’agent commence 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 clôture de la conversation. La copie de la plateforme est limitée à la session ; si vous avez besoin du fichier lors d’une future conversation ou dans vos propres systèmes, vous devez donc le télécharger depuis la charge utile du webhook avant la fermeture de cette fenêtre. Le délai d’action dépend de la politique de conservation, décrite dans la documentation de référence. Le webhook transmet l’état vers l’extérieur. 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 concentre le véritable travail d’intégration pour tout cas d’usage où les clients reviennent, escaladent une demande ou reprennent une résolution en cours.

L’injection du contexte dépend du canal

Le mécanisme d’injection varie selon le canal, mais le principe 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 est déclenché à chaque message entrant, ce qui vous permet de l’enrichir avec les données d’identité et le contexte métier de vos systèmes avant son traitement par l’agent. Sinon, ces 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 si elles concernent le même client. Mais comme la sortie du webhook et l’injection de variables dynamiques fonctionnent de façon identique sur tous les canaux, une seule couche de persistance les gère tous. Construisez-la une fois, et elle couvre chaque canal sur lequel l’agent est déployé. L’injection de contexte gère les données textuelles : noms, ID de commande, résumés, champs structurés. Les fichiers constituent un cas distinct et exigent une autre approche.

Conserver les fichiers

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 tour où il arrive, mais n’enregistre pas automatiquement cette interprétation dans un emplacement pérenne. La sortie structurée provient des données post-appel : la transcription, son résumé et les éventuels 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 sa réclamation, l’agent n’a pas besoin de revoir la photo. Il doit savoir que la réclamation concerne un joint de porte fissuré. Vous extrayez cette information des données post-appel, la stockez avec l’identifiant du client et l’injectez sous forme de variable dynamique lorsqu’il revient. 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 étape. Si vous manquez cette fenêtre alors que la conversation existe toujours, l’API GET de conversation réémet de nouvelles URL en solution de secours. Prévoyez que file_input puisse être absent dans certains cas, notamment en 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 passe par 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 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 ainsi intacts au modèle. Le contexte entre les sessions suit le même modèle sur chaque canal : le webhook post-appel transmet l’état vers l’extérieur, les variables dynamiques le réinjectent.

Si vous développez avec ElevenLabs Agents et souhaitez que votre agent exploite des images et documents en plus de la voix et du texte, activez l’entrée multimodale et partagez-nous votre avis.