Notifications and webhooks
Receive a phone's notifications on the PC, wait for one, react to every one, reply, open or dismiss them, and forward them to a webhook.
Droidline can pass the notifications that arrive on a phone to your PC. It uses Android's notification access, which gives the full title and text (the accessibility service alone only sees a shortened version). To read text messages that are already stored on the phone, see Text messages, calls and contacts.
Turn it on
- On the phone, open Droidline's Setup tab and allow Notification access.
- Choose which apps may send their notifications to the PC. Nothing is sent until you do, which keeps private messages on the phone. Pick apps on the app's Status tab under Notifications sent to the PC, or from code:
d.notify_filter(["com.google.android.gm", "com.google.android.apps.messaging"])
print(d.notify_filter()) # read the current listawait d.notifyFilter(["com.google.android.gm", "com.google.android.apps.messaging"]);
console.log(await d.notifyFilter()); // read the current listawait d.NotifyFilterAsync(new[] { "com.google.android.gm", "com.google.android.apps.messaging" });
Console.WriteLine(string.Join(", ", await d.NotifyFilterAsync())); // read the current listdroidline notify_filter com.google.android.gm,com.google.android.apps.messaging
droidline notify_filterWait for one notification
wait_notification blocks until a matching notification arrives and returns it:
n = d.wait_notification("textContains", "verification code", 60)
print(n["package"], n["title"], n["text"])const n = await d.waitNotification("textContains", "verification code", 60);
console.log(n.package, n.title, n.text);var n = await d.WaitNotificationAsync("textContains", "verification code", 60);
Console.WriteLine($"{n.Package} {n.Title} {n.Text}");droidline wait_notification textContains "verification code" 60The first argument says what to compare: text or textContains look at both the title and the text, title at the title only, and package matches the app. Pass package= as well to only accept notifications from one app.
The server does the waiting, so other commands to the same phone keep running in the meantime. It waits for a notification that arrives after the call. To look at what is already showing, use notifications() or has_notification(by, value).
React to every notification
stop = d.on_notification(package="com.google.android.gm",
callback=lambda n: print(n["title"], n["text"]))
# ... your program keeps running; call stop() to end itconst stop = await d.onNotification({ package: "com.google.android.gm" },
(n) => console.log(n.title, n.text));
// ... call stop() to end it; until then the process keeps runningvar stop = await d.OnNotificationAsync(n => Console.WriteLine($"{n.Title} {n.Text}"),
package: "com.google.android.gm");
// ... your program keeps running; call stop.Dispose() to end itdroidline on_notification --package com.google.android.gmThe CLI prints one JSON line per notification until you press Ctrl+C, which makes it easy to pipe into other tools. A notification looks like this:
{"event":"notification","device":"k7d2q9xa","key":"0|com.google.android.gm|1|null|10123","package":"com.google.android.gm","title":"New message","text":"Lunch at 12?","lines":[],"time":1791360000000,"actions":["reply","mark_read"],"update":false}
From version 0.1.7 a notification also has two more fields:
linesholds the separate lines when an app gathers several alerts into one notification, the way some apps show "3 new messages".textis often only a summary then, so read the amounts fromlines. It is an empty list for ordinary notifications.updateistruewhen the app changed a notification that was already showing, such as a download whose progress moved, andfalsewhen it is new. Thekeystays the same across updates. If your code reacts to each deposit or each code, skip the events whereupdateistrue, or remember the keys you have handled.
Group summaries ("2 new messages" above a group) are never sent. The notifications inside the group arrive one by one.
Act on a notification
Each notification has a key. Use it to open, reply to or dismiss that notification:
for n in d.notifications():
if "Bank" in n["title"]:
d.notification_click(n["key"]) # opens what the notification points to
d.notification_reply(key, "On my way") # only for notifications with a reply action
d.notification_dismiss(key)for (const n of await d.notifications()) {
if (n.title.includes("Bank")) await d.notificationClick(n.key);
}
await d.notificationReply(key, "On my way");
await d.notificationDismiss(key);foreach (var n in await d.NotificationsAsync())
{
if (n.Get<string>("title")?.Contains("Bank") == true)
await d.NotificationClickAsync(n.Get<string>("key")!); // opens what the notification points to
}
await d.NotificationReplyAsync(key, "On my way"); // only for notifications with a reply action
await d.NotificationDismissAsync(key);KEY=$(droidline --json notifications | jq -r '.value[0].key')
droidline notification_click "$KEY"actions lists what a notification offers. notification_reply only works when it includes reply.
While the phone is offline
The phone keeps up to 500 recent notifications while it cannot reach the PC and sends them, in order, when it reconnects.
Webhooks
The server can POST matching notifications to any URL, so other systems can react without an SDK. Add a section per webhook to config.toml and restart droidline serve:
[[webhooks]]
url = "https://example.com/hooks/droidline"
package = "com.google.android.gm" # optional
text_contains = "order" # optional, matches title or text
device = "shelf-01" # optional
The body is the notification as JSON plus device and device_name. Every request is signed so you can check that it came from your server:
X-Droidline-Timestamp: 1791360000
X-Droidline-Signature: sha256=<hex HMAC-SHA256 of timestamp + "." + body>
Get the signing secret with droidline webhook secret. Checking the signature in a receiver:
import hashlib, hmac
def valid(secret: str, timestamp: str, body: bytes, signature: str) -> bool:
mac = hmac.new(secret.encode(), timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
return hmac.compare_digest("sha256=" + mac, signature)import { createHmac, timingSafeEqual } from "node:crypto";
function valid(secret, timestamp, body, signature) {
const mac = "sha256=" + createHmac("sha256", secret).update(`${timestamp}.`).update(body).digest("hex");
return mac.length === signature.length && timingSafeEqual(Buffer.from(mac), Buffer.from(signature));
}using System.Security.Cryptography;
using System.Text;
static bool Valid(string secret, string timestamp, byte[] body, string signature)
{
var signed = Encoding.UTF8.GetBytes(timestamp + ".").Concat(body).ToArray();
var mac = "sha256=" + Convert.ToHexString(HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), signed)).ToLowerInvariant();
return CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(mac), Encoding.UTF8.GetBytes(signature));
}Failed deliveries are retried twice, after 1 and 4 seconds.
One-time codes on Android 15 and later
Android 15 hides one-time codes inside notifications from apps that are not the system's own. You still get the notification, but the code is masked. Use the notification as a signal, then read the code inside the app:
d.wait_notification("package", "com.example.bank", 120)
d.launch("com.example.bank")
code = d.get_text("id", "otp_value")await d.waitNotification("package", "com.example.bank", 120);
await d.launch("com.example.bank");
const code = await d.getText("id", "otp_value");await d.WaitNotificationAsync("package", "com.example.bank", 120);
await d.LaunchAsync("com.example.bank");
var code = await d.GetTextAsync("id", "otp_value");droidline wait_notification package com.example.bank 120
droidline launch com.example.bank
droidline get_text id otp_value