Developer Integration

Integrate Bot Connector into your app or website using the botconnector:// deep-link scheme.

URL Scheme

Bot Connector registers the botconnector:// custom URL scheme on iOS. Any app or web page can open the app or trigger specific flows using this scheme.

botconnector://[v1]/[action]?[params]

Add a Subscription

The most common integration: open Bot Connector and prompt the user to add a subscription URL.

botconnector://add-subscription?url={url}&name={name}&autoConnect={true|false}

Parameter	Description
`url`	Required. The subscription URL to import (URL-encoded).
`name`	Optional. Display name for the subscription.
`autoConnect`	Optional. Pass true to connect immediately after import.

JavaScript

jsif (await tryOpen('botconnector://add-subscription?url=' + encodeURIComponent(subUrl))) {
  return // app opened
}
window.location.href = 'https://apps.apple.com/app/id${APP_STORE_ID}'

Python

pyimport urllib.parse
url = "botconnector://add-subscription?url=" + urllib.parse.quote(sub_url)

Bash (macOS)

bashopen "botconnector://add-subscription?url=$(python3 -c 'import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))' "$SUB_URL")"

Swift

swiftlet encoded = subscriptionURL.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed)!
let url = URL(string: "botconnector://add-subscription?url=\(encoded)")!
UIApplication.shared.open(url)

Open the App

Use botconnector:// (no path) to simply bring the app to the foreground.

HTML Button Example

html<a href="botconnector://add-subscription?url=https%3A%2F%2Fexample.com%2Fsub.txt"
   style="display:inline-block;padding:.75rem 1.25rem;border-radius:9999px;background:#1E5BFF;color:#fff;text-decoration:none;font-weight:600;">
  Open in Bot Connector
</a>

QR Code Integration

Encode a botconnector:// URL in a QR code so mobile users can scan it to import a subscription without typing.

Smart App Banner

Add this meta tag to your web page to show the Smart App Banner on iOS Safari, linking to Bot Connector on the App Store.

html<meta name="apple-itunes-app" content="app-id=6767189747, app-argument=botconnector://" />

App-Installed vs Not-Installed

• If the app is installed, the deep link opens immediately.
• If the app is not installed, iOS shows a dialog asking the user to open the App Store. You can detect this in JavaScript using a timeout fallback.

Check If App Is Installed

Before triggering a deep link, check whether Bot Connector is installed.

Universal Links (Coming Soon)

Universal Links (https:// scheme with Apple App Site Association) are planned for v1.1. For now, use the botconnector:// scheme.

Versioning

The deep-link scheme version is encoded in the path prefix. Current version: v1. Omitting the version prefix defaults to v1.

Testing

Test deep links using the Safari address bar on a physical device or the iOS Simulator.

What Is Not Supported

• Background fetch or silent push via deep link.
• Passing credentials (passwords, private keys) via URL parameters. Use subscription URLs instead.
• Opening Bot Connector from a widget extension directly.