Native mobile app: CRM Caller ID and post-call logging for inbound/outbound phone calls

[Angel90000]

I'd like Twenty to identify inbound phone calls against CRM records on a salesperson's phone, and to capture the call afterwards as an activity on the record. HubSpot's mobile app does this today and it's the single feature I miss most when moving a team onto Twenty.

Two capabilities, both of which need a native mobile client:

1. Caller ID — when the phone rings, the native dialler shows the matching Twenty record (name, company, and on Android the linked opportunity) instead of an unknown number.
2. Call logging — after the call ends, the user is prompted to log it against the matched record, with an outcome and an optional note or follow-up task.

Out of scope: the rest of the mobile app surface (record browsing, editing, views). This assumes a native shell exists or is being built, so #6273 is a dependency. If you'd rather have it in smaller pieces, it splits cleanly into mobile: caller ID directory sync and mobile: post-call logging.

Also out of scope: VoIP/softphone calling inside Twenty, i.e. the Twilio and Zoom Phone style integrations discussed in #16735. This is about the calls people already make from their handset.

Worth saying why this is different from most mobile requests: it can't be built into the responsive web app at all. Only a native app can register with CallKit on iOS or the telephony broadcast/screening APIs on Android. So it's one of the few features that justifies a native client on its own merits, and it removes the main reason reps end up duplicating prospects into their personal address book.

Current behavior

Twenty has no native iOS/Android client. Mobile access is the responsive web app, which the OS never consults during an incoming call.

So when someone already in the workspace calls a user's phone, the dialler shows a bare number. The user either recognises it, declines and searches Twenty manually, or saves the contact into their personal phone address book, which puts CRM data outside the workspace and outside its permission model.

Calls are also never captured. To record that a call happened, the user opens Twenty later on desktop, finds the record, and writes a Note by hand. In practice most calls never get logged, so the timeline systematically under-represents actual activity.

Two structural gaps underneath this:

• The API has no phone-number-keyed lookup. Person.phones is a composite PHONES field (primaryPhoneNumber, primaryPhoneCallingCode, primaryPhoneCountryCode, additionalPhones), stored per record and not normalised to a single indexed E.164 string. There's no efficient "who owns this number?" query.
• There's no Call concept in the data model. Standard objects are People, Companies, Opportunities, Notes, Tasks, Messages, Calendar Events and Attachments. A phone call has nowhere canonical to live.

Expected behavior

How HubSpot does it

I dug into HubSpot's implementation before writing this, because the platform constraints shape the design more than I expected and they aren't obvious up front.

On iOS, HubSpot registers a CallKit Call Directory extension. Per Apple's CallKit documentation, when a call comes in the system first checks the user's own contacts, and only consults the app's Call Directory extension if there's no match. The important part: the extension is invoked when the system launches it, not per call, so all identification data has to be handed over in advance. A per-call network lookup is simply not possible. HubSpot formats its stored contacts and pushes them to the system each time the app starts. The consequence is that iOS is limited to first name, last name and company name, and a missed call leaves that label in the native call log.

On Android there's no such constraint. HubSpot uses a BroadcastReceiver on phone-state changes and draws its own overlay, so it can show first name, last name, company name, deal name and deal amount. Their engineering blog mentions they originally hit the backend on every incoming call, found it slow and unreliable, and moved to an on-device cache synced daily, falling back to the backend only on a cache miss. Missed calls generate a notification with "view contact" and "call back".

Common to both: contacts auto-sync every 24 hours, with a manual sync button under Settings → Calling → Caller ID. Matching runs off their Phone number and Mobile number property types. If the person is already in the phone's own address book, the OS contact wins. They document that it works best under roughly 10,000 contacts, and that numbers should be stored as +<country code><number> with no spaces or parentheses. On iOS the user also has to enable the app under Settings → Apps → Phone → Call Blocking & Identification. After a call, a "Log calls" screen (Android and Xiaomi only) lets the user log it with an outcome, notes, or a follow-up task.

The iOS/Android asymmetry is inherent to the platforms rather than a HubSpot shortcoming, so any implementation here will hit the same split.

Proposed behavior in Twenty

Enabling. Settings → Calling → Caller ID in the mobile app, with toggles for Caller ID and Log calls, a manual "Sync now" action, and a line showing last sync time and number of records synced. iOS additionally needs to point the user at Settings → Apps → Phone → Call Blocking & Identification, ideally with a deep link. Android requests READ_PHONE_STATE, READ_CALL_LOG, ANSWER_PHONE_CALLS and overlay permission, each with an in-app explanation shown before the system dialog.

Directory sync. On login, on app foreground, and on a 24-hour background schedule, the app pulls a compact caller-ID directory scoped to what the signed-in workspace member is permitted to see. Delta sync via an updatedSince cursor, full rebuild on first run or workspace switch. Numbers normalised to E.164 server-side using the record's calling code, falling back to the workspace default. The directory stays on-device, and the phone's own address book is never read or uploaded.

Incoming call, iOS. The Call Directory extension has already published the number-to-label mapping, so the dialler shows Jane Doe · Acme Inc with no network round trip. The label is a single string, so the format has to be {firstName} {lastName} · {companyName}, truncated to fit. A missed call keeps that label in the iOS call log.

Incoming call, Android. An overlay above the dialler showing name, company, and the primary open opportunity with its amount, plus an "Open in Twenty" action. On a cache miss with connectivity, fall back to a live server lookup; otherwise show nothing and let the OS behave normally. Missed calls produce a notification with "View record" and "Call back".

After the call. If Log calls is on and the number matched a record, a post-call screen offering an outcome (connected / no answer / left voicemail / wrong number / busy), duration prefilled, an optional note body, and an optional follow-up task with a due date. Confirming writes a call activity linked to the matched Person, and to their Company and open Opportunity where applicable. Dismissing writes nothing, and the screen should never block the dialler. Outbound calls placed from the phone to a known record get the same prompt.

Unmatched numbers. The OS behaves exactly as it does today. The post-call screen could optionally offer "Create person in Twenty" with the number prefilled, though that's fine as a follow-up.

Technical inputs

Suggestions rather than prescriptions, since you'll know better where things belong in the codebase.

Data model

The first thing to settle is how a call is represented. Options as I see them: a new standard call object (direction, outcome, startedAt, durationSeconds, phoneNumber, body, relations to Person/Company/Opportunity/WorkspaceMember); a timelineActivity of type call with no first-class object; or leaving it to a custom object via the SDK's defineObject. I'd argue for the first, because the same object is what any future Twilio, Zoom Phone or Quo integration would want to write into (#16735), so building it now avoids a migration later. This is the main product decision blocking the rest of the ticket.

Second, a normalised phone index. Some E.164 representation alongside the composite PHONES field, either a generated column on the workspace schema or a lookup table maintained on write, with a btree index. Plus a secondary index on the last 7–9 digits for suffix matching when a caller's number arrives without a country code. Without this, both the sync endpoint and the server-side fallback lookup are full scans.

Backend

• New endpoint along the lines of GET /rest/mobile/caller-id-directory?updatedSince=<ISO8601>&cursor=<...>, returning a minimal payload per entry: { e164, firstName, lastName, companyName, opportunityName, opportunityAmount, recordId, objectNameSingular, updatedAt }.
• Record-level permissions have to be enforced for the requesting workspace member. The directory must never contain records the user can't see in the web app. This is the main security consideration, since the payload leaves the server and lands in a local database on a device the workspace doesn't control.
• Cap directory size (soft warning above ~10k entries, hard cap configurable) and paginate. Return a syncToken so clients can resume.
• Fallback lookup for cache misses, e.g. GET /rest/mobile/caller-id-lookup?e164=<...>, rate-limited.
• The same payload shape could come from a webhook or subscription later if near-real-time sync is wanted. Daily is plenty for a first version.

Mobile client

• New workspace package packages/twenty-mobile (React Native + Expo, TypeScript), reusing twenty-shared and the generated GraphQL types so field changes propagate. Server URL supplied by the user at login so self-hosted instances work, which is non-negotiable for this project's user base.
• Local store: SQLite via expo-sqlite, table caller_id_directory, unique index on e164 and an index on the digit suffix. Nothing stored beyond what the directory payload contains.
• Background sync via expo-background-task on iOS and WorkManager on Android, manual sync from settings. Surface the last-sync timestamp and entry count prominently — HubSpot users have complained for years about silent sync failures, and it seems worth designing against that from the start.

iOS specifics

• CXCallDirectoryProvider in a Call Directory app extension.
• Extension and main app share an App Group container. The app writes the directory to shared storage, then calls CXCallDirectoryManager.reloadExtension(withIdentifier:).
• CallKit requires identification entries to be added in ascending numerical order of phone number. If they aren't sorted, the extension fails to load and the user gets no useful error.
• Prefer incremental reloads (addIdentificationEntry / removeIdentificationEntry in beginRequest) over full rebuilds, which get slow at scale.
• Extension memory is tightly constrained, so stream from SQLite rather than loading the directory into memory.
• Detect and surface the "extension not enabled in iOS Settings" state, because otherwise the feature silently does nothing and looks broken.

Android specifics

• Prefer CallScreeningService (API 29+) where available, falling back to a BroadcastReceiver on android.intent.action.PHONE_STATE.
• Overlay via SYSTEM_ALERT_WINDOW, or a full-screen intent notification where overlay permission is denied.
• OEM background restrictions need explicit handling. Xiaomi/MIUI requires autostart and "display pop-up windows while running in the background" to be enabled by hand, so a detection and guidance screen for the common offenders will save a lot of support noise.
• Play Store policy: READ_CALL_LOG and ANSWER_PHONE_CALLS are sensitive permissions requiring a declaration form and a demo video. Better to know that before submission than during.

Matching logic

• Normalise incoming numbers with libphonenumber (libphonenumber-js on the JS side), using the device SIM region first and the workspace default calling code as a fallback.
• Exact E.164 match first, then suffix match on the last 9 digits, then 7. Suffix matching will throw occasional false positives on short national numbers, so prefer the most recently updated record and present the match as tentative rather than guessing silently.
• Match against both primaryPhoneNumber and additionalPhones, on People and on Companies.

Documentation

A docs page covering enabling per platform, sync behaviour, matching rules, the "store numbers as +15551234567" guidance, and what data lives on the device.

Notes

Happy to write the flows up in more detail, mock the screens, or contribute to the implementation if the direction is accepted.

One piece of prior art worth a look: TwentyMobile (AGPL-3.0), an independent native client that came out of #6273. It doesn't implement caller ID, but the app-shell groundwork is there.

[Shinu-Cherian]

can i do this?