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

  1. On the phone, open Droidline's Setup tab and allow Notification access.
  2. 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 list
await d.notifyFilter(["com.google.android.gm", "com.google.android.apps.messaging"]);
console.log(await d.notifyFilter());   // read the current list
await d.NotifyFilterAsync(new[] { "com.google.android.gm", "com.google.android.apps.messaging" });
Console.WriteLine(string.Join(", ", await d.NotifyFilterAsync()));   // read the current list
droidline notify_filter com.google.android.gm,com.google.android.apps.messaging
droidline notify_filter

Wait 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" 60

The 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 it
const 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 running
var 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 it
droidline on_notification --package com.google.android.gm

The 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:

  • lines holds the separate lines when an app gathers several alerts into one notification, the way some apps show "3 new messages". text is often only a summary then, so read the amounts from lines. It is an empty list for ordinary notifications.
  • update is true when the app changed a notification that was already showing, such as a download whose progress moved, and false when it is new. The key stays the same across updates. If your code reacts to each deposit or each code, skip the events where update is true, 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