Guida pratica

Documentazione API e SDK di ScreenApp

L'API di ScreenApps ti consente di trascrivere, riassumere e analizzare automaticamente contenuti video e audio

Di Team ScreenApp

Documentazione API ScreenApp v2.0.0

L’API di ScreenApp ti consente di trascrivere, riassumere e analizzare automaticamente contenuti video e audio. Perfetto per le aziende che desiderano elaborare chiamate dei clienti, video di formazione e registrazioni di riunioni su larga scala.

Principali casi d’uso

✨ Caso d’uso popolare: i team di assistenza clienti utilizzano la nostra API per trascrivere automaticamente le chiamate di supporto e generare riepiloghi, che vengono poi sincronizzati con il loro CRM tramite webhook.

Ottieni le credenziali API nella dashboard →

Requisiti del piano e accesso API

Per utilizzare l’API ScreenApp, avrai bisogno di:

  1. Un abbonamento attivo al piano Business
  2. Credenziali API dalla tua dashboard ScreenApp

Ottenere le credenziali API

  1. Accedi al tuo account ScreenApp
  2. Vai su Impostazioni → Integrazione
  3. Qui troverai:
    • Token API
    • ID team

Conserva queste credenziali in modo sicuro e non condividerle mai pubblicamente.

Guida rapida

Vuoi iniziare subito? Segui questi passaggi per integrare ScreenApp nel tuo sito web:

1. Installa il plugin

Aggiungi questo codice all’HTML del tuo sito web:

<script>
  // Codice di installazione del plugin qui
</script>

2. Aggiungi il pulsante di attivazione

Aggiungi un pulsante o un elemento di attivazione alla tua pagina:

<button onclick="loadScreenApp()">Avvia registrazione</button>

3. Configura il callback

Personalizza la funzione di callback per gestire il completamento della registrazione:

function callback({ id, url }) {
  // Esempio: invia al tuo backend
  fetch('/api/recordings', {
    method: 'POST',
    body: JSON.stringify({ recordingId: id, recordingUrl: url })
  });
  
  // Esempio: aggiorna l'interfaccia utente
  document.getElementById('status').innerHTML = 
    `Registrazione salvata! Visualizzala all'indirizzo ${url}`;
}

Autenticazione

Tutte le richieste API richiedono l’autenticazione. ScreenApp utilizza l’autenticazione basata su token insieme a identificatori specifici del team.

Credenziali necessarie

Esempio di autenticazione

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

Endpoint di autenticazione

GET /auth/google

Reindirizza a Google per l’autenticazione

Parametri della query:

GET /auth/facebook

Reindirizza a Facebook per l’autenticazione

Parametri della query:

Concetti chiave

Prima di approfondire endpoint specifici, comprendiamo i concetti chiave di ScreenApp:

  1. Registrazioni: acquisizioni video e audio che possono essere caricate ed elaborate
  2. Team: gruppi che possono condividere e gestire le registrazioni
  3. Webhook: notifiche in tempo reale per eventi di registrazione e risultati di elaborazione
  4. Tag: metadati che possono essere allegati a registrazioni, team o profili utente

Riferimento API

Gestione del team

POST /team/{teamId}/tag

Aggiungi tag al team

Parametri del percorso:

Corpo della richiesta:

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

DELETE /team/{teamId}/tag

Rimuovi tag dal team

Parametri del percorso:

Corpo della richiesta:

{
  "key": "color"
}

Integrazione webhook del team

POST /team/{teamId}/integrations/webhook

Registra un nuovo URL webhook per il team

Parametri del percorso:

Corpo della richiesta:

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

Risposte:

DELETE /team/{teamId}/integrations/webhook

Annulla la registrazione di un URL webhook per il team

Parametri del percorso:

Parametri della query:

Risposte:

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

Ottieni dati di esempio per Zapier come array

Parametri del percorso:

Risposte:

Integrazioni utente

POST /integrations/webhook

Registra un nuovo webhook per l’utente

Corpo della richiesta:

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

Risposte:

DELETE /integrations/webhook

Annulla la registrazione di un webhook per l’utente

Parametri della query:

Risposte:

Eventi Webhook

L’endpoint webhook riceverà eventi in questo formato:

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

Gli eventi comuni includono:

Gestione dei file

POST /files/{fileId}/tag

Aggiungi tag al file

Parametri del percorso:

Corpo della richiesta:

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

DELETE /files/{fileId}/tag

Rimuovi tag dal file

Parametri del percorso:

Corpo della richiesta:

{
  "key": "color"
}

POST /files/{fileId}/ask/multimodal

Poni una domanda su un file utilizzando più modelli di intelligenza artificiale

Parametri del percorso:

Corpo della richiesta:

{
  "promptText": "Quali sono i punti chiave discussi?",
  "mediaAnalysisOptions": {
    "transcript": {
      "segments": [
        {
          "start": 0,
          "end": 120
        }
      ]
    },
    "video": {
      "segments": [
        {
          "start": 0,
          "end": 120
        }
      ]
    },
    "screenshots": {
      "timestamps": [30, 60, 90]
    }
  }
}

Risposte:

Caricamento file

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

Genera URL pre-firmati per il caricamento di file

Parametri del percorso:

Corpo della richiesta:

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

Risposte:

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

Finalizza i file caricati

Parametri del percorso:

Corpo della richiesta:

{
  "file": {
    "fileId": "file123",
    "contentType": "video/mp4",
    "name": "Chiamata di vendita",
    "description": "Chiamata di vendita settimanale con il cliente",
    "recorderName": "John Doe",
    "recorderEmail": "john.doe@example.com"
  }
}

Risposte:

Caricamento in più parti (per file di grandi dimensioni)

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

Inizializza un caricamento in più parti per un file di grandi dimensioni

Parametri del percorso:

Corpo della richiesta:

{
  "contentType": "video/mp4"
}

Risposte:

Esempio di risposta:

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

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

Ottieni l’URL di caricamento per una parte specifica

Parametri del percorso:

Corpo della richiesta:

{
  "contentType": "video/mp4"
}

Risposte:

Esempio di risposta:

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

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

Finalizza un caricamento in più parti

Parametri del percorso:

Corpo della richiesta:

{
  "file": {
    "contentType": "video/mp4",
    "recorderName": "John Doe",
    "recorderEmail": "john@example.com",
    "name": "La mia registrazione",
    "description": "Una sessione video registrata",
    "notes": [
      {
        "text": "Punto importante discusso",
        "timestamp": 1234567890
      }
    ]
  }
}

Risposte:

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

Carica la parte del file tramite backend (fallback)

Parametri del percorso:

Dati del modulo:

Risposte:

Gestione account

POST /v2/account/tag

Aggiungi un tag all’utente autenticato

Corpo della richiesta:

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

Risposte:

PUT /account/profile

Aggiorna il profilo dell’utente autenticato

Corpo della richiesta:

{
  "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"
}

Risposte:

Funzionalità avanzate

Analisi IA

Usa l’IA per analizzare le tue registrazioni e ottenere informazioni dettagliate:

// Richiedi l'analisi IA di una registrazione
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: "Quali sono i punti di discussione chiave?",
    mediaAnalysisOptions: {
      transcript: {
        segments: [{ start: 0, end: 300 }]
      },
      video: {
        segments: [{ start: 0, end: 300 }]
      }
    }
  })
});

Operazioni batch

Gestisci in modo efficiente più registrazioni:

// Tagga più registrazioni
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);
}

Gestione degli errori

Codici di errore comuni

Formato della risposta di errore

Le risposte di errore in genere seguono questo formato:

{
  "success": false,
  "message": "Messaggio di errore dettagliato"
}

Esempi

Impostazione dei webhook del team

I webhook ti consentono di ricevere aggiornamenti in tempo reale quando le registrazioni vengono elaborate:

// Registra un nuovo webhook per il tuo 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();
}

// Esempio di utilizzo
const result = await registerTeamWebhook(
  'team123',
  'https://your-domain.com/webhooks/screenapp',
  'Aggiornamenti di registrazione'
);

Caricamento ed elaborazione di un file di grandi dimensioni

Per i file di dimensioni superiori a 100 MB, utilizzare il flusso di caricamento in più parti:

// 1. Inizializza il caricamento
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. Dividi il file in blocchi e carica ogni parte
const CHUNK_SIZE = 5 * 1024 * 1024; // Blocchi da 5 MB
const totalParts = Math.ceil(file.size / CHUNK_SIZE);

for (let partNumber = 1; partNumber <= totalParts; partNumber++) {
  // Ottieni l'URL di caricamento per questa parte
  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();
  
  // Crea il blocco dal file
  const start = (partNumber - 1) * CHUNK_SIZE;
  const end = Math.min(start + CHUNK_SIZE, file.size);
  const chunk = file.slice(start, end);
  
  // Carica il blocco direttamente su S3
  await fetch(uploadUrl, {
    method: 'PUT',
    body: chunk,
    headers: {
      'Content-Type': 'video/mp4'
    }
  });
}

// 3. Finalizza il caricamento
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: 'Registrazione della riunione con il cliente',
        description: 'Revisione trimestrale con il cliente',
        recorderName: 'Jane Smith',
        recorderEmail: 'jane@example.com'
      }
    })
  }
);

Ottieni le credenziali API nella dashboard →