Guía práctica

Documentación de la API y el SDK de ScreenApp

La API de ScreenApps le permite transcribir, resumir y analizar automáticamente contenido de vídeo y audio

Por Equipo ScreenApp

Documentación de la API de ScreenApp v2.0.0

La API de ScreenApp le permite transcribir, resumir y analizar automáticamente contenido de video y audio. Perfecto para empresas que buscan procesar llamadas de clientes, videos de capacitación y grabaciones de reuniones a escala.

Casos de uso clave

✨ Caso de uso popular: Los equipos de atención al cliente utilizan nuestra API para transcribir automáticamente las llamadas de soporte y generar resúmenes, que luego se sincronizan con su CRM a través de webhooks.

Obtener credenciales de API en el panel →

Requisitos del plan y acceso a la API

Para usar la API de ScreenApp, necesitará:

  1. Una suscripción activa al plan Business
  2. Credenciales de API de su panel de ScreenApp

Cómo obtener sus credenciales de API

  1. Inicie sesión en su cuenta de ScreenApp
  2. Vaya a Configuración → Integración
  3. Aquí encontrará su:
    • Token de API
    • ID del equipo

Mantenga estas credenciales seguras y nunca las comparta públicamente.

Inicio rápido

¿Quiere comenzar de inmediato? Siga estos pasos para integrar ScreenApp en su sitio web:

1. Instalar el plugin

Agregue este código al HTML de su sitio web:

<script>
  // Plugin installation code here
</script>

2. Agregar el botón de activación

Agregue un botón o elemento de activación a su página:

<button onclick="loadScreenApp()">Start Recording</button>

3. Configurar la devolución de llamada

Personalice la función de devolución de llamada para manejar la finalización de la grabación:

function callback({ id, url }) {
  // Ejemplo: Enviar a su backend
  fetch('/api/recordings', {
    method: 'POST',
    body: JSON.stringify({ recordingId: id, recordingUrl: url })
  });
  
  // Ejemplo: Actualizar la IU
  document.getElementById('status').innerHTML = 
    `Grabación guardada! Véala en ${url}`;
}

Autenticación

Todas las solicitudes de API requieren autenticación. ScreenApp utiliza autenticación basada en tokens junto con identificadores específicos del equipo.

Credenciales que necesitará

Ejemplo de autenticación

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

Puntos finales de autenticación

GET /auth/google

Redirigir a Google para la autenticación

Parámetros de consulta:

GET /auth/facebook

Redirigir a Facebook para la autenticación

Parámetros de consulta:

Conceptos básicos

Antes de sumergirnos en puntos finales específicos, comprendamos los conceptos clave en ScreenApp:

  1. Grabaciones: Capturas de video y audio que se pueden cargar y procesar
  2. Equipos: Grupos que pueden compartir y administrar grabaciones
  3. Webhooks: Notificaciones en tiempo real para eventos de grabación y resultados de procesamiento
  4. Etiquetas: Metadatos que se pueden adjuntar a grabaciones, equipos o perfiles de usuario

Referencia de la API

Gestión de equipos

POST /team/{teamId}/tag

Agregar etiqueta al equipo

Parámetros de ruta:

Cuerpo de la solicitud:

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

DELETE /team/{teamId}/tag

Eliminar etiqueta del equipo

Parámetros de ruta:

Cuerpo de la solicitud:

{
  "key": "color"
}

Integración de Webhook del equipo

POST /team/{teamId}/integrations/webhook

Registrar una nueva URL de webhook para el equipo

Parámetros de ruta:

Cuerpo de la solicitud:

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

Respuestas:

DELETE /team/{teamId}/integrations/webhook

Anular el registro de una URL de webhook para el equipo

Parámetros de ruta:

Parámetros de consulta:

Respuestas:

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

Obtener datos de muestra para Zapier como una matriz

Parámetros de ruta:

Respuestas:

Integraciones de usuario

POST /integrations/webhook

Registrar un nuevo webhook para el usuario

Cuerpo de la solicitud:

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

Respuestas:

DELETE /integrations/webhook

Anular el registro de un webhook para el usuario

Parámetros de consulta:

Respuestas:

Eventos de Webhook

Su punto final de webhook recibirá eventos en este formato:

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

Los eventos comunes incluyen:

Gestión de archivos

POST /files/{fileId}/tag

Agregar etiqueta al archivo

Parámetros de ruta:

Cuerpo de la solicitud:

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

DELETE /files/{fileId}/tag

Eliminar etiqueta del archivo

Parámetros de ruta:

Cuerpo de la solicitud:

{
  "key": "color"
}

POST /files/{fileId}/ask/multimodal

Hacer una pregunta sobre un archivo utilizando múltiples modelos de IA

Parámetros de ruta:

Cuerpo de la solicitud:

{
  "promptText": "What are the key points discussed?",
  "mediaAnalysisOptions": {
    "transcript": {
      "segments": [
        {
          "start": 0,
          "end": 120
        }
      ]
    },
    "video": {
      "segments": [
        {
          "start": 0,
          "end": 120
        }
      ]
    },
    "screenshots": {
      "timestamps": [30, 60, 90]
    }
  }
}

Respuestas:

Subida de archivos

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

Generar URL previamente firmadas para la carga de archivos

Parámetros de ruta:

Cuerpo de la solicitud:

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

Respuestas:

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

Finalizar archivos subidos

Parámetros de ruta:

Cuerpo de la solicitud:

{
  "file": {
    "fileId": "file123",
    "contentType": "video/mp4",
    "name": "Sales Call",
    "description": "Weekly sales call with customer",
    "recorderName": "John Doe",
    "recorderEmail": "john.doe@example.com"
  }
}

Respuestas:

Carga multiparte (para archivos grandes)

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

Inicializar una carga multiparte para un archivo grande

Parámetros de ruta:

Cuerpo de la solicitud:

{
  "contentType": "video/mp4"
}

Respuestas:

Ejemplo de respuesta:

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

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

Obtener la URL de carga para una parte específica

Parámetros de ruta:

Cuerpo de la solicitud:

{
  "contentType": "video/mp4"
}

Respuestas:

Ejemplo de respuesta:

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

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

Finalizar una carga multiparte

Parámetros de ruta:

Cuerpo de la solicitud:

{
  "file": {
    "contentType": "video/mp4",
    "recorderName": "John Doe",
    "recorderEmail": "john@example.com",
    "name": "My Recording",
    "description": "A recorded video session",
    "notes": [
      {
        "text": "Important point discussed",
        "timestamp": 1234567890
      }
    ]
  }
}

Respuestas:

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

Cargar parte del archivo a través del backend (fallback)

Parámetros de ruta:

Datos del formulario:

Respuestas:

Gestión de cuenta

POST /v2/account/tag

Agregar una etiqueta al usuario autenticado

Cuerpo de la solicitud:

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

Respuestas:

PUT /account/profile

Actualizar el perfil del usuario autenticado

Cuerpo de la solicitud:

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

Respuestas:

Características avanzadas

Análisis de IA

Utilice la IA para analizar sus grabaciones en busca de información:

// Solicitar análisis de IA de una grabación
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: "What are the key discussion points?",
    mediaAnalysisOptions: {
      transcript: {
        segments: [{ start: 0, end: 300 }]
      },
      video: {
        segments: [{ start: 0, end: 300 }]
      }
    }
  })
});

Operaciones por lotes

Administre eficientemente múltiples grabaciones:

// Etiquetar múltiples grabaciones
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);
}

Manejo de errores

Códigos de error comunes

Formato de respuesta de error

Las respuestas de error suelen seguir este formato:

{
  "success": false,
  "message": "Detailed error message"
}

Ejemplos

Configuración de Webhooks de equipo

Los webhooks le permiten recibir actualizaciones en tiempo real cuando se procesan las grabaciones:

// Registrar un nuevo webhook para su equipo
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();
}

// Ejemplo de uso
const result = await registerTeamWebhook(
  'team123',
  'https://your-domain.com/webhooks/screenapp',
  'Recording Updates'
);

Carga y procesamiento de un archivo grande

Para archivos de más de 100 MB, utilice el flujo de carga multiparte:

// 1. Inicializar la carga
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. Dividir el archivo en fragmentos y cargar cada parte
const CHUNK_SIZE = 5 * 1024 * 1024; // Fragmentos de 5MB
const totalParts = Math.ceil(file.size / CHUNK_SIZE);

for (let partNumber = 1; partNumber <= totalParts; partNumber++) {
  // Obtener la URL de carga para esta 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();
  
  // Crear el fragmento del archivo
  const start = (partNumber - 1) * CHUNK_SIZE;
  const end = Math.min(start + CHUNK_SIZE, file.size);
  const chunk = file.slice(start, end);
  
  // Cargar el fragmento directamente a S3
  await fetch(uploadUrl, {
    method: 'PUT',
    body: chunk,
    headers: {
      'Content-Type': 'video/mp4'
    }
  });
}

// 3. Finalizar la carga
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: 'Customer Meeting Recording',
        description: 'Quarterly review with client',
        recorderName: 'Jane Smith',
        recorderEmail: 'jane@example.com'
      }
    })
  }
);

Obtener credenciales de API en el panel →