Fichiers et médias

Votre agent peut envoyer des fichiers et des médias, et lire ceux que l'utilisateur lui envoie. Le SDK chiffre les octets localement avec une nouvelle clé AES-256-GCM, n'envoie que le contenu chiffré, et transmet la clé — avec le nom et le type du fichier — à l'intérieur du message chiffré de bout en bout. Pacerelle stocke un fichier qu'il ne peut pas ouvrir, sous un nom qu'il ne peut pas lire.

Envoyer un fichier

import { readFile } from "node:fs/promises";

await agent.sendFile({
  conversationId: message.conversationId,
  to: message.from,
  replyToMessageId: message.id,
  text: "Voici le rapport du mois.",
  file: {
    name: "rapport-septembre.pdf",
    mime: "application/pdf",
    data: await readFile("./out/rapport-septembre.pdf"),
  },
});

En JavaScript, data accepte un Uint8Array, un ArrayBuffer ou un Blob. En Python, passez des bytes.

Envoyer une image, un son ou une vidéo

sendMedia fonctionne comme sendFile et ajoute des indications d'affichage facultatives — width et height pour les images et vidéos, durationMs (duration_ms) pour l'audio et la vidéo — afin que l'application prépare l'aperçu avant le téléchargement.

await agent.sendMedia({
  conversationId: message.conversationId,
  to: message.from,
  text: "Ventes par région",
  file: { name: "graphique.png", mime: "image/png", data: pngBytes },
  width: 1200,
  height: 800,
});

Plusieurs fichiers dans un message

Envoyez d'abord chaque fichier, puis joignez-les ensemble :

const attachments = await Promise.all(
  files.map((file) => agent.uploadFile(file)),
);

await agent.sendMessage({
  conversationId: message.conversationId,
  to: message.from,
  text: "Les trois exports sont prêts.",
  attachments,
});

En Python, utilisez upload_file(...) puis send_message(..., attachments=[...]).

Fichiers envoyés par l'utilisateur

Quand l'utilisateur joint des fichiers — dans un message ou via un widget Fichiers — chacun apparaît dans message.attachments avec son nom (name), son type (mime) et sa taille (size). Téléchargez-le et déchiffrez-le avec downloadAttachment (download_attachment en Python) : le SDK récupère le contenu chiffré et le déchiffre sur votre machine avec la clé transportée par le message.

client.onMessage(async (message, agent) => {
  for (const attachment of message.attachments) {
    if (attachment.size > 10_000_000) continue; // vérifier avant de traiter
    const bytes = await agent.downloadAttachment(attachment); // Uint8Array
    console.log(attachment.name, attachment.mime, bytes.length);
  }
});

L'agent peut télécharger les fichiers des conversations dont il est membre. Dans un groupe, il s'agit des fichiers envoyés après son ajout.

Limites

Le téléchargement échoue une fois le fichier expiré : enregistrez ce dont votre agent a besoin dès réception.

Confidentialité

• Le contenu, le nom et le type des fichiers sont chiffrés de bout en bout. Le relais stocke le contenu chiffré sous un nom générique et ne voit que la taille de chaque fichier.
• Les messages envoyés avant cette protection gardent leur nom d'origine dans les registres du relais ; les nouveaux fichiers ne l'exposent plus jamais.
• Traitez tout fichier reçu comme une entrée non fiable : vérifiez son type et sa taille avant de le traiter, et demandez l'accord de l'utilisateur avant d'envoyer son contenu à un service tiers.