Push Notifications
The server side of waking a mobile app for an incoming call: enabling the wake-up hold, the call.mobile_push_wakeup webhook, and sending the push from your backend.
Everything that happens in the app (the softphone, CallKit and Telecom, and handling the push when it arrives) is covered in the Mobile Integration Guide.
Mobile clients still need to register an emergency address for the user — see Emergency Calling (E911). Nomadic use cases make this especially important on mobile, since users routinely change networks and locations.
When a mobile app is in the background or closed, the WebRTC signalling connection is not active. Push notifications bridge this gap — DialStack notifies your backend via webhook, and your backend sends a push to wake the app.
Enabling Wake-Up Hold
By default, when a user has no active calling session, an incoming call moves on to their other devices and voicemail immediately. For DialStack to instead hold the call while your push wakes the app, enable mobile_push_wakeup on the user:
await dialstack.users.update(
userId,
{ config: { mobile_push_wakeup: true } },
{ dialstackAccount: accountId }
);
Enable this for users your application can actually reach with push notifications (for example, when they register a device token). With the flag on, the call keeps ringing toward the user's app for a wake-up window — long enough for push delivery, app wake-up, and connection — before falling through to the user's normal routing (next Find Me / Follow Me step or voicemail). With the flag off, there is no wait.
How It Works
For a user with mobile_push_wakeup on, DialStack sends your backend a call.mobile_push_wakeup webhook for every call it delivers to the user's softphone sessions. Your backend sends a push to the user's devices. The app wakes, reconnects, and receives the call. See The Wake Flow for the app's side.
The webhook fires even when the user has a connected session, such as a browser softphone. Both then ring: the browser at once, and the app as soon as it wakes and reconnects. The user can answer on either.
When the user has no connected session at all, DialStack also holds the call while the app wakes, instead of moving straight on to their other devices and voicemail.
The hold lasts at most 30 seconds from when DialStack starts ringing the user, and never longer than that ring step's own timeout. That covers push delivery, the app waking and reconnecting, and the user answering. After 30 seconds the app can no longer join the call, and the call moves on to the user's normal routing when the ring step times out.
Webhook Payload
DialStack delivers a call.mobile_push_wakeup webhook event to your platform's webhook URL whenever an incoming call is being delivered to the app session of a user with mobile_push_wakeup enabled — whether the call reached them directly, through a ring group, or as a call queue agent. The user field identifies the user whose app should be woken, so you can look up their device tokens in your own database and send the push:
{
"id": "evt_01jqr5k8m3n4p6q7r8s9t0u1v3",
"type": "call.mobile_push_wakeup",
"created_at": "2026-04-10T14:30:00Z",
"account": "acct_01h2xcejqtf2nbrexx3vqjhp41",
"data": {
"call_id": "call_01h2xcejqtf2nbrexx3vqjhp45",
"user": "user_01h2xcejqtf2nbrexx3vqjhp42",
"direction": "inbound",
"from_number": "+14155551234",
"from_name": "John Smith",
"to_number": "+14155559876",
"ringing_at": "2026-04-10T14:30:00Z"
}
}
Push on call.mobile_push_wakeup, not on call.incoming or call.ringing: it fires only when the user's app session is actually being rung, so every push matches a real, answerable call. The webhook catalog explains the difference.
What from_number holds on an internal or transferred call is described in the webhook catalog.
Your backend maintains the mapping between the DialStack user and your push notification device tokens. DialStack does not store device tokens — push delivery is entirely in your control.
Sending Push Notifications
The examples below show the transport settings. The exact payload shape depends on the OS call library in your app, which reads the push; whatever the shape, include the webhook's call_id, so the app can pair the push with the call it receives.
iOS (APNs)
Send a VoIP push notification using the PushKit framework. VoIP pushes wake the app immediately and have higher priority than standard notifications.
import apn from 'apn';
const provider = new apn.Provider({
token: {
key: './AuthKey.p8',
keyId: 'YOUR_KEY_ID',
teamId: 'YOUR_TEAM_ID',
},
production: true,
});
async function sendCallPush(deviceToken, callData) {
const notification = new apn.Notification();
notification.topic = 'com.example.myapp.voip';
notification.pushType = 'voip';
notification.priority = 10;
notification.expiry = Math.floor(Date.now() / 1000) + 30; // 30 second TTL
notification.payload = {
call_id: callData.call_id,
from_number: callData.from_number,
from_name: callData.from_name,
to_number: callData.to_number,
};
await provider.send(notification, deviceToken);
}
Android (FCM)
Send a high-priority data message to bypass Doze mode:
import admin from 'firebase-admin';
admin.initializeApp({
credential: admin.credential.applicationDefault(),
});
async function sendCallPush(deviceToken, callData) {
await admin.messaging().send({
token: deviceToken,
android: {
priority: 'high',
ttl: 30000, // 30 seconds
},
data: {
type: 'call.mobile_push_wakeup',
call_id: callData.call_id,
from_number: callData.from_number,
from_name: callData.from_name || '',
to_number: callData.to_number,
},
});
}
Use FCM data messages (not notification messages) for incoming calls. Data messages wake the app immediately and let you show a full-screen call UI. Notification messages display a banner that the user must tap.
Webhook Handler
Your platform's webhook handler receives call.mobile_push_wakeup events for all accounts. Verify the signature over the raw request body first; Signature verification covers the algorithm. With @dialstack/sdk-server, DialStack.webhooks.constructEvent verifies it and parses the event in one call, throwing when the signature is invalid:
import express from 'express';
import { DialStack } from '@dialstack/sdk-server';
const app = express();
app.post('/webhooks/dialstack', express.raw({ type: 'application/json' }), async (req, res) => {
let event;
try {
event = DialStack.webhooks.constructEvent(
req.body,
req.headers['x-dialstack-signature'],
process.env.DIALSTACK_WEBHOOK_SECRET
);
} catch {
return res.status(401).send('Invalid signature');
}
if (event.type === 'call.mobile_push_wakeup' && event.data.user) {
// Look up the user's device tokens in YOUR database
const devices = await getDeviceTokensForUser(event.data.user);
// Send push to all registered devices in parallel
await Promise.all(
devices.map((device) =>
device.platform === 'apns'
? sendApnsPush(device.token, event.data)
: sendFcmPush(device.token, event.data)
)
);
}
res.status(200).send('OK');
});
Best Practices
- Send push notifications with a short TTL (30 seconds) — stale call notifications confuse users
- Use VoIP pushes on iOS (PushKit) for immediate delivery and CallKit integration
- Use FCM data messages (not notification messages) on Android for full app control