Traitement des images et documents dans ElevenAgents

Un chef de chantier constate un manque de matériaux sur un site. Il le photographie, envoie l’image à l’agent chargé des achats sur WhatsApp et confirme l’adresse de livraison par téléphone. 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 conditions générales. 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 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, utilise son agent par téléphone, sur le web, dans l’application et sur WhatsApp, dans six langues, et résout automatiquement 90 % des demandes clients. Les entrées multimodales étendent 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 un même agent qui gère déjà le téléphone, WhatsApp, le web et le mobile. Les fichiers parviennent au modèle sous-jacent sous forme de messages natifs, ce qui permet à un seul agent de gérer chaque type d’entrée dans un même fil de conversation. 

Cet article explique ce que la multimodalité signifie 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 entre les sessions 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, texto, email, WhatsApp et autres. La configuration de l’agent, incluant le prompt, le modèle, les outils, la base de connaissances et la voix, est définie une seule fois et partagée sur 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 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 textos 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, le mobile et WhatsApp. Le traitement des entrées dépend de leur type, et non du canal : une photo et un message vocal reçus dans la même session WhatsApp sont traités via des pipelines entièrement différents avant de parvenir au 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, selon l’un de deux chemins.

Représentation des entrées : fichiers ou intégrées

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, puis 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 l’importation a réussi. Le stockage des fichiers est limité à la conversation. Tout élément devant être conservé au-delà de la session, qu’il s’agisse du fichier lui-même, de champs extraits ou d’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’utilisation.

Intégrées

La seconde représentation est intégrée 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 fiches 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, é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 produit 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. Le chemin des entrées intégrées ne requiert aucune action de votre part pendant la conversation : la plateforme normalise ces entrées en texte, qui figure directement dans la transcription. Le chemin basé sur les fichiers offre 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 exploite la structure du fichier plutôt qu’une représentation textuelle ou une description dérivée, préservant les relations spatiales, la mise en page visuelle et la mise en forme du document qui seraient autrement perdues. En gardant cette distinction à l’esprit, la suite de cet article aborde l’implémentation : comment configurer l’agent, comment les fichiers circulent sur chaque canal et comment conserver le contexte entre les sessions.

Configurer les entrées multimodales 

L’activation des entrées multimodales commence par la même configuration d’agent sur le web, le mobile et WhatsApp. Ensuite, la manière dont un fichier est importé et récupéré dépend 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 Paramètres > Paramètres avancés > Entrée de fichier 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 produit aucun effet si le modèle sous-jacent ne peut pas traiter les blocs d’image ou de document ; 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é conçu avec le SDK ou une connexion WebSocket Agents 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 connaître la requête et la réponse complètes :

Envoyez ensuite un message via la connexion 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 et gèrent l’identifiant du fichier en interne. Consultez la spécification multimodal_message pour connaître 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 de référencer son identifiant. Si vous devez le conserver au-delà de la session, l’approche la plus simple 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, présenté dans la section sur le 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 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 depuis le web ou 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 aucune méthode pour le récupérer au moment de l’importation, comme sur le web et le 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 abordés dans la section sur le 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 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’un client envoie, ni de ce que l’agent résout au cours d’une conversation, n’est automatiquement transféré à la suivante. L’agent transmet à votre système l’ensemble des données d’une conversation terminée via le webhook post-appel, mais la mémoire qui couvre plusieurs conversations se trouve hors du périmètre d’ElevenLabs. À vous d’assurer la continuité.

Il est important de concevoir votre architecture en tenant délibérément compte de cette frontière. Les conversations où les entrées multimodales sont les plus importantes, lorsqu’un client photographie un article endommagé, importe un document de conditions générales ou 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 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 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émarrage de la session via des variables dynamiques, afin que l’agent commence la conversation avec les informations qu’il possède 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 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 fin de cette période. Le délai dont vous disposez dépend de la politique de rétention, 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, et c’est là que se concentre le véritable travail d’intégration pour tout cas d’utilisation où les clients reviennent, font remonter un problème ou reprennent une résolution en cours.

L’injection de contexte dépend du canal

Le mécanisme d’injection varie selon le canal, mais le modèle sous-jacent reste cohérent. Pour le téléphone, ElevenLabs appelle votre serveur avant l’établissement de l’appel, vous permettant 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é pour chaque message entrant, ce qui vous permet de l’enrichir avec des informations d’identité et de contexte métier issues 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 des sessions distinctes, même si elles concernent le même client. Toutefois, puisque 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. Concevez-la une fois, et elle couvre chaque canal sur lequel l’agent opère. L’injection de contexte gère les données textuelles : noms, ID de commande, résumés et champs structurés. Les fichiers constituent un cas distinct et nécessitent une autre approche.

Conserver les fichiers

Les fichiers sont limités à une conversation et ne sont pas conservés automatiquement. Ce qu’il faut transférer dépend de la nécessité, pour la conversation suivante, de disposer des informations contenues dans un fichier ou du 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 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 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 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 constitue le moyen de récupération. Chaque fichier importé apparaît dans la transcription sous la forme d’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 dès la réception du webhook plutôt que de différer cette opération. Si vous manquez ce délai alors que la conversation existe encore, l’API GET de conversation génère à nouveau de nouvelles URL en solution de secours. Prévoyez l’absence de file_input dans certains cas, comme le mode zéro rétention, 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, une sortie structurée est transmise via le webhook et votre couche de persistance détermine ce que l’agent saura la prochaine fois.

Conclusion

La même configuration d’agent accepte les images et les PDF sur le web, le 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 des documents en plus de la voix et du texte, activez les entrées multimodales et partagez-nous votre avis.