ERR_UNKNOWN_URL_SCHEME on a WhatsApp link means your WebView tried to load a whatsapp:// or intent:// address as a web page. A WebView only loads web URLs, so it fails. The fix is to catch those links in shouldOverrideUrlLoading, hand them to Android as an Intent, and return true.
Why WhatsApp links trigger ERR_UNKNOWN_URL_SCHEME
WhatsApp links trigger ERR_UNKNOWN_URL_SCHEME because they end up at a scheme the WebView can’t render. The AdMob WebView click guide says it plainly: WebView doesn’t support custom URL schemes. Its example is a Google Play link that uses market://.
Testing in Chrome masks the problem, because Chrome passes whatsapp:// and intent:// to the WhatsApp app on its own. Your WebView does nothing of the kind until you write the code.
The usual report: the “Chat on WhatsApp” button works in the phone’s browser, but inside the app it shows a grey error page. A forum thread on exactly that settled on intercepting wa.me, whatsapp:// and intent:// URLs and starting an Intent.
What each link type should do
Each scheme needs its own handling, and each needs a plan for when the target app isn’t installed. Here is the decision table I use:
| Link on your page | What to do | If the app is missing |
|---|---|---|
https://wa.me/<number> |
Let it open outside the WebView, or hand it to an Intent | The browser shows WhatsApp’s web page |
whatsapp://send?... |
ACTION_VIEW Intent with the URL as data |
Open the https://wa.me/ version in a browser |
intent://...#Intent;...;end |
Parse it into an Intent, then start it | Load S.browser_fallback_url if the link has one |
upi://pay?... |
ACTION_VIEW Intent |
Show a message; there’s no web fallback |
market://details?... |
ACTION_VIEW Intent |
Open the Play Store web page |
My take: send every non-web scheme out of the WebView. None should ever fall through to loadUrl, because one missing branch is all it takes to put users on an error page.
The shouldOverrideUrlLoading fix
The fix is to check the scheme in shouldOverrideUrlLoading and start an Intent for anything that isn’t http or https. The WebViewClient reference describes this callback as the point where your app can take over a URL before the WebView loads it. Returning true stops the WebView from loading it.
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val uri = request.url
if (uri.scheme == "http" || uri.scheme == "https") return false
val intent = if (uri.scheme == "intent") {
Intent.parseUri(uri.toString(), Intent.URI_INTENT_SCHEME).apply {
addCategory(Intent.CATEGORY_BROWSABLE)
component = null
selector = null
}
} else {
Intent(Intent.ACTION_VIEW, uri)
}
try {
view.context.startActivity(intent)
} catch (e: ActivityNotFoundException) {
intent.getStringExtra("browser_fallback_url")?.let { view.loadUrl(it) }
}
return true
}
Three details matter here:
- Return
truefor every custom scheme. Returningfalselets the WebView try the URL and show the error. - Keep the
try/catch. The AdMob sample does the same: start the Intent, catchActivityNotFoundException, returntrue. - Treat
intent://links as untrusted. Clearing the component and selector, and adding the browsable category, keeps a page from opening an app screen that wasn’t meant to be opened from a link.
How intent:// links and fallbacks work
An intent:// link is a whole Android Intent packed into a URL. The Chrome intents guide shows the format: intent: plus a path, then #Intent;, optional package=, action=, scheme= and other fields, then end;.
The useful extra is S.browser_fallback_url, an encoded web address to open when no app can take the Intent. Chrome also limits what these links may do. Only activities with the android.intent.category.BROWSABLE filter can be opened this way, and Chrome won’t launch an app without a user tap. Copy both rules into your WebView.
Get the wa.me link right first
A broken wa.me link can look like a WebView bug when it’s really a formatting problem. WhatsApp’s click to chat help page says to use https://wa.me/<number> with the full phone number in international format, leaving out any zeroes, brackets or dashes.
To pre-fill a message, add ?text= and the URL-encoded text. A link with no number, https://wa.me/?text=..., shows the user a list of contacts to pick from. If you control the page, test the link in a phone browser before you debug the app.
UPI, Play Store and other payment links
UPI payment links fail in a WebView for the same reason WhatsApp links do: upi:// is a custom scheme. The UPI intent in WebView guide from one payment provider sends non-web URLs to an ACTION_VIEW Intent, catches ActivityNotFoundException, and returns true.
market:// links from ads or “Rate us” buttons work the same way. For anything that should leave your site but stays on the web, such as a partner’s checkout page, see opening external links in the browser.
Android 11 and checking whether WhatsApp is installed
Checking for WhatsApp before you open the link can backfire on newer Android versions. The package visibility guide says that when an app targets Android 11 (API level 30) or higher and queries installed apps, the system filters the results by default. A check can report WhatsApp missing when it’s installed.
Skip the check. Start the Intent and catch the exception, as the code does. You only need a <queries> entry if your UI must know in advance, for example to hide a WhatsApp button.
Testing and a limit worth knowing
Test every link type on a real phone with and without WhatsApp installed. A second phone or a work profile without WhatsApp shows you the fallback path. If a tap does nothing, inspect the WebView with Chrome DevTools and watch which URL the page actually requests.
The limitation: this fix needs code in the app. A no-code WebView builder handles these links however its template does, and you can’t change that template. Before you rely on WhatsApp or UPI buttons, build a test app and tap each one; the website to APK guide covers building and installing one. For mailto: and tel: links, the same idea applies with different Intent actions, covered in handling mailto and tel links.
FAQ
Why does a WhatsApp link work in Chrome but not in my WebView app?
Chrome knows how to hand whatsapp:// and intent:// addresses to other apps. A WebView doesn’t support custom URL schemes, so your app has to catch them in shouldOverrideUrlLoading and start an Intent itself.
What is the correct wa.me link format?
Use https://wa.me/ followed by the full phone number in international format, with no zeroes, brackets or dashes. Add ?text= and a URL-encoded message to pre-fill the chat.
What happens if WhatsApp isn’t installed?
startActivity throws ActivityNotFoundException. Catch it and send the user somewhere useful, such as the https://wa.me/ address in a browser, instead of letting the app crash or show an error page.
Do UPI payment links have the same problem?
Yes. A upi:// link is another custom scheme. Payment providers handle it the same way: pass it to an ACTION_VIEW Intent, catch ActivityNotFoundException and return true.
Sources
- How to use click to chat (WhatsApp Help Center)
- Android Intents with Chrome (Chrome for Developers)
- Optimize click behavior (AdMob WebView)
- UPI Intent in WebView - Android (Razorpay)
- Package visibility filtering on Android (Android Developers)
- WebViewClient (Android Developers)
- WhatsApp link works in browser but not inside WebView (B4X forum)