Fireflies.ai Migration Deep Dive

Current State

!

npm list graphql graphql-request 2>/dev/null || echo 'No graphql packages'

Overview

Migrate to Fireflies.ai from other transcription platforms or custom recording systems. Covers historical recording import via

uploadAudio

Migration Types

uploadAudio

Instructions

Step 1: Pre-Migration Assessment

// Inventory your current meeting data
interface MigrationInventory {
  totalRecordings: number;
  totalHours: number;
  formats: string[];        // mp3, mp4, wav, m4a, ogg
  averageDuration: number;  // minutes
  dateRange: { oldest: string; newest: string };
  platforms: string[];      // Zoom, Teams, etc.
}

// Fireflies supports: mp3, mp4, wav, m4a, ogg
// Size limits: 200MB audio, 100MB video (free), 1.5GB video (paid)
// Minimum: 50KB (can bypass with bypass_size_check: true)

Step 2: Batch Upload Historical Recordings

const FIREFLIES_API = "https://api.fireflies.ai/graphql";

interface UploadJob {
  url: string;        // Must be publicly accessible HTTPS URL
  title: string;
  attendees?: { displayName: string; email: string }[];
  referenceId: string; // Your internal ID for tracking
}

async function batchUpload(jobs: UploadJob[]) {
  const results: { id: string; status: string; error?: string }[] = [];

  for (const job of jobs) {
    try {
      const res = await fetch(FIREFLIES_API, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${process.env.FIREFLIES_API_KEY}`,
        },
        body: JSON.stringify({
          query: `
            mutation($input: AudioUploadInput) {
              uploadAudio(input: $input) {
                success title message
              }
            }
          `,
          variables: {
            input: {
              url: job.url,
              title: job.title,
              attendees: job.attendees,
              client_reference_id: job.referenceId,
              webhook: process.env.WEBHOOK_URL,
            },
          },
        }),
      });

      const json = await res.json();
      if (json.errors) {
        results.push({ id: job.referenceId, status: "error", error: json.errors[0].message });
      } else {
        results.push({ id: job.referenceId, status: "uploaded" });
      }
    } catch (err) {
      results.push({ id: job.referenceId, status: "error", error: (err as Error).message });
    }

    // Rate limit: wait between uploads
    await new Promise(r => setTimeout(r, 2000));
  }

  return results;
}

Step 3: Upload with Authenticated URLs

If your recordings are behind auth (S3, GCS):

// Bearer token auth (e.g., pre-signed URLs with auth headers)
const upload = {
  url: "https://storage.example.com/recordings/meeting-123.mp3",
  title: "Q1 Planning",
  download_auth: {
    type: "bearer_token",
    bearer: { token: "your-storage-access-token" },
  },
  client_reference_id: "meeting-123",
};

// Basic auth
const uploadBasicAuth = {
  url: "https://recordings.example.com/files/meeting-456.mp3",
  title: "Sprint Review",
  download_auth: {
    type: "basic_auth",
    basic: { username: "api-user", password: "api-pass" },
  },
  client_reference_id: "meeting-456",
};

Step 4: Direct File Upload (No Public URL)

For files that can't be made publicly accessible:

// Step 1: Get a pre-signed upload URL from Fireflies
const { createUploadUrl } = await firefliesQuery(`
  mutation($input: CreateUploadUrlInput!) {
    createUploadUrl(input: $input) {
      url
      meeting_id
    }
  }
`, { input: { /* file metadata */ } });

// Step 2: Upload file directly to the pre-signed URL
await fetch(createUploadUrl.url, {
  method: "PUT",
  body: fileBuffer,
});

// Step 3: Confirm the upload
await firefliesQuery(`
  mutation($input: ConfirmUploadInput!) {
    confirmUpload(input: $input) {
      success
    }
  }
`, { input: { meeting_id: createUploadUrl.meeting_id } });

Step 5: Track Migration Progress via Webhooks

// Webhook handler tracks which uploads have completed
const migrationTracker = new Map<string, { status: string; meetingId?: string }>();

async function handleMigrationWebhook(event: any) {
  if (event.eventType === "Transcription completed" && event.clientReferenceId) {
    migrationTracker.set(event.clientReferenceId, {
      status: "completed",
      meetingId: event.meetingId,
    });

    // Check progress
    const completed = [...migrationTracker.values()].filter(v => v.status === "completed").length;
    const total = migrationTracker.size;
    console.log(`Migration progress: ${completed}/${total} (${Math.round(completed/total*100)}%)`);
  }
}

Step 6: Validate Migration

async function validateMigration(expectedIds: string[]) {
  const results = {
    found: 0,
    missing: [] as string[],
    hasSummary: 0,
    hasSentences: 0,
  };

  for (const refId of expectedIds) {
    const tracker = migrationTracker.get(refId);
    if (!tracker?.meetingId) {
      results.missing.push(refId);
      continue;
    }

    results.found++;

    // Verify transcript quality
    const { transcript } = await firefliesQuery(`
      query($id: String!) {
        transcript(id: $id) {
          id title
          sentences { text }
          summary { overview action_items }
        }
      }
    `, { id: tracker.meetingId });

    if (transcript.summary?.overview) results.hasSummary++;
    if (transcript.sentences?.length > 0) results.hasSentences++;

    await new Promise(r => setTimeout(r, 1100)); // Rate limit
  }

  console.log(`Validation: ${results.found}/${expectedIds.length} found`);
  console.log(`With summary: ${results.hasSummary}`);
  console.log(`With sentences: ${results.hasSentences}`);
  console.log(`Missing: ${results.missing.length}`);

  return results;
}

Step 7: Adapter Pattern for Gradual Cutover

interface TranscriptionService {
  getTranscript(id: string): Promise<any>;
  searchTranscripts(query: string): Promise<any[]>;
}

class FirefliesService implements TranscriptionService {
  async getTranscript(id: string) {
    return firefliesQuery(`
      query($id: String!) {
        transcript(id: $id) {
          id title date duration
          sentences { speaker_name text start_time end_time }
          summary { overview action_items }
        }
      }
    `, { id });
  }

  async searchTranscripts(query: string) {
    const data = await firefliesQuery(`
      query($keyword: String) {
        transcripts(keyword: $keyword, limit: 20) {
          id title date duration
        }
      }
    `, { keyword: query });
    return data.transcripts;
  }
}

// Gradual cutover with feature flag
function getTranscriptionService(): TranscriptionService {
  if (process.env.USE_FIREFLIES === "true") {
    return new FirefliesService();
  }
  return new LegacyTranscriptionService();
}

Error Handling

payload_too_small

bypass_size_check: true

client_reference_id

Output

• Pre-migration inventory assessed
• Historical recordings uploaded via

  uploadAudio

  mutation
• Migration progress tracked via webhooks and

  clientReferenceId

• Post-migration validation confirming transcript quality
• Adapter layer enabling gradual platform cutover

Resources

• Upload Audio Mutation
• Fireflies API Docs

Next Steps

For monitoring the migrated system, see

fireflies-observability