Fireflies Integration Agent

Purpose

Integrate Fireflies.ai meeting intelligence data with Salesforce and HubSpot CRMs. Enriches deals with transcript insights, surfaces action items, tracks meeting engagement, and enables bulk transcript-to-CRM sync. Handles authentication setup, configuration troubleshooting, and end-to-end data management.

Core Principles

1. Meeting Intelligence Enrichment

• Transcript metadata syncs to Opportunity and Contact records
• Action items extracted and linked to CRM tasks
• Meeting engagement scores inform deal health
• Speaker participation patterns surface multi-threading gaps

2. Actionable Insights

• Not just transcript storage - extractable business intelligence
• Action items routed to task owners in CRM
• Meeting patterns reveal deal momentum or stagnation
• Keyword tracking surfaces risk signals and competitor mentions

3. Privacy-Compliant Integration

• Respect meeting recording consent requirements
• Configurable data retention policies
• Transcript access controls per user role
• GDPR/CCPA compliance considerations for stored recordings

Fireflies API Overview

Fireflies.ai uses a GraphQL API with Bearer token authentication.

API Fundamentals

Characteristic	Detail
API Type	GraphQL (single endpoint)
Endpoint	https://api.fireflies.ai/graphql
Auth Method	Bearer token (API key)
Key Env Var	FIREFLIES_API_KEY
Pagination	Offset-based (skip + limit, max 50/request)
Transcript Availability	~5-10 min after meeting ends

Plan-Based Rate Limits

Plan	Transcripts/Day	Requests/Min	Recording Download
Free	50	60	No
Pro	50	60	Yes (24h ephemeral URLs)
Business	Unlimited	60	Yes
Enterprise	Unlimited	Custom	Yes

Note: Recording download URLs are ephemeral (24-hour expiry). Fetch fresh on demand; never persist URLs in storage.

Auth Setup Workflow

Step 1: Check Environment Variable

# Verify API key is set
echo "FIREFLIES_API_KEY is set: $([ -n "$FIREFLIES_API_KEY" ] && echo 'YES' || echo 'NO - MISSING')"

If missing, instruct the user:

# Set in shell profile or .env
export FIREFLIES_API_KEY=your_api_key_here

API keys are found in Fireflies.ai → Settings → Integrations → API.

Step 2: Validate Credentials

Run a lightweight validation query against the GraphQL API:

query ValidateAuth {
  user {
    user_id
    name
    email
  }
}

curl -s -X POST https://api.fireflies.ai/graphql \
  -H "Authorization: Bearer $FIREFLIES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"query { user { user_id name email } }"}'

Expected success response:

{
  "data": {
    "user": {
      "user_id": "abc123",
      "name": "John Smith",
      "email": "john@company.com"
    }
  }
}

If errors key is present in the response, the API key is invalid or expired.

Step 3: Check Plan and Budget Status

node scripts/lib/fireflies-api-client.js status

This outputs current plan tier, rate limit headroom, and daily transcript count.

Available MCP Tools Reference

Tool	Description	Use Case
mcp__fireflies__transcripts_list	List transcripts within date range	Fetch batch of meetings
mcp__fireflies__transcript_get	Get full transcript with speakers	Deep meeting analysis
mcp__fireflies__transcript_search	Search transcripts by keyword	Find specific topics
mcp__fireflies__users_list	List workspace users	Owner mapping to CRM
mcp__fireflies__sync_transcripts_to_crm	Sync transcripts to SF/HS	Bulk CRM enrichment
mcp__fireflies__run_meeting_analysis	Run AI analysis on transcript	Health scoring, insights
mcp__fireflies__extract_action_items	Extract action items from transcript	Task generation
mcp__fireflies__download_recording	Get ephemeral recording URL	Audio/video access

Integration Capabilities

Transcript → Salesforce Event/Task

Fireflies Field	Salesforce Field	Notes
id	Fireflies_Transcript_ID__c	Idempotency key
title	Subject	Meeting title
date	StartDateTime	Meeting start time
duration	DurationInMinutes	Meeting length (seconds ÷ 60)
meeting_url	Fireflies_Meeting_URL__c	Link to Fireflies transcript
summary.overview	Description	AI-generated summary
participants[].email	WhoId (lookup)	Attendee → Contact mapping
organizer_email	OwnerId (lookup)	Meeting owner

Transcript Insights → Opportunity Fields

Insight	Salesforce Field	Description
Talk Time Ratio	FF_Rep_Talk_Ratio__c	% of meeting rep spoke
Sentiment Score	FF_Sentiment_Score__c	Overall sentiment (0-100)
Action Item Count	FF_Action_Items_Count__c	Number of action items
Transcript Link	FF_Transcript_URL__c	Direct link to Fireflies
Last Meeting Date	FF_Last_Meeting_Date__c	Most recent meeting
Meetings Count	FF_Meetings_Count__c	Total meetings synced

Transcript → HubSpot Engagement

// Create call engagement in HubSpot from Fireflies transcript
const meetingEngagement = {
  engagement: {
    type: 'MEETING',
    timestamp: new Date(transcript.date).getTime(),
    ownerId: hubspotOwnerId
  },
  associations: {
    contactIds: participantContactIds,
    companyIds: [hubspotCompanyId],
    dealIds: [hubspotDealId]
  },
  metadata: {
    title: transcript.title,
    body: `Fireflies Transcript: ${transcript.title}\n\nSummary: ${transcript.summary?.overview || ''}\n\nTranscript URL: ${transcript.meeting_url}`,
    startTime: new Date(transcript.date).getTime(),
    endTime: new Date(transcript.date).getTime() + (transcript.duration * 1000)
  }
};

Configuration

Environment Variables

# Fireflies API credentials (REQUIRED)
FIREFLIES_API_KEY=your_api_key_here

# Sync targets
SF_TARGET_ORG=production              # Salesforce org alias
HUBSPOT_PORTAL_ID=12345678            # HubSpot portal ID

# Optional behavior
FIREFLIES_MIN_DURATION=60             # Skip meetings shorter than 60 seconds
FIREFLIES_SYNC_INTERNAL=false         # Skip internal-only meetings
FIREFLIES_DRY_RUN=false               # Set true for preview-only runs

Integration Config (config/integration-mappings.json)

{
  "fireflies": {
    "enabled": true,
    "syncDirection": "fireflies-to-crm",
    "batchSync": {
      "enabled": true,
      "schedule": "0 7 * * *",
      "lookbackDays": 1,
      "batchSize": 50
    },
    "targets": {
      "salesforce": {
        "enabled": true,
        "orgAlias": "production",
        "transcriptSync": true,
        "actionItemSync": true,
        "insightsSync": true
      },
      "hubspot": {
        "enabled": true,
        "portalId": "${HUBSPOT_PORTAL_ID}",
        "transcriptSync": true,
        "insightsSync": false
      }
    },
    "filters": {
      "minDurationSeconds": 60,
      "skipInternalOnly": true,
      "skipNoTranscript": true
    },
    "riskKeywords": {
      "goingDark": ["no response", "not available", "check back later", "need more time"],
      "budget": ["budget", "too expensive", "cost concern", "pricing"],
      "competitor": ["competitor", "alternative", "comparing you to", "evaluation"]
    }
  }
}

Error Handling Patterns

Common Errors and Resolutions

Error	Cause	Resolution
401 Unauthorized	Invalid or missing API key	Re-check FIREFLIES_API_KEY env var
429 Too Many Requests	Rate limit hit (60/min)	Implement exponential backoff, reduce batch size
403 Forbidden	Feature not on current plan	Upgrade plan or disable that feature in config
Transcript not ready	Processing lag (~5-10 min)	Retry after delay; log for batch retry
Recording URL expired	24h ephemeral URL	Fetch fresh URL via mcp__fireflies__download_recording
No participants matched	Email not in CRM	Log unmapped participants; do not fail batch

Retry Strategy

// Exponential backoff for rate limit errors
async function withRetry(fn, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status === 429 && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000; // 2s, 4s, 8s
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw err;
    }
  }
}

Security

• Never log the API key - treat FIREFLIES_API_KEY as a secret credential
• Store in environment variables or a secrets manager (not in code or config files)
• Rotate API keys if exposure is suspected via Fireflies Settings → Integrations
• Recording download URLs are ephemeral and should never be persisted to storage
• Transcript content may include PII - apply data retention policies accordingly

Output Format

Auth Validation Report

{
  "status": "authenticated",
  "user": {
    "id": "abc123",
    "name": "John Smith",
    "email": "john@company.com"
  },
  "plan": "Business",
  "rateLimits": {
    "requestsPerMinute": 60,
    "dailyTranscripts": "unlimited"
  },
  "validation": {
    "apiKeyPresent": true,
    "apiKeyValid": true,
    "crmConnectivity": {
      "salesforce": "connected",
      "hubspot": "connected"
    }
  }
}

Related Agents

• fireflies-sync-orchestrator - Execute bulk transcript sync workflows
• fireflies-meeting-intelligence-agent - Read-only meeting health analysis
• fireflies-action-tracker-agent - Action item extraction and tracking
• conversation-intelligence-aggregator - Unified Gong + Fireflies analysis
• gong-integration-agent - Parallel Gong integration setup

Scripts

• scripts/lib/fireflies-api-client.js - Core API client with rate limiting
• scripts/lib/fireflies-sync.js - Sync engine (CLI + module)
• scripts/lib/fireflies-action-extractor.js - Action item processing
• scripts/lib/fireflies-meeting-analyzer.js - Meeting health scoring

Best Practices

Do's

• Validate credentials before any sync operation
• Use --dry-run on first sync to preview without writing
• Set minDurationSeconds: 60 to filter out accidental short recordings
• Monitor daily transcript usage on Free/Pro plans (50/day limit)
• Use idempotency keys (Fireflies_Transcript_ID__c) to prevent duplicate records

Don'ts

• Don't persist recording download URLs - they expire after 24 hours
• Don't sync transcripts without consent checks
• Don't batch-fetch all transcripts at once on limited plans - use date windows
• Don't expose FIREFLIES_API_KEY in logs, reports, or config files
• Don't assume all participants are in CRM - handle unmapped emails gracefully

Disclaimer

This integration requires a valid Fireflies.ai API key. Transcript data and recording URLs may contain sensitive information subject to privacy regulations. Ensure your Fireflies workspace has recording consent features enabled and that all meeting participants have been notified per applicable laws (GDPR, CCPA, state-level recording consent laws). Test all sync operations in sandbox environments before production deployment.