Phone alerts
With Unstuck Cloud, your agent can tell you the moment it gets stuck. A takeover sends you a short alert, and tapping it opens the live browser so you can solve the page.
On this page:
- Choose how you get alerts
- Turn on alerts for a key
- Pair a phone
- Telegram (recommended)
- Phone notifications
- Alerts in this browser
- Email alerts and plans
- History
- Test and troubleshoot
- Privacy
- Alerts in your code
Choose how you get alerts
| Channel | Who it is for | Cost |
|---|---|---|
| Telegram (recommended) | Most people: messages arrive reliably. Works on iPhone in Safari, without installing anything. | Free |
| Phone notification | A second channel, or if you don't use Telegram. On iPhone and iPad, Unstuck must be on the Home Screen. | Free |
| Alerts in this browser | You have no phone to pair, or you work at a computer. Works while the alerts page is open. | Free |
| You want a copy in your inbox, or a backup. | Paid plan |
We recommend Telegram because many Android phones delay or drop browser notifications: battery saving, sleeping apps (Samsung), notification cooldown, and some browsers such as Samsung Internet. Telegram messages still arrive. You can use several at once. Telegram and phone notifications are set up on a paired phone. Each alert says which API key sent it ("Sent by key: production").
When an agent calls takeover(), the engine on your machine seals the takeover link to each phone and browser you have paired and hands it to Unstuck Cloud. Cloud delivers it on the channels you turned on.
Turn on alerts for a key
An API key can only alert you once you allow it. On API keys, switch on Can alert my phones for the key (you are asked to confirm), or use Turn on alerts for a key on the Phones page.
Only turn this on for keys you control. Anyone with the key can send you alerts, and with email alerts on, a key that can alert can use up your monthly email quota.
Pair a phone
Pairing gives the phone its own key. Only that phone (in that browser) can open the links sent to it.
- Open Phones in your dashboard and choose Add a phone. You get a QR code, a link and a code like
ABCD-EFGH. The code works once, for 10 minutes. - On the phone, scan the QR code or open the link. It opens the pairing page,
view.unstuck.sh/pair. - Check the name for this phone, then tap Pair this phone. On iPhone and iPad in Safari, the button is Pair Safari (for Telegram and email links).
- The page says "This phone is paired as …". Now connect Telegram (recommended) on the same page. You can also turn on phone notifications.
Good to know:
- The phone shows up in the dashboard under Your phones.
- Clearing the browser's site data unpairs the phone. Pair it again with a new code.
- If the code ran out, the page says so. Choose Add a phone again for a new one.
- Opening a new code in a browser that is already paired asks first: Pair again or Keep current.
Telegram
Telegram is the recommended channel: its messages arrive reliably, also on phones that hold browser notifications back.
Telegram alerts come from the Unstuck bot, @unstuck_bot. Each message reads "Your agent needs you" with the key that sent it and an Open button. Telegram is set up on the paired phone, with no new pairing code.
- Pair the phone (see Pair a phone). On iPhone, pair Safari.
- On the phone's pairing page, tap Connect Telegram. If you left the page, open it again: the Phones page shows its link under your phones.
- Telegram opens the bot. Press Start. The bot answers "Connected. Alerts for … will arrive here."
- Go back to the pairing page. It says "Telegram is connected: alerts for this phone arrive in your Telegram chat."
- In the dashboard, the phone now has a Telegram alerts switch instead of "Not connected".
The link from Connect Telegram works for 10 minutes. If the bot says the code has expired, tap Connect Telegram again (or Reconnect Telegram once connected). To stop Telegram alerts, switch off Telegram alerts in the dashboard, or send /stop to the bot.
Opening an alert from Telegram
Telegram opens links in its own in-app browser, which can't open an alert meant for the browser you paired. If the page says it is the "phone you paired" page, tap the menu and choose Open in Safari (iPhone) or Open in Chrome (Android), or open it from the Home Screen app.
Tip: in Telegram, open Settings, Chat Settings and turn off In-App Browser, so links from the bot open in the browser you paired.
Open Telegram links in any browser
If you open Telegram links in a browser other than the one you paired (Samsung Internet instead of Chrome, say), turn this on for that phone. It is called Telegram links open in any browser on the phone's pairing page and Open Telegram links in any browser on Phones. It is off by default and needs Telegram connected.
The trade-off: Telegram links then carry the key that opens them, so Unstuck Cloud, Telegram and anyone you forward the message to could open your takeovers. Phone notifications and email stay locked to the paired browser.
With it on, Telegram links open on a short start screen that shows the reason, the site and the key that sent them. The "From your key" line confirms Unstuck sent this takeover to your phone. If Unstuck didn't send the link, or it can't check, the screen warns you first. Turning the setting off deletes that key at once; links already sent keep working until they expire.
Phone notifications
A phone notification (Web Push) arrives like any app notification. Tapping it opens the takeover. It is free: one alert per takeover, per phone.
Some phones hold browser notifications back, especially Android phones with battery saving or notification cooldown. Use it alongside Telegram, and see Notifications that don't show up.
Android (Chrome)
- Pair the phone in Chrome (see Pair a phone).
- Optional: tap Install Unstuck on the pairing page. It brings back Chrome's install prompt, so you can install Unstuck as an app even if you dismissed Chrome's own banner earlier. Takeover links and notifications then open in the app.
- Tap Turn on phone notifications and allow notifications when asked.
- The page says "Phone notifications are on."
The Install Unstuck button shows only while Chrome offers to install. If you dismiss the prompt, the button goes until you reload the page. If there is no button, you can install from Chrome's menu instead (⋮, then Install app or Add to Home screen).
Once Unstuck is installed, the pairing page says "Unstuck is installed on this phone."
Computer (Chrome or Edge)
- Pair the browser: open the link from Add a phone on the computer, then choose Pair this phone.
- Optional: choose Install Unstuck to install it as an app. On a computer, the page doesn't mention it once it is installed; the button just goes away.
- Choose Turn on phone notifications and allow notifications.
iPhone and iPad
iPhone and iPad only show notifications for apps on the Home Screen, from iOS 16.4. Safari alone can't get them. The Home Screen app is paired on its own, with a second code.
- Open the pairing link in Safari. If you also want Telegram or email alerts, tap Pair Safari (for Telegram and email links): those links open in Safari.
- Add Unstuck to the Home Screen: tap Share, then Add to Home Screen. The pairing page shows these steps, and once Safari is paired, Install Unstuck shows them again.
- Open Unstuck from your Home Screen.
- In the dashboard, choose Add a phone again. In the Home Screen app, enter the new code under "Enter the pairing code from your dashboard" and tap Pair this phone.
- Tap Turn on phone notifications and allow notifications.
The Home Screen app says "Unstuck is installed on this phone." In the dashboard, Safari and the Home Screen app appear as two phones, for example "iPhone · Safari" and "iPhone · Home screen app".
Alerts in this browser
No phone? A browser tab can get alerts instead. It pairs itself like a phone, on its own page, view.unstuck.sh/alerts. It has no push: it only shows alerts while that page is open.
- In the dashboard, choose Get alerts in this browser. It is on Phones, under Alerts in this browser, and on History.
- The alerts page opens in a new tab and sets up this browser. It shows up on Phones with a Browser tag.
- Tick Notify me and allow notifications, so a new takeover also shows a browser notification ("Your agent needs you", with no reason or site).
- Keep the tab open. New takeovers appear under Waiting for you, with the reason, the site, the key, the time left and an Open button.
How often it checks:
- Every 5 seconds while the tab is in view.
- In the background, only with Notify me on: once a minute.
- With the tab closed, nothing arrives in this browser.
The dashboard's Overview and History show "1 takeover waiting" (or "N takeovers waiting") with Open alerts, which opens the alerts page.
The alerts page works only while this browser is signed in to the dashboard. If you sign out, alerts are hidden there until you open alerts from the dashboard again.
To stop, choose Stop alerts in this browser on the alerts page, or Remove next to the browser on Phones.
Email alerts and plans
Email sends one email per takeover to your sign-in address, with an "Open on" button for each paired phone. It needs a plan.
- Basic: $5/month for 500 emails.
- Pro: $12/month for 3,000 emails.
- Scale: $29/month for 15,000 emails.
Emails don't roll over, and stop at the limit: there is no overage charge. Choose a plan and switch email alerts on from Billing. Telegram, phone notifications and alerts in this browser never need a plan.
History
History in the dashboard lists every takeover from the last 30 days: when it started, which key, whether a person opened it, how long it ran and which alerts were sent. It never shows the reason, the site or anything typed, because Unstuck can't read them.
Test and troubleshoot
Each phone and browser on Phones has Send a test alert. The result shows what each channel did, for example "Phone notification: sent · Telegram: not connected".
- Phone notification: a test notification arrives on the phone.
- Telegram: the bot sends "Test alert from Unstuck".
- Alerts in this browser: the dashboard says "Sent to this browser’s alerts page." The alerts page shows "Test alert: alerts reach this browser." for a minute. With Notify me on, you also get an "Unstuck test alert" notification.
You can send up to 5 tests a minute to a browser. Past that, the result says to wait a minute.
After a test, every Send a test alert button waits 10 seconds. Phones often hold back a second notification that arrives a few seconds after the first (see Notifications that don't show up), so two quick tests can look like one was lost.
Common problems:
- No notification on iPhone. Safari can't show notifications. Add Unstuck to the Home Screen, open it from there, pair it with a new code and turn on phone notifications (iOS 16.4 or later).
- No notification on Android. Check that notifications are allowed for Chrome (or the installed app) in the phone's settings. Battery saver can hold notifications back: let Chrome run in the background.
- "Could not turn on phone notifications." Notifications are blocked for the site. Allow them in the browser's settings, then try again.
- Telegram doesn't show as connected. Press Start in the bot within 10 minutes of tapping Connect Telegram, then go back to the pairing page. If it still says Connect Telegram, tap it again. On Phones, "Not connected" means no Telegram chat is linked to that phone.
- "No channel is on for this phone." Connect Telegram or turn on phone notifications on the phone, or switch them back on in the dashboard.
- Nothing is paired. Without a phone, a browser or email alerts, takeover links only reach your agent's logs. The dashboard shows a banner with Pair a phone and Get alerts in this browser.
- No alert at all. Check that the key has Can alert my phones on (see Turn on alerts for a key).
Notifications that don't show up
When the dashboard says Phone notification: sent, the push service (Google's for Android and Chrome, Apple's for iPhone, Mozilla's for Firefox) has accepted the alert. From there, the phone or computer decides when and how to show it. Most "missing" alerts are held back or shown quietly by a setting on the device. Menu names vary by maker and version; the steps below are for recent ones.
First, check whether it arrived quietly:
- Android: pull down the notification shade, or open Settings → Notifications → Notification history (on Samsung: Settings → Notifications → Advanced settings → Notification history).
- iPhone and iPad: swipe down from the top-left corner to see Notification Center.
- Mac: click the date and time in the menu bar.
- Windows: open the notification center (Windows key + N).
Android
- Notification cooldown (Android 15 and later, including Samsung One UI 7). When several notifications arrive close
together, the phone lowers their sound and vibration and may skip the pop-up, so the second one lands silently in
the shade. Turn it off:
- Pixel and most phones: Settings → Notifications → Notification cooldown, then turn it off.
- Samsung: Settings → Notifications → Advanced settings → Notification cooldown, then turn it off.
- Battery saving. Phones put apps they think are unused to sleep and hold their notifications until you open them.
Do this for Chrome (or the browser you paired, or the installed Unstuck app) and for Telegram:
- Any Android: Settings → Apps → app → Battery → Unrestricted.
- Samsung: Settings → Battery → Background usage limits: remove the app from Sleeping apps and Deep sleeping apps, add it to Never sleeping apps, and consider turning off Put unused apps to sleep.
- Xiaomi, Redmi, POCO: Settings → Apps → Manage apps → app: turn on Autostart and set Battery saver to No restrictions.
- OnePlus, OPPO, realme: Settings → Battery → app: allow background activity and turn off battery optimisation for it.
- Huawei, Honor: Settings → Battery → App launch → app: switch to Manage manually and allow auto-launch and running in the background.
- The app's notifications. Settings → Apps → app → Notifications: notifications allowed, all categories on,
and for the browser, the site (
view.unstuck.sh) allowed too. - Do Not Disturb and modes. Turn them off, or add the app as an exception.
iPhone and iPad
iOS has no notification cooldown, but these hold alerts back:
- Only the Home Screen app gets notifications (iOS 16.4 or later). Safari tabs never do. See iPhone and iPad.
- Focus and Do Not Disturb. Settings → Focus: turn it off, or add the Unstuck Home Screen app (and Telegram) to Allowed Apps.
- Scheduled Summary delivers some notifications in batches. Settings → Notifications → Scheduled Summary: leave Unstuck and Telegram out of it, or turn it off.
- The app's settings. Settings → Notifications → Unstuck (and Telegram): Allow Notifications on, with Lock Screen, Notification Center and Banners all on. Banner style Persistent keeps an alert on screen until you act on it.
- Low Power Mode can delay background activity. If alerts are late, try with it off.
Mac
- Focus and Do Not Disturb. Turn them off, or allow your browser in System Settings → Focus.
- System Settings → Notifications → your browser: Allow notifications on, alert style Alerts (stays on screen) rather than Banners.
- The browser must be running. Chrome can keep running in the background when its windows are closed: Chrome settings → System → Continue running background apps when Google Chrome is closed.
Windows
- Do not disturb and Focus (Settings → System → Notifications). Turn them off, or add your browser as a priority app.
- Settings → System → Notifications → your browser: notifications on, with Show notification banners.
- As on Mac, the browser must be running for notifications to arrive. Keep Chrome's Continue running background apps on.
Telegram
- In Telegram, open the Unstuck bot chat and make sure it isn't muted.
- Telegram → Settings → Notifications and Sounds: Private Chats notifications on.
- The phone's battery settings above apply to Telegram as well.
Privacy
Unstuck only forwards sealed links. The link's secret stays inside an encrypted blob that only your paired phone or browser can open, so Unstuck Cloud, Telegram, the push service and your email provider never see the takeover token, the key, the page or anything typed. Cloud only learns that an alert was sent. The reason and the site are unlocked on your device, not by Unstuck. The one exception is the opt-in Open Telegram links in any browser setting.
Turn alerts off for one takeover
Alerts are on by default for keys that can alert. To skip them for a single call, pass alerts: false (Python: alerts=False; MCP: alerts: false).
await unstuck.takeover(page, { reason: 'CAPTCHA on checkout', alerts: false });await unstuck.takeover(page, reason="CAPTCHA on checkout", alerts=False)Fail at once if no phone gets the link
For an agent that runs with nobody watching, pass alerts: 'required' (Python: alerts="required"). If Unstuck Cloud can't accept the link for at least one paired phone, the takeover ends at once as failed with detail alert_failed, instead of waiting for its timeout. That covers alerts not enabled for the key, no paired phone, a seal failure, and Unstuck Cloud erroring or not answering within 10 seconds. It does not fire once a person has already joined through a link your own onLink sent. A self-hosted relay has no alerts, so 'required' throws a configuration error there.
const result = await unstuck.takeover(page, { reason: 'CAPTCHA on checkout', alerts: 'required' });
if (result.detail === 'alert_failed') { /* pair a phone, or turn alerts on for the key */ }When a person taps Can't solve, the result is cancelled and detail is cant_solve, or the note they typed.
Staging and development
Engines use Unstuck Cloud's relay, send alerts to unstuck.sh and link to the viewer at view.unstuck.sh. To try alerts against another Cloud (staging or a local one), set UNSTUCK_VIEWER_URL together with UNSTUCK_CLOUD_URL (that environment's relay) and UNSTUCK_CLOUD_API (its API), so the links the engine seals open on that environment's viewer, where your phone was paired.