twenty/packages/twenty-apps/public/fireflies/README.md

Fireflies for Twenty

Sync Fireflies call transcripts and AI summaries into CallRecording records linked to the matching CalendarEvent in your Twenty CRM — searchable, in context, and ready for AI agents and workflows to act on. Plus on-demand workflow tools to sync, list, and search Fireflies calls from the AI chat or workflow builder.

What this app does

1. Fireflies records and transcribes your Zoom / Meet / Teams / phone call.
2. When the transcript is ready, Fireflies fires a meeting.transcribed webhook; once Fireflies finishes its AI summary, it fires a separate meeting.summarized webhook.
3. For each event, this app fetches the relevant data via the Fireflies GraphQL API.
4. It upserts a CallRecording record (one per Fireflies call) with the diarized transcript and the AI summary, linked to the matching CalendarEvent when one is found.

Alongside the webhook, three Workflow tools let you trigger Fireflies actions from the AI chat or as steps inside a workflow, without waiting for Fireflies to push.

How a transcript is matched to a CalendarEvent

The matcher tries two provider-ID strategies in priority order and stops at the first hit:

1. Provider-native event ID — Fireflies' calendar_id / cal_id is matched against CalendarChannelEventAssociation.eventExternalId. Covers events synced into Twenty from Google Calendar (including individual instances of recurring events, where Fireflies returns the per-instance id with timestamp on cal_id).
2. iCalUID — Fireflies' calendar_id is matched against CalendarEvent.iCalUid. Covers events synced from Outlook / CalDAV, where Fireflies returns the RFC 5545 iCalUID directly.

Both identifiers are populated by Twenty's calendar drivers on every synced CalendarEvent, so any meeting that's been pulled in via Google / Outlook / CalDAV calendar sync will match exactly. The matcher does not fall back to fuzzy URL matching — if the transcript can't be tied to a synced calendar event, the CallRecording is still created, just without a linked calendar event. This avoids silently linking transcripts to the wrong event.

What gets added to your Twenty workspace

The app writes to the standard CallRecording object (no new schema):

• One CallRecording per Fireflies call, with a deterministic id — the meeting.transcribed webhook, the meeting.summarized webhook, and manual syncs all converge on the same record.
• Transcript — the diarized transcript (speaker names and sentence-level timestamps) stored in the CallRecording transcript field.
• Summary — the Fireflies AI summary (overview, action items, topics, keywords) stored as rich text in the CallRecording summary field.
• Title, start/end time, external recording id, and the CalendarEvent link filled from the Fireflies call metadata.

Plus three workflow tools — see Workflow tools below.

Workflow tools

Once the API key is configured, three tools become available in the workflow builder and the AI chat — covering the cases the webhook can't:

• Sync Fireflies Call — "sync the Fireflies call 01HXYZ... into a CallRecording now". As a workflow step: provide transcriptId. Runs the same pipeline as the webhook (fetch transcript + AI summary, find matching CalendarEvent, upsert the CallRecording) on demand. Use cases: backfilling historical calls that happened before the app was installed; recovering from a missed webhook (e.g. the calendar event hadn't synced yet when Fireflies pushed); or triggering a sync from a workflow instead of waiting for Fireflies. Output includes callRecordingId, calendarEventId, updatedFields, and a per-field outcome breakdown so partial successes are visible.
• List Fireflies Calls By Participant — "show me my last 5 calls with john@acme.com". As a workflow step: provide participantEmail (and optional limit, max 50). Returns recent Fireflies calls — newest first — where that email was an attendee, with title, date, duration, host, and transcript URL. The natural first step in workflows triggered on Person.created — "find what we've talked about with this contact".
• Search Fireflies Calls — "find any call where we discussed pricing". As a workflow step: provide keyword (and optional limit, max 50). Matches the keyword against both meeting titles and the words actually spoken in meetings. Returns the same call-summary shape as the participant tool. Best for AI-chat-driven research.

The list-by-participant and search tools return the same compact call shape: id, title, date, durationMinutes, participants, hostEmail, transcriptUrl, meetingLink. To then sync any of those calls into a CallRecording, pass the id from a list result into Sync Fireflies Call.

Installing

1. Open Settings → Applications in your Twenty workspace.
2. Find Fireflies in the available apps and click Install.
3. Follow Self-hosting setup below to wire up the API key and webhook (admin-only, one-time).

Heads up: if you see "Fireflies is not configured" on the first webhook, your Twenty admin needs to follow the Self-hosting setup section.

Upgrading from 0.1.x

Version 0.1.x stored transcripts and summaries as two rich-text fields on CalendarEvent. Upgrading removes those fields and their stored content — recordings now live on the standard CallRecording object instead.

The removed content is a cache of Fireflies data: any call still available in Fireflies can be re-ingested as a CallRecording by passing its id to Sync Fireflies Call (find ids with the list / search tools). An automatic history backfill on install and upgrade is planned as a follow-up.

Limitations

What this connector intentionally does not support in v1:

• Audio / video media ingestion. Fireflies' audio_url / video_url are not downloaded yet; the CallRecording holds the transcript and summary only. Media ingestion is planned for a follow-up.
• Fireflies sentiment, speaker analytics, transcript chapters. Only the raw transcript and the AI summary (overview, action items, topics, keywords) are synced today.
• Calls without a matching CalendarEvent (orphan calls). These are no longer skipped — the CallRecording is created — but it stays unlinked until the calendar event syncs; re-running Sync Fireflies Call after the calendar sync fills the link.
• Per-user Fireflies accounts. All transcripts come through one workspace-shared API key (set by the admin). Per-user OAuth-style connections require extending Twenty's connection provider system and are planned once we have evidence that workspace-shared is too coarse.
• Editing transcripts or summaries in Twenty. The CallRecording fields are writable but the next Fireflies sync overwrites any manual edits — treat them as read-only.

Troubleshooting

Symptom	Likely cause	Fix
Webhook returns Fireflies is not configured	FIREFLIES_API_KEY not set	Admin: paste the API key in Settings → Applications → Fireflies → Settings
Webhook returns Invalid webhook signature	FIREFLIES_WEBHOOK_SECRET mismatch between Fireflies and Twenty	Re-copy the signing secret from the Fireflies webhook configuration and paste it into the Twenty app settings
CallRecording is created but has no linked CalendarEvent	The meeting was never on a synced calendar in Twenty, or the workspace has no Google/Outlook/CalDAV calendar connection set up	Connect the relevant calendar provider in Settings → Accounts so the calendar event lands in Twenty with eventExternalId and iCalUid populated, then re-run Sync Fireflies Call for that transcript. Manually-created CalendarEvents are intentionally not matched in v1
Transcript appears empty	Fireflies returned no sentences (call too short, audio failed)	Check the call in the Fireflies dashboard; nothing this app can do
Summary appears empty	Fireflies hasn't summarized the call yet, or the call was too short to summarize	Fireflies sends meeting.summarized separately from meeting.transcribed (typically a minute or two later); ensure that event is subscribed to in your Webhooks V2 config
Summary is populated but Transcript isn't (or vice versa)	Only one of the two Fireflies events is subscribed to	Subscribe to both meeting.transcribed and meeting.summarized in your Fireflies Webhooks V2 configuration
Fireflies API errors with 401	API key wrong, rotated, or revoked	Generate a new key in Fireflies → Integrations → Fireflies API → Regenerate, then update FIREFLIES_API_KEY
Sync Fireflies Call reports No CallRecording was written	Fireflies returned no transcript sentences and no summary for the call, or the per-field outcomes show transient Fireflies API failures	Check the fieldOutcomes array in the result — skipped means Fireflies had no content for that field; error means Fireflies-side failure (retry, or inspect the error message)
List / Search tools return count: 0 for a contact you've definitely talked to	Email mismatch — Fireflies stores the address as the participant joined the meeting with, which may differ from the contact's primary address in Twenty (aliases, plus-addressing, work vs. personal)	Try the contact's other known email addresses; cross-check the participants list on a known matching call

---

Self-hosting setup (admin-only)

This section is for Twenty server admins. If you're on Twenty Cloud, skip this — the credentials may already be configured.

1. Generate a Fireflies API key

1. Visit https://app.fireflies.ai and sign in.
2. Go to Integrations → Fireflies API.
3. Click Generate API key and copy the value (it's only shown once).

2. Configure a Webhooks V2 endpoint in Fireflies

This integration targets Fireflies Webhooks V2 (snake_case payload, granular event subscriptions). The legacy V1 webhook format (meetingId / eventType: "Transcription completed") is not supported.

1. Open the Webhooks V2 page: https://app.fireflies.ai/integrations/api/webhook
2. Set the Webhook URL to your Twenty deployment's webhook endpoint: https://<your-twenty-domain>/webhook/fireflies. Twenty resolves the target workspace from the request's Host header, so the URL must match the workspace's public domain — localhost is not valid in the Fireflies UI. For local development, expose your dev server with a tunnel like ngrok http 3000 and paste the HTTPS forwarding URL here, or skip the Fireflies UI entirely and POST a signed payload directly to your local endpoint.
3. Set a Signing Secret (a long random string — generate one with openssl rand -hex 32). Save it; you'll paste it into Twenty next.
4. Under Events, subscribe to both:
   • meeting.transcribed — fires when the transcript is ready and writes it to the CallRecording's Transcript field.
   • meeting.summarized — fires once Fireflies finishes its AI summary and writes it to the CallRecording's Summary field. Subscribing to only one is fine if you don't want the other field populated; the app dispatches per event.
5. Save the configuration.

3. Wire the credentials into Twenty

1. In Twenty: Settings → Applications → Fireflies → Settings tab.
2. Paste the Fireflies API key into the FIREFLIES_API_KEY row.
3. Paste the signing secret into the FIREFLIES_WEBHOOK_SECRET row.

After saving, the next time Fireflies finishes processing a recording, a CallRecording with the transcript will appear (linked to the matching CalendarEvent) within a few seconds; the summary follows once Fireflies finishes the AI summarization step (typically a minute or two later — Fireflies sends two separate webhooks).