Getting started
expo-callkit-telecom is opinionated about system integration and unopinionated about media. You wire your media library (LiveKit, plain WebRTC, etc.) to the events the module emits.
Tested against
This library has been exercised end-to-end on real devices in the example/ app. See Verified against for the full compatibility matrix (iOS, Android, Expo SDK, React Native, media transport).
Install
bun add expo-callkit-telecomPeer dependencies
Your app also needs expo-notifications and a react-native-webrtc build:
bun add @livekit/react-native-webrtc expo-notifications- A
react-native-webrtcbuild.@livekit/react-native-webrtc>= 144is the one the maintainers test against. The module doesn't depend on a specific WebRTC pod: on iOS it finds WebRTC's classes at runtime in whichever WebRTC framework your app ships,LK-prefixed (LiveKitWebRTC, from@livekit/react-native-webrtc144.2.0) or not, so upstreamreact-native-webrtc>= 124.0.5and other forks also work (community-verified). Install only one of them. expo-notifications— required on Android, where the module's FCM service builds on it.
Add the config plugin to app.json / app.config.ts. Minimal form:
{
"expo": {
"plugins": ["expo-callkit-telecom"]
}
}With custom sounds and options:
{
"expo": {
"plugins": [
[
"expo-callkit-telecom",
{
"sounds": [
"./assets/sounds/ringtone.wav",
"./assets/sounds/dialtone.wav"
],
"defaultRingtoneIos": "ringtone.wav",
"defaultRingtoneAndroid": "ringtone.wav",
"defaultDialtone": "dialtone.wav",
"iconTemplateIos": "./assets/callkit-icon.png",
"notificationIconAndroid": "./assets/notification-icon.png",
"notificationStringsAndroid": {
"es": { "incomingCall": "Llamada entrante", "answer": "Contestar", "decline": "Rechazar" }
},
"incomingCallTimeout": 45,
"outgoingCallTimeout": 60,
"fulfillAnswerCallTimeout": 30,
"includesCallsInRecents": true,
"supportsVideo": true,
"microphonePermission": "$(PRODUCT_NAME) needs the microphone to make calls."
}
]
]
}
}Files in sounds are copied into the iOS bundle and Android raw resources at prebuild time. Set includesCallsInRecents: false to keep calls out of the phone's Recents/call log (iOS — defaults to true; Android self-managed calls are never logged, so no flag is needed there). The full prop type is ExpoCallKitTelecomPluginProps in plugin/src/.
iconTemplateIos sets the app's icon on the iOS CallKit call screen. CallKit renders it as a template — only the alpha channel is used (RGB is ignored) and the system tints it — so provide a ~40×40pt square PNG whose alpha describes the glyph. It's iOS-only; Android brands the incoming-call UI from the launcher icon automatically.
notificationIconAndroid is the small icon on the Android call notifications. Android draws it from the alpha channel only, so provide a white glyph on a transparent background (a ~96×96px PNG or a vector drawable .xml); without it, the launcher icon is used and an opaque icon renders as a solid shape.
notificationStringsAndroid sets the text on the Android call notifications, incoming-call screen, and notification channels, keyed by locale: default replaces the built-in English, and BCP 47 keys ("es", "pt-BR") are used when the device is set to that language. See AndroidNotificationStrings for the keys.
Set supportsVideo: false in audio-only apps to hide the video button on the iOS CallKit call screen.
Concepts
The TypeScript API is organised into three verbs:
| Verb | Direction | Examples |
|---|---|---|
| Request | App → System | startOutgoingCall, answerCall, endCall, setMuted |
| Report | App → System (state) | reportIncomingCall, reportOutgoingCallConnected, reportCallEnded |
| Fulfill | App → System (ack) | fulfillIncomingCallConnected |
Events flow the other way (System → App) via addXxxListener.
Registering for VoIP push
import {
registerVoIPPush,
useVoIPPushToken,
} from "expo-callkit-telecom";
// Once, early in app lifecycle:
registerVoIPPush();
// In a React component:
function App() {
const voip = useVoIPPushToken();
useEffect(() => {
if (voip) {
// voip.type is "APNS_VOIP" on iOS, "FCM" on Android.
sendToBackend(voip.token, voip.type);
}
}, [voip]);
}Example app
The repo's example/ contains a runnable Expo app (example/client/) and a zero-dep push-sender script (example/server/). See their READMEs for setup and how to validate VoIP push end-to-end.