API de Demodesk

Configuración — Obtén Tu Clave API

Verifica .env para DEMODESK_API_KEY. Si falta, sigue una de las opciones abajo.

Opción A: Auto-extraer (si has iniciado sesión en Demodesk en navegador)

Extrae la clave API desde una sesión de navegador de Demodesk con sesión iniciada. Se vuelve a la Opción B si la extracción de cookie falla.

# 1. Obtén cookie de sesión desde almacén de cookies de Chrome (macOS)
SESSION_COOKIE=$(sqlite3 "$HOME/Library/Application Support/Google/Chrome/Default/Cookies" \
  "SELECT encrypted_value FROM cookies WHERE host_key='.demodesk.com' AND name='_demodesk_session'" 2>/dev/null)

# 2. Intercambia cookie de sesión por token Bearer
BEARER=$(curl -s -X POST "https://demodesk.com/api/v1/users/login" \
  -H "Cookie: _demodesk_session=$SESSION_COOKIE" \
  | python3 -c "import sys,json,base64; print(base64.b64decode(json.load(sys.stdin)['meta']['access_token']).decode())")

# 3. Extrae encabezados de auth desde paquete Bearer decodificado
ACCESS_TOKEN=$(echo "$BEARER" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['access_token'])")
CLIENT=$(echo "$BEARER" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['client'])")
UID_VAL=$(echo "$BEARER" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['uid'])")

# 4. Obtén clave API existente (o genera una nueva)
API_KEY=$(curl -s "https://demodesk.com/api/v1/users/show_api_key" \
  -H "access-token: $ACCESS_TOKEN" -H "client: $CLIENT" -H "uid: $UID_VAL" -H "token-type: Bearer" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['api_key'])")

# 5. Guarda en .env
echo "export DEMODESK_API_KEY=$API_KEY" >> .env
grep -qxF '.env' .gitignore 2>/dev/null || echo '.env' >> .gitignore

Nota: El descifrado de cookie de Chrome es dependiente del SO (macOS usa Keychain, Linux usa DPAPI/kwallet). Intenta esto como esfuerzo máximo y vuelve a la Opción B si falla.

Opción B: Copiar desde configuración

1. Abre https://demodesk.com/manage/settings/internet-accounts#:~:text=API%20Key
2. Haz clic en el icono del ojo para revelar la clave (o "Generar Clave API" si eres admin)
3. Guárdala:

echo 'export DEMODESK_API_KEY=pega-tu-clave-aqui' >> .env
grep -qxF '.env' .gitignore 2>/dev/null || echo '.env' >> .gitignore

Opción C: Navegación manual

Configuración > Integraciones > Conexiones > desplázate a la sección Clave API.

Importante

• La palabra clave export es requerida en .env — sin ella, source .env establece la variable pero los subprocesos (como curl) no la verán.
• Siempre añade .env a .gitignore si no está ya allí.
• La clave API hereda permisos del usuario que la creó. Las claves de admin tienen acceso a nivel empresa.

Cargando la Clave

source .env && curl -s -H "api-key: $DEMODESK_API_KEY" "https://demodesk.com/api/v2/recordings?limit=5"

Siempre verifica que la clave no esté vacía después de hacer source: [ -z "$DEMODESK_API_KEY" ] && echo "Clave faltante" && exit 1

Gotchas Conocidas

1. Los errores de límite de tasa devuelven {"error":{"code":"invalid_api_key"}} no 429. Si la clave funcionaba antes, espera 60 segundos e intenta de nuevo. No asumas que la clave está mal.
2. Los corchetes de filtro necesitan codificación URL: usa %5B / %5D en lugar de [ / ].
3. Siempre captura la respuesta a $RESP antes de hacer pipe a jq — las respuestas de error causan crash en jq.
4. No hay endpoint /users — obtén el propietario de la reunión a través del endpoint de detalle de grabación y filtra para permission:"host" en el array de participantes.

Referencia API en Vivo

Para esquemas de endpoint, filtros y campos de respuesta, obtén la especificación OpenAPI en vivo:

curl -s https://demodesk.com/api/docs/v2/generated.yaml | head -500

Nunca confíes en esquemas memorizados — siempre verifica la especificación en vivo para nombres de campo actuales, parámetros de filtro, valores de enumeración y límites de tasa.

Referencia Rápida (solo paths)

URLs Base

• V2: https://demodesk.com/api/v2
• V1: https://demodesk.com/api/v1

Paginación

Basada en cursor. limit acepta 1–100 (default 25). Verifica meta.hasNext en la respuesta — si es true, pasa meta.nextCursor como el parámetro de consulta cursor=.

Recetas

1. Listar grabaciones listas recientes (últimos 7 días)

source .env
RESP=$(curl -s -H "api-key: $DEMODESK_API_KEY" \
  "https://demodesk.com/api/v2/recordings?limit=100&filter%5Bstatus%5D=ready&filter%5BcreatedAfter%5D=$(date -v-7d +%Y-%m-%d)")
echo "$RESP" | jq '.data[] | {token, title, createdAt, duration}'

2. Descargar todas las grabaciones en lote

source .env
CURSOR=""
while true; do
  RESP=$(curl -s -H "api-key: $DEMODESK_API_KEY" \
    "https://demodesk.com/api/v2/recordings?limit=100&filter%5Bstatus%5D=ready${CURSOR:+&cursor=$CURSOR}")
  echo "$RESP" | jq -r '.data[] | .token' | while read -r TOKEN; do
    DETAIL=$(curl -s -H "api-key: $DEMODESK_API_KEY" \
      "https://demodesk.com/api/v2/recordings/$TOKEN")
    URL=$(echo "$DETAIL" | jq -r '.temporaryDirectUrl // empty')
    [ -n "$URL" ] && wget -q -O "${TOKEN}.mp4" "$URL"
    sleep 1  # consciente del límite de tasa
  done
  HAS_NEXT=$(echo "$RESP" | jq -r '.meta.hasNext')
  [ "$HAS_NEXT" != "true" ] && break
  CURSOR=$(echo "$RESP" | jq -r '.meta.nextCursor')
done

3. Obtener transcripción (texto plano + traducido)

source .env
# Texto plano en inglés
RESP=$(curl -s -H "api-key: $DEMODESK_API_KEY" \
  "https://demodesk.com/api/v2/recordings/TOKEN/transcript?format=plaintext")
echo "$RESP" | jq -r '.text'

# Traducción al alemán
RESP=$(curl -s -H "api-key: $DEMODESK_API_KEY" \
  "https://demodesk.com/api/v2/recordings/TOKEN/transcript?format=plaintext&lang=de")
echo "$RESP" | jq -r '.text'

Nota: Si la transcripción aún se está procesando, la API devuelve 202 — espera e intenta de nuevo.

4. Obtener transcripciones en lote (hasta 100 tokens)

source .env
RESP=$(curl -s -X POST -H "api-key: $DEMODESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recordingTokens": ["token1", "token2", "token3"]}' \
  "https://demodesk.com/api/v2/transcripts/batch")
echo "$RESP" | jq '.data'

5. Obtener nombre del propietario de reunión

source .env
RESP=$(curl -s -H "api-key: $DEMODESK_API_KEY" \
  "https://demodesk.com/api/v2/recordings/TOKEN")
echo "$RESP" | jq '.participants[] | select(.permission == "host") | .name'

V1: Subir Grabaciones Externas

source .env
curl -s -X POST -H "api-key: $DEMODESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Llamada Externa",
    "recording_url": "https://example.com/recording.mp4",
    "scheduled_at": "2025-01-15T10:00:00Z"
  }' \
  "https://demodesk.com/api/v1/externally_recorded_demos"

Webhooks

No es self-serve. Envía email a support@demodesk.com con la URL de tu endpoint.

Eventos disponibles: demo.scheduled, demo.rescheduled, demo.canceled, demo.started, demo.ended, recording.uploaded, recording.transcription_postprocessed y más.

Flujo de Trabajo para Asistentes de IA

1. Verifica .env para DEMODESK_API_KEY — si falta, ejecuta el flujo de configuración de arriba.
2. source .env y verifica que la clave no esté vacía.
3. Obtén la especificación OpenAPI en vivo si necesitas detalles de esquema para campos, filtros o enumeraciones.
4. Usa curl -s y captura la respuesta en una variable $RESP primero.
5. Verifica errores antes de hacer pipe a través de jq.
6. Usa limit=100 y filtra del lado del cliente cuando sea posible (consciente del límite de tasa).
7. Codifica URL los corchetes de filtro (%5B / %5D).
8. Maneja límites de tasa: error invalid_api_key pero la clave funcionaba antes → espera 60 segundos.
9. Maneja respuestas 202 (transcripción aún procesándose) → espera e intenta de nuevo.
10. Maneja paginación: verifica meta.hasNext, usa meta.nextCursor.