wazap-mcp 0.16.0 → 0.17.0

package/README.md

@@ -545,9 +545,9 @@ response still carries `account_id`. `link_account` needs an account that
 already exists. Five accounts is advice, not a cap. One phone number is one
 account.
 
-An account can override the global webhook URL and secret in `accounts.json`
-(`webhook_url`, `webhook_secret`). `wazap webhook test --account work` posts
-with that account's id and name.
+An account can override the global webhook URL, secret and event list in
+`accounts.json` (`webhook_url`, `webhook_secret`, `webhook_events`).
+`wazap webhook test --account work` posts with that account's id and name.
 
 ## Several clients at once
 
@@ -704,38 +704,119 @@ What to know before exposing it:
 
 ## Outbound webhook
 
-A live inbound message can POST to one URL. Off by default. History sync
-is not posted. The only event is `message_received`.
+Live events POST to one URL. Off by default. History sync is not posted.
+Only `message_received` is posted unless you ask for more, because a consumer
+that answers every POST without reading `event` would otherwise answer the
+messages its own owner typed on the phone.
+
+The `event` field names one of three. `message_received` is a message another
+person sent. `message_sent` is a message this account sent itself, typed on
+the phone or on another linked device; a message wazap sent through its own
+tools is not announced, so a consumer can never be made to answer itself.
+`connection` says the link came up, went down or expired.
+
+Ask for the other two in `WAZAP_WEBHOOK_EVENTS`, comma-separated
+(`message_received,connection`), or say `all` for the three of them. Case
+does not matter and the spaces around a name are ignored. An unknown name
+fails `wazap status`, doctor and setup. An account carries its own list as
+`webhook_events` in `accounts.json`.
 
 ```bash
 npx wazap-mcp config webhook on    # asks for URL + secret (secret is not echoed)
 npx wazap-mcp webhook test         # POST a probe event
+npx wazap-mcp webhook test --event connection   # needs connection enabled
 npx wazap-mcp webhook test --account work
 npx wazap-mcp config webhook off
 ```
 
 On without a URL or secret fails `wazap status`, doctor and setup. A failed
 delivery retries twice (200 ms, then 500 ms), then sets `webhook.last_error`
-and leaves WhatsApp and MCP running. An account may set `webhook_url` and
-`webhook_secret` in `accounts.json`; those win over the global URL and secret.
+and leaves WhatsApp and MCP running. An account may set `webhook_url`,
+`webhook_secret` and `webhook_events` in `accounts.json`; those win over the
+global URL, secret and event list, and `config webhook off --account work`
+clears all three.
+
+`webhook test --event <name>` posts nothing and exits non-zero when that
+event is not enabled, and says what to enable it with. While the webhook is
+on, `wazap config` prints the events it posts on an `events:` line.
 
 HMAC: `X-Wazap-Signature` is `sha256=<hex>`, HMAC-SHA256 of the exact raw
 JSON body with the secret that signed it. Verify that raw body, not a
 re-serialized object. HTTPS only, except `http://` on loopback.
 
+`text` is a preview, cut at 2000 characters and ending in a single `…`.
+`truncated` is true when it was cut. For `kind: "audio"`, `text` is the
+transcription when wazap auto-transcribed the note itself, which it does for
+incoming notes only; the event waits up to 60 seconds for those words. In
+every other case `text` is the `[voice message · 0:42]` placeholder: a note
+you recorded yourself, a note longer than 600 seconds, a note WhatsApp stated
+no duration for, and a transcription that failed. `ts` is the original local
+time with a numeric offset, kept for consumers already reading it, and
+`timestamp` is the same instant in UTC.
+
+Events are not guaranteed to arrive in the order they happened. A message held
+for its transcript is overtaken by the messages behind it, so order by
+`timestamp` and not by arrival. Connection events are the exception: they are
+delivered in the order the link moved in.
+
+A message another person sent:
+
 ```json
 {
   "event": "message_received",
-  "from": "+15550100",
+  "from": "15550100",
   "chat_id": "15550100@s.whatsapp.net",
-  "ts": "2026-09-08T14:00:00+00:00",
-  "text": "hello, or a short preview",
+  "ts": "2026-09-08T17:00:00+03:00",
+  "timestamp": "2026-09-08T14:00:00.000Z",
+  "text": "hello, or a preview of something longer",
+  "truncated": false,
+  "kind": "text",
+  "from_me": false,
+  "is_self_chat": false,
   "message_id": "false_15550100@s.whatsapp.net_3EB0…",
   "account_id": "default",
   "account_name": "default"
 }
 ```
 
+A message sent from the phone, here in the "Message yourself" chat:
+
+```json
+{
+  "event": "message_sent",
+  "from": "15551234",
+  "chat_id": "15551234@s.whatsapp.net",
+  "ts": "2026-09-08T17:04:12+03:00",
+  "timestamp": "2026-09-08T14:04:12.000Z",
+  "text": "call the notary at 14:00 on Wednesday",
+  "truncated": false,
+  "kind": "text",
+  "from_me": true,
+  "is_self_chat": true,
+  "message_id": "true_15551234@s.whatsapp.net_3EB0…",
+  "account_id": "default",
+  "account_name": "default"
+}
+```
+
+A connection change. `status` is `linked`, `disconnected` or `expired`;
+`not_linked`, `linking` and `connecting` post nothing, and two changes that
+mean the same status post once.
+
+```json
+{
+  "event": "connection",
+  "status": "expired",
+  "timestamp": "2026-09-08T14:10:00.000Z",
+  "account_id": "default",
+  "account_name": "default"
+}
+```
+
+`connection` reports what the socket does while wazap is running. A clean
+shutdown posts nothing, and a crash posts nothing either, so silence does not
+mean the link is up. Poll `get_status` when you need to know that.
+
 ## Settings
 
 | Variable | Default | Meaning |
@@ -759,9 +840,10 @@ re-serialized object. HTTPS only, except `http://` on loopback.
 | `WAZAP_TRANSCRIBE_API_KEY` | unset | API key; `OPENAI_API_KEY` is the fallback. Never a flag. |
 | `WAZAP_TRANSCRIBE_URL` | `https://api.openai.com/v1` | OpenAI-compatible base URL. |
 | `WAZAP_TRANSCRIBE_MODEL` | `gpt-4o-mini-transcribe` | Model at that URL. |
-| `WAZAP_WEBHOOK` | `off` | `on` posts live inbound messages to the webhook URL. |
+| `WAZAP_WEBHOOK` | `off` | `on` posts the enabled events to the webhook URL. |
 | `WAZAP_WEBHOOK_URL` | unset | HTTPS endpoint. `http://` only on loopback. An account `webhook_url` wins. |
 | `WAZAP_WEBHOOK_SECRET` | unset | Shared secret for `X-Wazap-Signature`. Never a flag. An account `webhook_secret` wins. |
+| `WAZAP_WEBHOOK_EVENTS` | unset (`message_received`) | Which events to post, comma-separated, or `all`. An account `webhook_events` wins. |
 
 Flags beat environment variables, which beat `<data-dir>/.env`.
 

package/dist/accounts.js

@@ -2,7 +2,8 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, wri
 import { dirname } from "node:path";
 import { readLinkedAccount } from "./auth-state.js";
 import { accountPaths, paths } from "./config.js";
-import { WazapError } from "./errors.js";
+import { WazapError, asWazapError } from "./errors.js";
+import { parseWebhookEvents } from "./webhook.js";
 export const DEFAULT_ACCOUNT_ID = "default";
 export const ACCOUNT_ID_RE = /^[a-z0-9][a-z0-9-]{0,31}$/;
 const FIX_LIST = "Run `wazap account list`";
@@ -72,10 +73,13 @@ function parseAccountRecord(value, file) {
         }
         record.rate_limit = value.rate_limit;
     }
-    return { ...record, ...webhookFields(value.id, value.webhook_url, value.webhook_secret, ` in ${file}`) };
+    return {
+        ...record,
+        ...webhookFields(value.id, value.webhook_url, value.webhook_secret, value.webhook_events, ` in ${file}`),
+    };
 }
 /** Shared by load and `setWebhook` so a writer cannot persist what load refuses. */
-function webhookFields(id, url, secret, where = "", fix = "Fix or remove accounts.json") {
+function webhookFields(id, url, secret, events, where = "", fix = "Fix or remove accounts.json") {
     const fields = {};
     if (url !== undefined) {
         if (typeof url !== "string" || url.trim() === "") {
@@ -89,6 +93,19 @@ function webhookFields(id, url, secret, where = "", fix = "Fix or remove account
         }
         fields.webhook_secret = secret;
     }
+    if (events !== undefined) {
+        if (typeof events !== "string" || events.trim() === "") {
+            throw new WazapError("INVALID_ID", `Account "${id}"${where} has a bad webhook_events.`, fix);
+        }
+        const trimmed = events.trim();
+        try {
+            parseWebhookEvents(trimmed);
+        }
+        catch (err) {
+            throw new WazapError("INVALID_ID", `Account "${id}"${where} has a bad webhook_events: ${asWazapError(err).message}`, fix);
+        }
+        fields.webhook_events = trimmed;
+    }
     return fields;
 }
 function parseAccountsFile(value, file) {
@@ -200,7 +217,7 @@ export class AccountRegistry {
     setWebhook(id, webhook) {
         this.commit(this.withAccount(id, (account) => ({
             ...account,
-            ...webhookFields(id, webhook.url, webhook.secret, "", "Set a non-empty webhook URL or secret"),
+            ...webhookFields(id, webhook.url, webhook.secret, undefined, "", "Set a non-empty webhook URL or secret"),
         })));
     }
     /** Drop the per-account override so the account follows the global webhook again. */
@@ -209,6 +226,7 @@ export class AccountRegistry {
             const next = { ...account };
             delete next.webhook_url;
             delete next.webhook_secret;
+            delete next.webhook_events;
             return next;
         }));
     }

package/dist/config.js

@@ -163,6 +163,7 @@ export function parseCli(argv = process.argv.slice(2)) {
                 service: { type: "boolean" },
                 expose: { type: "boolean" },
                 yes: { type: "boolean", short: "y" },
+                event: { type: "string" },
                 account: { type: "string" },
                 name: { type: "string" },
                 help: { type: "boolean", short: "h" },
@@ -245,6 +246,7 @@ export function parseCli(argv = process.argv.slice(2)) {
             keepRunning: values.expose === true ? "expose" : values.service === true ? "service" : null,
             accountId: values.account,
             accountName: values.name,
+            webhookEvent: values.event,
         },
     };
 }

package/dist/index.js

@@ -26,7 +26,7 @@ Usage:
   wazap expose [tailscale|cloudflare|off]                  Give the running service a public https URL cloud agents can reach
   wazap config [writes on|off] [transcribe local|openai|off] [webhook on|off]
                                                            Show the effective settings, or change one
-  wazap webhook test [--account <id>]                      POST a test message_received to the configured webhook
+  wazap webhook test [--event <name>] [--account <id>]     POST a test event to the configured webhook
   wazap transcribe download [--model <alias>]              Fetch the whisper.cpp model into the data dir
   wazap transcribe test <audio file>                       Transcribe a local file with the configured provider
   wazap contacts resync                                    Fetch the phone's address book from WhatsApp again
@@ -46,6 +46,7 @@ Options:
   --data-dir <path>   Where wazap keeps its data (default ~/.wazap, or $WAZAP_DATA_DIR)
   --account <id>      With login, logout, status, contacts, config writes|webhook, webhook test:
                       pick this account. account add|enable|disable|default apply on server restart
+  --event <name>      With webhook test: message_received (default), message_sent or connection
   --name <name>       With account add: a display name
   --read-only         Refuse every write; the write tools are not registered at all
   --http              Serve Streamable HTTP instead of stdio
@@ -76,7 +77,8 @@ WAZAP_TRANSPORT, WAZAP_HOST, WAZAP_PORT, WAZAP_READ_TOKEN, WAZAP_WRITE_TOKEN, WA
 WAZAP_OAUTH_PASSWORD, WAZAP_RATE_LIMIT,
 WAZAP_NO_SHARE, WAZAP_NO_UPDATE_CHECK, WAZAP_TRANSCRIBE, WAZAP_TRANSCRIBE_AUTO,
 WAZAP_TRANSCRIBE_LANGUAGE, WAZAP_TRANSCRIBE_API_KEY, WAZAP_TRANSCRIBE_URL, WAZAP_TRANSCRIBE_MODEL,
-WAZAP_WHISPER_MODEL, WAZAP_WHISPER_BIN, WAZAP_WEBHOOK, WAZAP_WEBHOOK_URL, WAZAP_WEBHOOK_SECRET.
+WAZAP_WHISPER_MODEL, WAZAP_WHISPER_BIN, WAZAP_WEBHOOK, WAZAP_WEBHOOK_URL,
+WAZAP_WEBHOOK_SECRET, WAZAP_WEBHOOK_EVENTS.
 An optional <data-dir>/.env is loaded if present.`;
 async function main() {
     const invocation = parseCli();

package/dist/messages.js

@@ -323,12 +323,10 @@ export function isStubEvent(raw) {
     return stubKind(raw) !== undefined;
 }
 /**
- * A person sent this inbound. Stubs, protocol machinery and system notices
- * are not `message_received`.
+ * Something a person sent or received, as opposed to a control notice, a stub
+ * or a system line. The webhook posts these in both directions.
  */
-export function isUserInboundMessage(raw) {
-    if (raw.key.fromMe)
-        return false;
+export function isUserMessage(raw) {
     if (isControlMessage(raw) || isStubEvent(raw))
         return false;
     return messageType(raw) !== "system";

package/dist/sent-ids.js

@@ -0,0 +1,40 @@
+/**
+ * Baileys message ids this process sent, kept only long enough for WhatsApp to
+ * echo them back. This is a backstop, not the mechanism: Baileys re-emits a local
+ * send as an `append`, and the webhook path runs on `notify` only, so that gate is
+ * what keeps wazap from announcing its own sends. Do not delete it believing this
+ * replaces it. What lands here is an echo that arrives as `notify` anyway, such as
+ * a server-side redelivery or a future send path. Identity is the bare `key.id`,
+ * unique per sender and stable while a chat jid is re-canonicalised, never the
+ * composite message id and never the text.
+ */
+export const SENT_TTL_MS = 10 * 60_000;
+export class SentIds {
+    noted = new Map();
+    ttlMs;
+    clock;
+    constructor(opts = {}) {
+        this.ttlMs = opts.ttlMs ?? SENT_TTL_MS;
+        this.clock = opts.now ?? Date.now;
+    }
+    note(id) {
+        this.prune();
+        this.noted.set(id, this.clock());
+    }
+    has(id) {
+        this.prune();
+        return this.noted.has(id);
+    }
+    get size() {
+        this.prune();
+        return this.noted.size;
+    }
+    /** No timer: a long-lived service prunes on the reads and writes it already does. */
+    prune() {
+        const cutoff = this.clock() - this.ttlMs;
+        for (const [id, at] of this.noted) {
+            if (at <= cutoff)
+                this.noted.delete(id);
+        }
+    }
+}

package/dist/settings.js

@@ -8,7 +8,7 @@ import { lockHolder } from "./lock.js";
 import { say } from "./logger.js";
 import { maskKey, readTranscribeSettings, requireSafeUrl, stripPasted, transcribeReady, } from "./transcribe/index.js";
 import { brand, dim, fix, ok, shortPath, warn } from "./ui.js";
-import { WEBHOOK_ON_FIX, WEBHOOK_TEST_FIX, WebhookSink, readWebhookSettings, requireWebhookUrl, } from "./webhook.js";
+import { WEBHOOK_ON_FIX, WEBHOOK_TEST_FIX, WebhookSink, parseWebhookEvent, readWebhookSettings, requireWebhookUrl, } from "./webhook.js";
 /**
  * dotenv 16 treats an unquoted `#` as a comment, even with no space, and
  * trims unquoted padding. Quote so a secret like `p@ss#word` round-trips.
@@ -154,8 +154,13 @@ function transcribeRows(config) {
 }
 function accountWebhook(config) {
     const selected = resolveAccount(config.dataDir, config.accountId);
-    const override = { url: selected.account.webhook_url, secret: selected.account.webhook_secret };
-    const source = override.url !== undefined || override.secret !== undefined ? "accounts.json" : config.sources.webhook;
+    const override = {
+        url: selected.account.webhook_url,
+        secret: selected.account.webhook_secret,
+        events: selected.account.webhook_events,
+    };
+    const fromAccount = override.url !== undefined || override.secret !== undefined || override.events !== undefined;
+    const source = fromAccount ? "accounts.json" : config.sources.webhook;
     return { override, source };
 }
 function webhookRows(config) {
@@ -165,7 +170,11 @@ function webhookRows(config) {
         case "off":
             return [`webhook: off (${source})`];
         case "ready":
-            return [`webhook: on (${new URL(settings.url).host}) (${source})`, `secret: ${maskKey(settings.secret)}`];
+            return [
+                `webhook: on (${new URL(settings.url).host}) (${source})`,
+                `secret: ${maskKey(settings.secret)}`,
+                `events: ${settings.events.join(", ")}`,
+            ];
         case "invalid":
             return [`webhook: ${settings.detail}${settings.fix === "" ? "" : ` — ${settings.fix}`}`];
         default: {
@@ -191,7 +200,7 @@ async function applyWebhook(config, value) {
             return;
         }
         setWebhookFlag(config, "off");
-        say(ok("webhook: off — live inbound messages are not posted anywhere. Turn it on with `wazap config webhook on`."));
+        say(ok("webhook: off — nothing is posted anywhere. Turn it on with `wazap config webhook on`."));
         say(dim(`Stored in ${shortPath(paths(config.dataDir).envFile)}.`));
         warnIfServerRunning(config);
         return;
@@ -235,7 +244,7 @@ async function enableWebhook(config) {
         // The switch stays global; the URL and secret are this account's override.
         AccountRegistry.load(config.dataDir).setWebhook(config.accountId, { url, secret });
         setEnvSetting(p.envFile, "WAZAP_WEBHOOK", "on");
-        say(ok(`webhook: on for ${config.accountId} — live inbound messages POST to ${new URL(url).host} as message_received.`));
+        say(ok(`webhook: on for ${config.accountId} — messages both ways and link changes POST to ${new URL(url).host}.`));
         say(dim(`URL and secret stored in ${shortPath(p.accountsFile)}; WAZAP_WEBHOOK=on in ${shortPath(p.envFile)}.`));
         warnIfServerRunning(config);
         return;
@@ -243,7 +252,7 @@ async function enableWebhook(config) {
     setEnvSetting(p.envFile, "WAZAP_WEBHOOK", "on");
     setEnvSetting(p.envFile, "WAZAP_WEBHOOK_URL", url);
     setEnvSetting(p.envFile, "WAZAP_WEBHOOK_SECRET", secret);
-    say(ok(`webhook: on — live inbound messages POST to ${new URL(url).host} as message_received.`));
+    say(ok(`webhook: on — messages both ways and link changes POST to ${new URL(url).host}.`));
     say(dim(`Stored in ${shortPath(p.envFile)}.`));
     warnIfServerRunning(config);
 }
@@ -251,8 +260,9 @@ function setWebhookFlag(config, value) {
     setEnvSetting(paths(config.dataDir).envFile, "WAZAP_WEBHOOK", value);
 }
 async function testWebhook(config) {
+    const event = parseWebhookEvent(config.webhookEvent);
     const selected = resolveAccount(config.dataDir, config.accountId);
-    const result = await new WebhookSink(process.env, { account: selected.account }).sendTest();
+    const result = await new WebhookSink(process.env, { account: selected.account }).sendTest(event);
     if (result.ok) {
         say(ok("webhook: test delivered"));
         return;

package/dist/transcribe/queue.js

@@ -9,16 +9,31 @@ export class TranscribeQueue {
     pending = [];
     inFlight = null;
     waiters = [];
+    /** One entry per id queued or in flight, which is also how a repeat enqueue is spotted. */
+    settling = new Map();
     constructor(run) {
         this.run = run;
     }
-    /** Ignores an id already queued or in flight. */
+    /**
+     * Settles when this id's own run settles, so a caller can wait for one
+     * transcript without waiting for the queue behind it. It never rejects: a run
+     * that failed settles like one that worked, because ingestion must never see a
+     * transcription fail. An id already queued or in flight hands back the promise
+     * already outstanding, so two enqueues of one id share one settle.
+     */
     enqueue(id) {
-        if (this.inFlight === id || this.pending.includes(id))
-            return;
+        const outstanding = this.settling.get(id);
+        if (outstanding !== undefined)
+            return outstanding.promise;
+        let settle;
+        const promise = new Promise((resolve) => {
+            settle = resolve;
+        });
+        this.settling.set(id, { promise, settle });
         this.pending.push(id);
         if (this.inFlight === null)
             void this.drain();
+        return promise;
     }
     get size() {
         return this.pending.length + (this.inFlight === null ? 0 : 1);
@@ -43,6 +58,9 @@ export class TranscribeQueue {
                 logError(`transcribe ${id}`, err);
             }
             this.inFlight = null;
+            const done = this.settling.get(id);
+            this.settling.delete(id);
+            done?.settle();
         }
         const waiters = this.waiters;
         this.waiters = [];

package/dist/webhook.js

@@ -1,6 +1,8 @@
 /**
- * W1 outbound webhook: one live event (`message_received`). Global URL and
- * secret live in `.env`; an account may override either. Delivery never throws
+ * W1 outbound webhook: three live events (`message_received`, `message_sent`
+ * and `connection`), of which only `message_received` is posted unless
+ * `WAZAP_WEBHOOK_EVENTS` asks for more. Global URL, secret and event list live
+ * in `.env`; an account may override any of the three. Delivery never throws
  * into the WhatsApp or MCP path.
  */
 import { createHmac, timingSafeEqual } from "node:crypto";
@@ -9,13 +11,19 @@ import { WAZAP_VERSION } from "./config.js";
 import { WazapError, asWazapError } from "./errors.js";
 import { logError } from "./logger.js";
 import { redact, stripPasted } from "./transcribe/index.js";
+export const WEBHOOK_EVENTS = ["message_received", "message_sent", "connection"];
+/** What `webhook test` posts when `--event` does not name another one. */
 export const WEBHOOK_EVENT = "message_received";
 export const WEBHOOK_TIMEOUT_MS = 10_000;
-export const WEBHOOK_TEXT_MAX = 500;
+export const WEBHOOK_TEXT_MAX = 2000;
 export const WEBHOOK_RETRY_DELAYS_MS = [200, 500];
 export const WEBHOOK_ON_FIX = "run `wazap config webhook on`";
 export const WEBHOOK_URL_FIX = "set WAZAP_WEBHOOK_URL to an https:// URL, or http:// on 127.0.0.1";
 export const WEBHOOK_TEST_FIX = "run `wazap webhook test`";
+export const WEBHOOK_EVENT_FIX = `pass one of ${WEBHOOK_EVENTS.join(", ")}`;
+export const WEBHOOK_EVENTS_DEFAULT = ["message_received"];
+export const WEBHOOK_EVENTS_FIX = `set WAZAP_WEBHOOK_EVENTS to all or a comma-separated list of ${WEBHOOK_EVENTS.join(", ")}`;
+export const WEBHOOK_KINDS = ["text", "audio", "image", "other"];
 const OFF = new Set(["", "off", "0", "no", "none", "false"]);
 const ON = new Set(["on", "1", "true", "yes"]);
 const LOOPBACK = new Set(["127.0.0.1", "::1", "localhost"]);
@@ -36,6 +44,8 @@ export function readWebhookSettings(env = process.env, override = {}) {
     const overrideSecret = stripPasted(override.secret ?? "");
     const urlRaw = (overrideUrl || stripPasted(env.WAZAP_WEBHOOK_URL ?? "")).replace(/\/+$/, "");
     const secret = overrideSecret || stripPasted(env.WAZAP_WEBHOOK_SECRET ?? "");
+    const overrideEvents = stripPasted(override.events ?? "");
+    const eventsRaw = overrideEvents || stripPasted(env.WAZAP_WEBHOOK_EVENTS ?? "");
     const missingUrl = urlRaw === "";
     const missingSecret = secret === "";
     if (missingUrl && missingSecret) {
@@ -46,7 +56,7 @@ export function readWebhookSettings(env = process.env, override = {}) {
     if (missingSecret)
         return { kind: "invalid", detail: "on without a secret", fix: WEBHOOK_ON_FIX };
     try {
-        return { kind: "ready", url: requireWebhookUrl(urlRaw), secret };
+        return { kind: "ready", url: requireWebhookUrl(urlRaw), secret, events: parseWebhookEvents(eventsRaw) };
     }
     catch (err) {
         const failure = asWazapError(err);
@@ -84,21 +94,129 @@ export function webhookSignatureMatches(body, secret, header) {
 }
 export function previewText(text) {
     if (text.length <= WEBHOOK_TEXT_MAX)
-        return text;
-    return `${text.slice(0, WEBHOOK_TEXT_MAX - 1)}…`;
+        return { text, truncated: false };
+    return { text: `${text.slice(0, WEBHOOK_TEXT_MAX - 1)}…`, truncated: true };
 }
-export function asWebhookPayload(view, account) {
+/**
+ * Every message type collapses into one of four buckets a consumer can switch
+ * on. A recorded note (`voice`) and an attached file (`audio`) share `audio`,
+ * because both carry speech and both can arrive transcribed.
+ */
+const KIND_BY_TYPE = {
+    text: "text",
+    image: "image",
+    audio: "audio",
+    voice: "audio",
+    video: "other",
+    document: "other",
+    sticker: "other",
+    location: "other",
+    contact: "other",
+    poll: "other",
+    reaction: "other",
+    deleted: "other",
+    view_once: "other",
+    call: "other",
+    system: "other",
+    unknown: "other",
+};
+/**
+ * `--event` as typed on the command line. The one place a string becomes an
+ * event, so nothing downstream has to widen the union back to `string`.
+ */
+export function parseWebhookEvent(raw) {
+    if (raw === undefined)
+        return WEBHOOK_EVENT;
+    const value = raw.trim();
+    const known = WEBHOOK_EVENTS.find((event) => event === value);
+    if (known === undefined) {
+        throw new WazapError("INVALID_ID", `Unknown webhook event "${raw}".`, WEBHOOK_EVENT_FIX);
+    }
+    return known;
+}
+/**
+ * `WAZAP_WEBHOOK_EVENTS` as an operator typed it. An unset list is the 0.16.0
+ * set, so a consumer that answers every POST without reading `event` keeps
+ * hearing only what it already handled.
+ */
+export function parseWebhookEvents(raw) {
+    const tokens = raw.split(",").map((token) => token.trim()).filter((token) => token !== "");
+    if (tokens.length === 0)
+        return WEBHOOK_EVENTS_DEFAULT;
+    const wanted = new Set();
+    for (const token of tokens) {
+        const value = token.toLowerCase();
+        if (value === "all") {
+            for (const event of WEBHOOK_EVENTS)
+                wanted.add(event);
+            continue;
+        }
+        const known = WEBHOOK_EVENTS.find((event) => event === value);
+        if (known === undefined) {
+            throw new WazapError("INVALID_ID", `Unknown webhook event "${token}".`, WEBHOOK_EVENTS_FIX);
+        }
+        wanted.add(known);
+    }
+    return WEBHOOK_EVENTS.filter((event) => wanted.has(event));
+}
+export function webhookKind(type) {
+    return KIND_BY_TYPE[type];
+}
+/**
+ * `null` is a state nobody outside wazap can act on, so it posts nothing:
+ * `linking` and `connecting` are steps on the way to `connected`, and
+ * `not_linked` is the state before any credentials exist. Every credential
+ * failure collapses to `expired`, the one thing a consumer does something about.
+ */
+const CONNECTION_STATUS = {
+    not_linked: null,
+    linking: null,
+    connecting: null,
+    connected: "linked",
+    disconnected: "disconnected",
+    logged_out: "expired",
+    session_corrupt: "expired",
+    auth_failure: "expired",
+};
+export function webhookConnectionStatus(status) {
+    return CONNECTION_STATUS[status];
+}
+/**
+ * The same instant as the local-offset `ts`, never a fresh read of the clock. The
+ * instant is the sender's to state, and a peer that states a nonsense one would
+ * otherwise cost the whole delivery, so an unparseable `ts` costs this one field.
+ */
+function utcTimestamp(iso) {
+    const at = new Date(iso);
+    return Number.isNaN(at.getTime()) ? new Date().toISOString() : at.toISOString();
+}
+export function asWebhookPayload({ event, view, account, isSelfChat }) {
+    const { text, truncated } = previewText(view.transcript ?? view.text);
     return {
-        event: WEBHOOK_EVENT,
+        event,
         from: view.sender.phone ?? view.sender.id,
         chat_id: view.chat_id,
         ts: view.timestamp,
-        text: previewText(view.text),
+        timestamp: utcTimestamp(view.timestamp),
+        text,
+        truncated,
+        kind: webhookKind(view.type),
+        from_me: view.from_me,
+        is_self_chat: isSelfChat,
         message_id: view.message_id,
         account_id: account.id,
         account_name: account.name,
     };
 }
+export function asConnectionPayload({ status, account, at }) {
+    return {
+        event: "connection",
+        status,
+        timestamp: new Date(at).toISOString(),
+        account_id: account.id,
+        account_name: account.name,
+    };
+}
 export function webhookInfo(settings, lastError) {
     switch (settings.kind) {
         case "off":
@@ -113,7 +231,7 @@ export function webhookInfo(settings, lastError) {
         }
     }
 }
-/** Posts `message_received` when the webhook is on and valid. Never throws. */
+/** Posts an event when the webhook is on and valid. Never throws. */
 export class WebhookSink {
     env;
     lastError = null;
@@ -130,34 +248,51 @@ export class WebhookSink {
         return readWebhookSettings(this.env, {
             url: this.account?.webhook_url,
             secret: this.account?.webhook_secret,
+            events: this.account?.webhook_events,
         });
     }
     info() {
         return webhookInfo(this.settings(), this.lastError);
     }
+    /**
+     * True only when the consumer accepted the POST, so a caller whose event has no
+     * later transition to recover with can tell a delivery from a drop. Still never
+     * throws.
+     */
     async notify(payload) {
         try {
             const settings = this.settings();
             if (settings.kind !== "ready")
-                return;
-            await this.postEvent(payload, settings);
+                return false;
+            if (!settings.events.includes(payload.event))
+                return false;
+            return (await this.postEvent(payload, settings)).ok;
         }
         catch (err) {
             const settings = this.settings();
             const secret = settings.kind === "ready" ? settings.secret : "";
             this.lastError = redact(err instanceof Error ? err.message : String(err), secret);
             logError("webhook", this.lastError);
+            return false;
         }
     }
-    async sendTest() {
+    async sendTest(event = WEBHOOK_EVENT) {
         const settings = this.settings();
         switch (settings.kind) {
             case "off":
                 return { ok: false, error: "Webhook is off.", fix: WEBHOOK_ON_FIX };
             case "invalid":
                 return { ok: false, error: settings.detail, fix: settings.fix };
-            case "ready":
-                return this.postEvent(testPayload(this.account), settings);
+            case "ready": {
+                if (!settings.events.includes(event)) {
+                    return {
+                        ok: false,
+                        error: `Webhook event "${event}" is not enabled.`,
+                        fix: enableEventFix(settings.events, event, this.account),
+                    };
+                }
+                return this.postEvent(testPayload(event, this.account), settings);
+            }
             default: {
                 const _exhaustive = settings;
                 return _exhaustive;
@@ -169,7 +304,7 @@ export class WebhookSink {
         const attempts = 1 + this.retryDelays.length;
         let last = { ok: false, error: "webhook POST failed", fix: "check the webhook URL is reachable and returns 2xx" };
         for (let i = 0; i < attempts; i++) {
-            last = await this.postOnce(body, settings);
+            last = await this.postOnce(body, payload.event, settings);
             if (last.ok) {
                 this.lastError = null;
                 return last;
@@ -185,14 +320,14 @@ export class WebhookSink {
         logError("webhook", last.error);
         return last;
     }
-    async postOnce(body, settings) {
+    async postOnce(body, event, settings) {
         try {
             const response = await this.post(settings.url, {
                 method: "POST",
                 headers: {
                     "content-type": "application/json",
                     "user-agent": `wazap/${WAZAP_VERSION}`,
-                    "x-wazap-event": WEBHOOK_EVENT,
+                    "x-wazap-event": event,
                     "x-wazap-signature": webhookSignature(body, settings.secret),
                 },
                 body,
@@ -208,16 +343,31 @@ export class WebhookSink {
         }
     }
 }
-function testPayload(account) {
+/** A list is set whole, so enabling one event means naming the ones already on. */
+function enableEventFix(active, event, account) {
+    const both = WEBHOOK_EVENTS.filter((known) => active.includes(known) || known === event).join(",");
+    if (account?.webhook_events === undefined)
+        return `set WAZAP_WEBHOOK_EVENTS=${both}, or all`;
+    return `set webhook_events for "${account.id}" in accounts.json to ${both}, or all`;
+}
+function testPayload(event, account) {
+    const now = new Date().toISOString();
+    const named = { account_id: account?.id ?? "default", account_name: account?.name ?? "default" };
+    if (event === "connection")
+        return { event, status: "linked", timestamp: now, ...named };
     return {
-        event: WEBHOOK_EVENT,
+        event,
         from: "wazap",
         chat_id: "test@s.whatsapp.net",
-        ts: new Date().toISOString(),
+        ts: now,
+        timestamp: now,
         text: "wazap webhook test",
+        truncated: false,
+        kind: "text",
+        from_me: event === "message_sent",
+        is_self_chat: false,
         message_id: "test",
-        account_id: account?.id ?? "default",
-        account_name: account?.name ?? "default",
+        ...named,
     };
 }
 function hostOf(url) {

package/dist/whatsapp.js

@@ -21,13 +21,14 @@ import { Notes } from "./notes.js";
 import { asGifMedia, assertMediaSource, describe, loadMedia, loadProfilePicture, mediaContent, mediaFilename } from "./outgoing-media.js";
 import { makePreview, videoFrame } from "./previews.js";
 import { decodeMessage, encode, Store } from "./store.js";
-import { buildMessageView, callInfo, formatAge, isCallPlaceholder, isControlMessage, isStubEvent, isUserInboundMessage, isoWithOffset, mediaInfo, mentionedJids, messageIdFor, messageText, messageTimestampMs, messageType, protoNumber, quotedSenderJid, reactionOf, thumbnailOf, viewText, voiceSeconds, } from "./messages.js";
+import { buildMessageView, callInfo, formatAge, isCallPlaceholder, isControlMessage, isStubEvent, isUserMessage, isoWithOffset, mediaInfo, mentionedJids, messageIdFor, messageText, messageTimestampMs, messageType, protoNumber, quotedSenderJid, reactionOf, thumbnailOf, viewText, voiceSeconds, } from "./messages.js";
 import { PAIRING_TIMEOUT_MS, WA_BROWSER, prettyCode, startPairing } from "./pairing.js";
 import { readTranscribeSettings, transcribeFile, TranscribeQueue, transcribeReady, } from "./transcribe/index.js";
 import { DraftStore } from "./drafts.js";
 import { RateLimiter } from "./ratelimit.js";
 import { maskNumber } from "./ui.js";
-import { WebhookSink, asWebhookPayload } from "./webhook.js";
+import { SentIds } from "./sent-ids.js";
+import { WebhookSink, asConnectionPayload, asWebhookPayload, webhookConnectionStatus, } from "./webhook.js";
 /** Reconnect pacing. A closed socket used to be retried instantly, which turns
  * any persistent rejection into a login storm — WhatsApp answers that by
  * throttling the account and refusing to link *any* new device to it, phone
@@ -70,6 +71,8 @@ const CALL_DEDUPE_SCAN = 20;
 const HISTORY_STORE_CAP_PER_CHAT = 2_000;
 /** Ten minutes of speech. Past that, auto-transcribing is a bill nobody asked for. */
 const AUTO_TRANSCRIBE_MAX_SECONDS = 600;
+/** How long a message event waits for the transcript of the voice note it carries. */
+const WEBHOOK_TRANSCRIPT_WAIT_MS = 60_000;
 const DIR_MODE = 0o700;
 const FILE_MODE = 0o600;
 /**
@@ -188,6 +191,12 @@ export class WhatsAppService {
     drafts = new DraftStore();
     writes;
     webhook;
+    /** Sends of our own, so their `fromMe` echo is never announced as `message_sent`. */
+    sentByWazap = new SentIds();
+    /** The last status a consumer was told, so several internal states collapse into one event. */
+    lastWebhookStatus = null;
+    /** Connection posts run one at a time, so a consumer sees the order the link moved in. */
+    connectionPosts = Promise.resolve();
     accountRecord;
     effectiveReadOnly;
     effectiveRateLimit;
@@ -385,6 +394,36 @@ export class WhatsAppService {
             return;
         this.status = next;
         this.statusSince = Date.now();
+        this.queueConnectionWebhook(next);
+    }
+    /**
+     * Several internal states map to one thing a consumer acts on, so the guard is
+     * on the mapped status, and it advances only on a post the consumer actually
+     * received: an endpoint that was down for `expired` hears it on the next
+     * change instead of never, since re-linking needs a human and there is no
+     * later transition to recover with. One chain, because a post can occupy half
+     * a minute in retries and a flapping link would otherwise land `linked` and
+     * `disconnected` out of order. Running the guard inside the chain is what makes
+     * "only on change" true of what arrives rather than of what was attempted. The
+     * chain rests on `notify` never throwing, so it also catches: a rejection here
+     * would silence every later change instead of one.
+     */
+    queueConnectionWebhook(status) {
+        const mapped = webhookConnectionStatus(status);
+        if (mapped === null)
+            return;
+        const at = this.statusSince;
+        this.connectionPosts = this.connectionPosts
+            .then(async () => {
+            if (mapped === this.lastWebhookStatus)
+                return;
+            if (this.stopped || this.webhook.settings().kind !== "ready")
+                return;
+            if (await this.webhook.notify(asConnectionPayload({ status: mapped, account: this.accountRecord, at }))) {
+                this.lastWebhookStatus = mapped;
+            }
+        })
+            .catch((err) => logError("webhook", err));
     }
     getStatus() {
         const inboundAt = this.latestInboundAt();
@@ -1459,8 +1498,8 @@ export class WhatsAppService {
                         continue;
                     this.lastInboundAt = Math.max(this.lastInboundAt ?? 0, messageTimestampMs(raw));
                 }
-                this.queueTranscripts(stored);
-                this.queueWebhook(stored);
+                const transcribing = this.queueTranscripts(stored);
+                this.queueWebhook(stored, transcribing);
                 this.noteArrivals(stored);
             }
             void this.appendHistory(stored);
@@ -2023,21 +2062,26 @@ export class WhatsAppService {
         return this.transcribe;
     }
     /**
-     * Live inbound a person sent, same notify gate as transcription: a history
-     * sync must not POST the backlog, and stubs or system notices are not
-     * `message_received`. Failures stay on `webhook.last_error` and never
-     * reject this path.
+     * Live messages both ways, same notify gate as transcription: a history sync
+     * must not POST the backlog, and stubs or system notices are not events. That
+     * gate is also what keeps wazap's own sends quiet in production, since Baileys
+     * re-emits a local send as an `append`; `sentByWazap` is the id-level backstop
+     * for an echo that does arrive as `notify`. Failures stay on
+     * `webhook.last_error` and never reject this path.
      */
-    queueWebhook(arrived) {
+    queueWebhook(arrived, transcribing) {
         if (this.stopped || this.webhook.settings().kind !== "ready")
             return;
         for (const raw of arrived) {
-            if (!isUserInboundMessage(raw))
+            if (!isUserMessage(raw))
                 continue;
             try {
                 const jid = this.canonical(raw.key.remoteJid ?? "");
                 const sid = messageIdFor(raw.key, jid);
-                void this.webhook.notify(asWebhookPayload(this.viewOf(sid, jid), this.accountRecord)).catch((err) => {
+                if (raw.key.fromMe && raw.key.id && this.sentByWazap.has(raw.key.id))
+                    continue;
+                const event = raw.key.fromMe ? "message_sent" : "message_received";
+                void this.postMessageEvent({ sid, jid, event, transcript: transcribing.get(sid) }).catch((err) => {
                     logError("webhook", err);
                 });
             }
@@ -2046,6 +2090,29 @@ export class WhatsAppService {
             }
         }
     }
+    /**
+     * A transcript lands after ingestion returns, so a message that just went onto
+     * the transcribe queue waits for it, bounded, before the view is built:
+     * `viewOf` reads `store.transcripts` fresh, so the wait is the whole reason a
+     * voice note's webhook can carry its words. The wait is on that one message's
+     * transcript, never on the queue, so a note is never held for the notes behind
+     * it. The timer is unreferenced so it can never hold the process open.
+     */
+    async postMessageEvent(args) {
+        if (args.transcript !== undefined) {
+            await Promise.race([args.transcript, sleep(WEBHOOK_TRANSCRIPT_WAIT_MS, undefined, { ref: false })]);
+        }
+        if (this.stopped) {
+            logError("webhook", `dropped ${args.event} for ${args.sid}: the service stopped while waiting for a transcript`);
+            return;
+        }
+        await this.webhook.notify(asWebhookPayload({
+            event: args.event,
+            view: this.viewOf(args.sid, args.jid),
+            account: this.accountRecord,
+            isSelfChat: this.isMe(args.jid),
+        }));
+    }
     /**
      * Only what genuinely arrived, which is why this hangs off the notify branch
      * rather than off ingestMessages: a history sync replays a backlog, and
@@ -2053,11 +2120,14 @@ export class WhatsAppService {
      * only, and only ones whose length WhatsApp stated and kept short, since an
      * audio file is something the sender chose to attach and a recording of
      * unknown length is unbounded. Anything skipped here is still one
-     * transcribe_audio call away. A service on its way out starts nothing.
+     * transcribe_audio call away. A service on its way out starts nothing. Each
+     * sid it enqueued carries the promise that settles when that one transcript
+     * does, which is what a held webhook event waits on.
      */
     queueTranscripts(arrived) {
+        const queued = new Map();
         if (this.stopped || this.transcribeQueue === null)
-            return;
+            return queued;
         for (const raw of arrived) {
             if (raw.key.fromMe || messageType(raw) !== "voice")
                 continue;
@@ -2067,8 +2137,9 @@ export class WhatsAppService {
             const sid = messageIdFor(raw.key, this.canonical(raw.key.remoteJid ?? ""));
             if (this.store.transcripts.has(sid))
                 continue;
-            this.transcribeQueue.enqueue(sid);
+            queued.set(sid, this.transcribeQueue.enqueue(sid));
         }
+        return queued;
     }
     messageOrThrow(messageId) {
         const raw = this.store.messages.get(messageId);
@@ -2238,6 +2309,8 @@ export class WhatsAppService {
             return { message_id: `unknown_${jid}_${randomUUID()}`, chat_id: jid, text, timestamp: isoWithOffset(Date.now()) };
         }
         const sid = messageIdFor(sent.key, jid);
+        if (sent.key.id)
+            this.sentByWazap.note(sent.key.id);
         this.store.putMessage(sid, jid, sent);
         this.markStoreDirty();
         return { message_id: sid, chat_id: jid, text, timestamp: isoWithOffset(messageTimestampMs(sent)) };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wazap-mcp",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "mcpName": "io.github.razvangirgiz/wazap",
   "description": "WhatsApp for your AI agent. MCP server over Baileys: pairing-code login, several accounts, 33 tools, stdio or HTTP.",
   "license": "MIT",