Anleitung

ScreenApp API- und SDK-Dokumentation

Die ScreenApps-API ermöglicht Ihnen die automatische Transkription, Zusammenfassung und Analyse von Video- und Audioinhalten

Von ScreenApp Team

ScreenApp API Dokumentation v2.0.0

Die ScreenApp API ermöglicht Ihnen die automatische Transkription, Zusammenfassung und Analyse von Video- und Audioinhalten. Perfekt für Unternehmen, die Kundenanrufe, Schulungsvideos und Meeting-Aufzeichnungen in großem Umfang verarbeiten möchten.

Hauptanwendungsfälle

✨ Beliebter Anwendungsfall: Kundendienstteams nutzen unsere API, um Supportanrufe automatisch zu transkribieren und Zusammenfassungen zu generieren, die dann über Webhooks mit ihrem CRM synchronisiert werden.

API-Zugangsdaten im Dashboard abrufen →

Plananforderungen & API-Zugriff

Um die ScreenApp API zu nutzen, benötigen Sie:

  1. Ein aktives Business-Plan-Abonnement
  2. API-Zugangsdaten von Ihrem ScreenApp-Dashboard

Abrufen Ihrer API-Zugangsdaten

  1. Melden Sie sich bei Ihrem ScreenApp-Konto an
  2. Navigieren Sie zu Einstellungen → Integration
  3. Hier finden Sie Ihre:
    • API-Token
    • Team-ID

Bewahren Sie diese Zugangsdaten sicher auf und geben Sie sie niemals öffentlich weiter.

Schnellstart

Möchten Sie sofort loslegen? Befolgen Sie diese Schritte, um ScreenApp in Ihre Website zu integrieren:

1. Installieren Sie das Plugin

Fügen Sie diesen Code zum HTML-Code Ihrer Website hinzu:

<script>
  // Plugin Installationscode hier
</script>

2. Fügen Sie die Auslöser-Schaltfläche hinzu

Fügen Sie Ihrer Seite eine Schaltfläche oder ein Auslöser-Element hinzu:

<button onclick="loadScreenApp()">Aufnahme starten</button>

3. Konfigurieren Sie den Callback

Passen Sie die Callback-Funktion an, um den Abschluss der Aufnahme zu verarbeiten:

function callback({ id, url }) {
  // Beispiel: An Ihr Backend senden
  fetch('/api/recordings', {
    method: 'POST',
    body: JSON.stringify({ recordingId: id, recordingUrl: url })
  });
  
  // Beispiel: UI aktualisieren
  document.getElementById('status').innerHTML = 
    `Aufnahme gespeichert! Zeigen Sie sie unter ${url} an`;
}

Authentifizierung

Alle API-Anfragen erfordern eine Authentifizierung. ScreenApp verwendet Token-basierte Authentifizierung zusammen mit teamspezifischen Kennungen.

Zugangsdaten, die Sie benötigen

Authentifizierungsbeispiel

curl -X POST "https://api.screenapp.io/v2/files/upload" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "X-Team-ID: YOUR_TEAM_ID"

Authentifizierungs-Endpunkte

GET /auth/google

Weiterleitung zu Google zur Authentifizierung

Query-Parameter:

GET /auth/facebook

Weiterleitung zu Facebook zur Authentifizierung

Query-Parameter:

Kernkonzepte

Bevor wir in spezifische Endpunkte eintauchen, lassen Sie uns die Schlüsselkonzepte in ScreenApp verstehen:

  1. Aufzeichnungen: Video- und Audioaufnahmen, die hochgeladen und verarbeitet werden können
  2. Teams: Gruppen, die Aufzeichnungen gemeinsam nutzen und verwalten können
  3. Webhooks: Echtzeitbenachrichtigungen für Aufnahmeereignisse und Verarbeitungsergebnisse
  4. Tags: Metadaten, die an Aufzeichnungen, Teams oder Benutzerprofile angehängt werden können

API-Referenz

Team-Management

POST /team/{teamId}/tag

Tag zum Team hinzufügen

Pfadparameter:

Anfrage-Body:

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

DELETE /team/{teamId}/tag

Tag aus dem Team entfernen

Pfadparameter:

Anfrage-Body:

{
  "key": "color"
}

Team-Webhook-Integration

POST /team/{teamId}/integrations/webhook

Registrieren Sie eine neue Webhook-URL für das Team

Pfadparameter:

Anfrage-Body:

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

Antworten:

DELETE /team/{teamId}/integrations/webhook

Heben Sie die Registrierung einer Webhook-URL für das Team auf

Pfadparameter:

Query-Parameter:

Antworten:

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

Beispieldaten für Zapier als Array abrufen

Pfadparameter:

Antworten:

Benutzerintegrationen

POST /integrations/webhook

Registrieren Sie einen neuen Webhook für den Benutzer

Anfrage-Body:

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

Antworten:

DELETE /integrations/webhook

Heben Sie die Registrierung eines Webhooks für den Benutzer auf

Query-Parameter:

Antworten:

Webhook-Ereignisse

Ihr Webhook-Endpunkt empfängt Ereignisse in diesem Format:

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

Häufige Ereignisse umfassen:

Dateiverwaltung

POST /files/{fileId}/tag

Tag zur Datei hinzufügen

Pfadparameter:

Anfrage-Body:

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

DELETE /files/{fileId}/tag

Tag aus der Datei entfernen

Pfadparameter:

Anfrage-Body:

{
  "key": "color"
}

POST /files/{fileId}/ask/multimodal

Stellen Sie eine Frage zu einer Datei mit mehreren KI-Modellen

Pfadparameter:

Anfrage-Body:

{
  "promptText": "Was sind die wichtigsten besprochenen Punkte?",
  "mediaAnalysisOptions": {
    "transcript": {
      "segments": [
        {
          "start": 0,
          "end": 120
        }
      ]
    },
    "video": {
      "segments": [
        {
          "start": 0,
          "end": 120
        }
      ]
    },
    "screenshots": {
      "timestamps": [30, 60, 90]
    }
  }
}

Antworten:

Datei-Upload

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

Generieren Sie vorab signierte URLs für Datei-Uploads

Pfadparameter:

Anfrage-Body:

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

Antworten:

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

Hochgeladene Dateien finalisieren

Pfadparameter:

Anfrage-Body:

{
  "file": {
    "fileId": "file123",
    "contentType": "video/mp4",
    "name": "Sales Call",
    "description": "Wöchentlicher Verkaufsanruf mit Kunde",
    "recorderName": "John Doe",
    "recorderEmail": "john.doe@example.com"
  }
}

Antworten:

Multipart-Upload (für große Dateien)

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

Initialisieren Sie einen Multipart-Upload für eine große Datei

Pfadparameter:

Anfrage-Body:

{
  "contentType": "video/mp4"
}

Antworten:

Beispielantwort:

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

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

Upload-URL für einen bestimmten Teil abrufen

Pfadparameter:

Anfrage-Body:

{
  "contentType": "video/mp4"
}

Antworten:

Beispielantwort:

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

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

Multipart-Upload abschließen

Pfadparameter:

Anfrage-Body:

{
  "file": {
    "contentType": "video/mp4",
    "recorderName": "John Doe",
    "recorderEmail": "john@example.com",
    "name": "Meine Aufnahme",
    "description": "Eine aufgezeichnete Videositzung",
    "notes": [
      {
        "text": "Wichtiger besprochener Punkt",
        "timestamp": 1234567890
      }
    ]
  }
}

Antworten:

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

Datei-Teil über Backend hochladen (Fallback)

Pfadparameter:

Formulardaten:

Antworten:

Kontoverwaltung

POST /v2/account/tag

Fügen Sie dem authentifizierten Benutzer ein Tag hinzu

Anfrage-Body:

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

Antworten:

PUT /account/profile

Aktualisieren Sie das Profil des authentifizierten Benutzers

Anfrage-Body:

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

Antworten:

Erweiterte Funktionen

KI-Analyse

Verwenden Sie KI, um Ihre Aufnahmen auf Erkenntnisse zu analysieren:

// Fordern Sie eine KI-Analyse einer Aufnahme an
const analysis = await fetch(`/v2/files/${fileId}/ask/multimodal`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    promptText: "Was sind die wichtigsten Diskussionspunkte?",
    mediaAnalysisOptions: {
      transcript: {
        segments: [{ start: 0, end: 300 }]
      },
      video: {
        segments: [{ start: 0, end: 300 }]
      }
    }
  })
});

Batch-Operationen

Verwalten Sie mehrere Aufnahmen effizient:

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

Fehlerbehandlung

Häufige Fehlercodes

Fehlerantwortformat

Fehlerantworten folgen typischerweise diesem Format:

{
  "success": false,
  "message": "Detaillierte Fehlermeldung"
}

Beispiele

Einrichten von Team-Webhooks

Mit Webhooks können Sie Echtzeit-Updates erhalten, wenn Aufnahmen verarbeitet werden:

// Registrieren Sie einen neuen Webhook für Ihr Team
async function registerTeamWebhook(teamId, webhookUrl, webhookName) {
  const response = await fetch(`/v2/team/${teamId}/integrations/webhook`, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: webhookUrl,
      name: webhookName
    })
  });
  return await response.json();
}

// Beispielhafte Nutzung
const result = await registerTeamWebhook(
  'team123',
  'https://your-domain.com/webhooks/screenapp',
  'Aufnahme-Updates'
);

Hochladen und Verarbeiten einer großen Datei

Verwenden Sie für Dateien, die größer als 100 MB sind, den Multipart-Upload-Flow:

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

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

// 2. Datei in Chunks aufteilen und jeden Teil hochladen
const CHUNK_SIZE = 5 * 1024 * 1024; // 5MB Chunks
const totalParts = Math.ceil(file.size / CHUNK_SIZE);

for (let partNumber = 1; partNumber <= totalParts; partNumber++) {
  // Upload-URL für diesen Teil abrufen
  const urlResponse = await fetch(
    `/v2/files/upload/multipart/url/${teamId}/${folderId}/${fileId}/${uploadId}/${partNumber}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        contentType: 'video/mp4'
      })
    }
  );
  
  const { data: { uploadUrl } } = await urlResponse.json();
  
  // Chunk aus der Datei erstellen
  const start = (partNumber - 1) * CHUNK_SIZE;
  const end = Math.min(start + CHUNK_SIZE, file.size);
  const chunk = file.slice(start, end);
  
  // Chunk direkt auf S3 hochladen
  await fetch(uploadUrl, {
    method: 'PUT',
    body: chunk,
    headers: {
      'Content-Type': 'video/mp4'
    }
  });
}

// 3. Upload finalisieren
const finalizeResponse = await fetch(
  `/v2/files/upload/multipart/finalize/${teamId}/${folderId}/${fileId}/${uploadId}`,
  {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      file: {
        contentType: 'video/mp4',
        name: 'Kundenmeeting-Aufzeichnung',
        description: 'Vierteljährliche Überprüfung mit Kunde',
        recorderName: 'Jane Smith',
        recorderEmail: 'jane@example.com'
      }
    })
  }
);

API-Zugangsdaten im Dashboard abrufen →