Guide pratique

Documentation de l'API et du SDK ScreenApp

L'API ScreenApps vous permet de transcrire, de résumer et d'analyser automatiquement le contenu vidéo et audio

Par Équipe ScreenApp

Documentation de l’API ScreenApp v2.0.0

L’API de ScreenApp vous permet de transcrire, de résumer et d’analyser automatiquement du contenu vidéo et audio. Parfait pour les entreprises qui cherchent à traiter à grande échelle les appels clients, les vidéos de formation et les enregistrements de réunions.

Principaux cas d’utilisation

✨ Cas d’utilisation populaire : Les équipes de service client utilisent notre API pour transcrire automatiquement les appels d’assistance et générer des résumés, qui sont ensuite synchronisés avec leur CRM via des webhooks.

Obtenir les identifiants API dans le tableau de bord →

Exigences du plan et accès à l’API

Pour utiliser l’API ScreenApp, vous aurez besoin de :

  1. Un abonnement actif au plan Business
  2. Identifiants API depuis votre tableau de bord ScreenApp

Obtenir vos identifiants API

  1. Connectez-vous à votre compte ScreenApp
  2. Accédez à Paramètres → Intégration
  3. Ici, vous trouverez :
    • Jeton API
    • ID d’équipe

Gardez ces identifiants en sécurité et ne les partagez jamais publiquement.

Démarrage rapide

Vous voulez démarrer tout de suite ? Suivez ces étapes pour intégrer ScreenApp à votre site Web :

1. Installer le plugin

Ajoutez ce code au HTML de votre site web :

<script>
  // Code d'installation du plugin ici
</script>

2. Ajouter le bouton de déclenchement

Ajoutez un bouton ou un élément de déclenchement à votre page :

<button onclick="loadScreenApp()">Démarrer l'enregistrement</button>

3. Configurer le callback

Personnalisez la fonction de callback pour gérer la fin de l’enregistrement :

function callback({ id, url }) {
  // Exemple : Envoyer à votre backend
  fetch('/api/recordings', {
    method: 'POST',
    body: JSON.stringify({ recordingId: id, recordingUrl: url })
  });
  
  // Exemple : Mettre à jour l'interface utilisateur
  document.getElementById('status').innerHTML = 
    `Enregistrement sauvegardé ! Visualisez-le à ${url}`;
}

Authentification

Toutes les requêtes API nécessitent une authentification. ScreenApp utilise une authentification basée sur un jeton ainsi que des identifiants spécifiques à l’équipe.

Identifiants dont vous aurez besoin

Exemple d’authentification

curl -X POST "https://api.screenapp.io/v2/files/upload" \
  -H "Authorization: Bearer VOTRE_JETON_API" \
  -H "X-Team-ID: VOTRE_ID_ÉQUIPE"

Points de terminaison d’authentification

GET /auth/google

Rediriger vers Google pour l’authentification

Paramètres de requête :

GET /auth/facebook

Rediriger vers Facebook pour l’authentification

Paramètres de requête :

Concepts fondamentaux

Avant de plonger dans des points de terminaison spécifiques, comprenons les concepts clés de ScreenApp :

  1. Enregistrements : captures vidéo et audio qui peuvent être téléchargées et traitées
  2. Équipes : groupes qui peuvent partager et gérer des enregistrements
  3. Webhooks : notifications en temps réel pour les événements d’enregistrement et les résultats de traitement
  4. Tags : Métadonnées pouvant être attachées aux enregistrements, aux équipes ou aux profils d’utilisateurs

Référence API

Gestion d’équipe

POST /team/{teamId}/tag

Ajouter un tag à l’équipe

Paramètres du chemin :

Corps de la requête :

{
  "key": "color",
  "value": "red"
}

DELETE /team/{teamId}/tag

Supprimer un tag de l’équipe

Paramètres du chemin :

Corps de la requête :

{
  "key": "color"
}

Intégration de Webhook d’équipe

POST /team/{teamId}/integrations/webhook

Enregistrer une nouvelle URL de webhook pour l’équipe

Paramètres du chemin :

Corps de la requête :

{
  "url": "https://example.com/webhook",
  "name": "My Webhook"
}

Réponses :

DELETE /team/{teamId}/integrations/webhook

Désenregistrer une URL de webhook pour l’équipe

Paramètres du chemin :

Paramètres de requête :

Réponses :

GET /team/{teamId}/integrations/zapier/sample/list

Obtenir des exemples de données pour Zapier sous forme de tableau

Paramètres du chemin :

Réponses :

Intégrations utilisateur

POST /integrations/webhook

Enregistrer un nouveau webhook pour l’utilisateur

Corps de la requête :

{
  "url": "https://example.com/webhook",
  "name": "My Webhook"
}

Réponses :

DELETE /integrations/webhook

Désenregistrer un webhook pour l’utilisateur

Paramètres de requête :

Réponses :

Événements de webhook

Votre point de terminaison de webhook recevra des événements dans ce format :

{
  "event": "recording.completed",
  "fileId": "file789",
  "teamId": "team123",
  "data": {
    "url": "https://screenapp.io/recording/file789",
    "duration": 300,
    "status": "processed"
  }
}

Les événements courants incluent :

Gestion de fichiers

POST /files/{fileId}/tag

Ajouter un tag au fichier

Paramètres du chemin :

Corps de la requête :

{
  "key": "color",
  "value": "red"
}

DELETE /files/{fileId}/tag

Supprimer un tag du fichier

Paramètres du chemin :

Corps de la requête :

{
  "key": "color"
}

POST /files/{fileId}/ask/multimodal

Poser une question sur un fichier en utilisant plusieurs modèles d’IA

Paramètres du chemin :

Corps de la requête :

{
  "promptText": "Quels sont les points clés abordés ?",
  "mediaAnalysisOptions": {
    "transcript": {
      "segments": [
        {
          "start": 0,
          "end": 120
        }
      ]
    },
    "video": {
      "segments": [
        {
          "start": 0,
          "end": 120
        }
      ]
    },
    "screenshots": {
      "timestamps": [30, 60, 90]
    }
  }
}

Réponses :

Téléchargement de fichiers

POST /files/upload/{teamId}/{folderId}/url

Générer des URL pré-signées pour les téléchargements de fichiers

Paramètres du chemin :

Corps de la requête :

{
  "files": [
    {
      "contentType": "video/mp4",
      "name": "meeting-recording.mp4"
    }
  ]
}

Réponses :

POST /files/upload/{teamId}/{folderId}/finalize

Finaliser les fichiers téléchargés

Paramètres du chemin :

Corps de la requête :

{
  "file": {
    "fileId": "file123",
    "contentType": "video/mp4",
    "name": "Appel commercial",
    "description": "Appel commercial hebdomadaire avec le client",
    "recorderName": "John Doe",
    "recorderEmail": "john.doe@example.com"
  }
}

Réponses :

Téléchargement multipartie (pour les fichiers volumineux)

PUT /files/upload/multipart/init/{teamId}/{folderId}

Initialiser un téléchargement multipartie pour un fichier volumineux

Paramètres du chemin :

Corps de la requête :

{
  "contentType": "video/mp4"
}

Réponses :

Exemple de réponse :

{
  "success": true,
  "data": {
    "fileId": "file789",
    "uploadId": "upload123"
  }
}

PUT /files/upload/multipart/url/{teamId}/{folderId}/{fileId}/{uploadId}/{partNumber}

Obtenir l’URL de téléchargement pour une partie spécifique

Paramètres du chemin :

Corps de la requête :

{
  "contentType": "video/mp4"
}

Réponses :

Exemple de réponse :

{
  "success": true,
  "data": {
    "uploadUrl": "https://presigned-s3-url.com/part1"
  }
}

PUT /files/upload/multipart/finalize/{teamId}/{folderId}/{fileId}/{uploadId}

Finaliser un téléchargement multipartie

Paramètres du chemin :

Corps de la requête :

{
  "file": {
    "contentType": "video/mp4",
    "recorderName": "John Doe",
    "recorderEmail": "john@example.com",
    "name": "Mon enregistrement",
    "description": "Une session vidéo enregistrée",
    "notes": [
      {
        "text": "Point important discuté",
        "timestamp": 1234567890
      }
    ]
  }
}

Réponses :

PUT /files/upload/multipart/fallback/{teamId}/{folderId}/{fileId}/{partNumber}

Télécharger la partie du fichier via le backend (solution de repli)

Paramètres du chemin :

Données du formulaire :

Réponses :

Gestion de compte

POST /v2/account/tag

Ajouter un tag à l’utilisateur authentifié

Corps de la requête :

{
  "key": "color",
  "value": "red"
}

Réponses :

PUT /account/profile

Mettre à jour le profil de l’utilisateur authentifié

Corps de la requête :

{
  "firstName": "John",
  "lastName": "Doe",
  "name": "John Doe",
  "gender": "male",
  "userType": "user",
  "company": "Acme Inc",
  "role": "Developer",
  "goals": "Learn new technologies",
  "phoneNumber": "+1234567890",
  "location": "San Francisco, CA",
  "website": "https://example.com",
  "picture": "https://example.com/avatar.jpg",
  "provider": "local",
  "providerId": "12345",
  "primaryField": "development"
}

Réponses :

Fonctionnalités avancées

Analyse IA

Utilisez l’IA pour analyser vos enregistrements et obtenir des informations :

// Demander l'analyse IA d'un enregistrement
const analysis = await fetch(`/v2/files/${fileId}/ask/multimodal`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer VOTRE_JETON_API',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    promptText: "Quels sont les principaux points de discussion ?",
    mediaAnalysisOptions: {
      transcript: {
        segments: [{ start: 0, end: 300 }]
      },
      video: {
        segments: [{ start: 0, end: 300 }]
      }
    }
  })
});

Opérations par lots

Gérez efficacement plusieurs enregistrements :

// Marquer plusieurs enregistrements
async function batchTag(fileIds, tag) {
  const promises = fileIds.map(fileId => 
    fetch(`/v2/files/${fileId}/tag`, {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer VOTRE_JETON_API',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(tag)
    })
  );
  await Promise.all(promises);
}

Gestion des erreurs

Codes d’erreur courants

Format de réponse d’erreur

Les réponses d’erreur suivent généralement ce format :

{
  "success": false,
  "message": "Message d'erreur détaillé"
}

Exemples

Configuration des webhooks d’équipe

Les webhooks vous permettent de recevoir des mises à jour en temps réel lorsque les enregistrements sont traités :

// Enregistrer un nouveau webhook pour votre équipe
async function registerTeamWebhook(teamId, webhookUrl, webhookName) {
  const response = await fetch(`/v2/team/${teamId}/integrations/webhook`, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer VOTRE_JETON_API',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: webhookUrl,
      name: webhookName
    })
  });
  return await response.json();
}

// Exemple d'utilisation
const result = await registerTeamWebhook(
  'team123',
  'https://your-domain.com/webhooks/screenapp',
  'Mises à jour d'enregistrement'
);

Téléchargement et traitement d’un fichier volumineux

Pour les fichiers de plus de 100 Mo, utilisez le flux de téléchargement multipartie :

// 1. Initialiser le téléchargement
const initResponse = await fetch(`/v2/files/upload/multipart/init/${teamId}/${folderId}`, {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer VOTRE_JETON_API',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    contentType: 'video/mp4'
  })
});

const { data: { fileId, uploadId } } = await initResponse.json();

// 2. Diviser le fichier en morceaux et télécharger chaque partie
const CHUNK_SIZE = 5 * 1024 * 1024; // Morceaux de 5 Mo
const totalParts = Math.ceil(file.size / CHUNK_SIZE);

for (let partNumber = 1; partNumber <= totalParts; partNumber++) {
  // Obtenir l'URL de téléchargement pour cette partie
  const urlResponse = await fetch(
    `/v2/files/upload/multipart/url/${teamId}/${folderId}/${fileId}/${uploadId}/${partNumber}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Bearer VOTRE_JETON_API',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        contentType: 'video/mp4'
      })
    }
  );
  
  const { data: { uploadUrl } } = await urlResponse.json();
  
  // Créer le morceau à partir du fichier
  const start = (partNumber - 1) * CHUNK_SIZE;
  const end = Math.min(start + CHUNK_SIZE, file.size);
  const chunk = file.slice(start, end);
  
  // Télécharger le morceau directement sur S3
  await fetch(uploadUrl, {
    method: 'PUT',
    body: chunk,
    headers: {
      'Content-Type': 'video/mp4'
    }
  });
}

// 3. Finaliser le téléchargement
const finalizeResponse = await fetch(
  `/v2/files/upload/multipart/finalize/${teamId}/${folderId}/${fileId}/${uploadId}`,
  {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer VOTRE_JETON_API',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      file: {
        contentType: 'video/mp4',
        name: 'Enregistrement de réunion client',
        description: 'Revue trimestrielle avec le client',
        recorderName: 'Jane Smith',
        recorderEmail: 'jane@example.com'
      }
    })
  }
);

Obtenir les identifiants API dans le tableau de bord →