Unstuck Docs GitHub

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

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
Email 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.

  1. 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.
  2. On the phone, scan the QR code or open the link. It opens the pairing page, view.unstuck.sh/pair.
  3. 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).
  4. 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:

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.

  1. Pair the phone (see Pair a phone). On iPhone, pair Safari.
  2. 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.
  3. Telegram opens the bot. Press Start. The bot answers "Connected. Alerts for … will arrive here."
  4. Go back to the pairing page. It says "Telegram is connected: alerts for this phone arrive in your Telegram chat."
  5. 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.

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)

  1. Pair the phone in Chrome (see Pair a phone).
  2. 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.
  3. Tap Turn on phone notifications and allow notifications when asked.
  4. 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)

  1. Pair the browser: open the link from Add a phone on the computer, then choose Pair this phone.
  2. 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.
  3. 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.

  1. 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.
  2. 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.
  3. Open Unstuck from your Home Screen.
  4. 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.
  5. 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.

  1. In the dashboard, choose Get alerts in this browser. It is on Phones, under Alerts in this browser, and on History.
  2. The alerts page opens in a new tab and sets up this browser. It shows up on Phones with a Browser tag.
  3. Tick Notify me and allow notifications, so a new takeover also shows a browser notification ("Your agent needs you", with no reason or site).
  4. 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:

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.

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".

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:

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

iPhone and iPad

iOS has no notification cooldown, but these hold alerts back:

Mac

Windows

Telegram

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)

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.