@getdial/cli 0.37.2 → 0.39.0

package/dist/cli.js

@@ -16,6 +16,8 @@ import { runWaitFor } from "./commands/wait-for.js";
 import { runNumberList } from "./commands/number/list.js";
 import { runNumberPurchase } from "./commands/number/purchase.js";
 import { runNumberSet } from "./commands/number/set.js";
+import { runNumberWhatsapp } from "./commands/number/whatsapp.js";
+import { runGroupList } from "./commands/group/list.js";
 import { runMessageSend } from "./commands/message/send.js";
 import { runMessageReply } from "./commands/message/reply.js";
 import { runMessageList } from "./commands/message/list.js";
@@ -163,6 +165,7 @@ number
     .option("--inbound-language <bcp47>", "language tag inbound calls are pinned to (default: detect from the caller's country prefix, alongside en-US)")
     .option("--area-code <code>", "preferred US area code (only US numbers can be provisioned; ignored with --include-imessage)")
     .option("--include-imessage", "provision an iMessage number (pay-as-you-go only; provisioned asynchronously — poll `dial number list` until ready)")
+    .option("--whatsapp", "also connect WhatsApp to the new line (beta, enabled per account). Requires --include-imessage: WhatsApp is a channel on an iMessage line")
     .option("--json", "machine-readable output")
     .action(async (opts) => process.exit(await runNumberPurchase({
     inboundInstruction: opts.inboundInstruction,
@@ -171,8 +174,14 @@ number
     inboundLanguage: opts.inboundLanguage,
     areaCode: opts.areaCode,
     includeImessage: !!opts.includeImessage,
+    whatsapp: !!opts.whatsapp,
     json: !!opts.json,
 })));
+number
+    .command("whatsapp <number>")
+    .description("Connect WhatsApp to a number you already hold (beta, enabled per account). POST /api/v1/numbers/<id>/whatsapp.")
+    .option("--json", "machine-readable output")
+    .action(async (number, opts) => process.exit(await runNumberWhatsapp({ number, json: !!opts.json })));
 number
     .command("set <number>")
     .description("Update a number's properties (at least one flag). PATCH /api/v1/numbers/<id>.")
@@ -192,6 +201,8 @@ number
     .option("--first-name <text>", 'iMessage display first name shown beside this number\'s messages (iMessage numbers only); pass "" to clear')
     .option("--last-name <text>", 'iMessage display last name (iMessage numbers only); pass "" to clear')
     .option("--avatar <path-or-url>", "iMessage avatar photo (iMessage numbers only): a local image file (jpeg/png/gif/webp, max 5 MB) to upload, or a public image URL to fetch. Replaces the current photo; photos can't be removed")
+    .option("--whatsapp-name <text>", "WhatsApp display name shown to recipients (WhatsApp-ready numbers only): 1-25 chars, no reserved marks. The call blocks until WhatsApp applies it")
+    .option("--whatsapp-avatar <path-or-url>", "WhatsApp avatar photo (WhatsApp-ready numbers only): a local image file or public URL. Square jpeg/png between 192x192 and 640x640 (not resized)")
     .option("--json", "machine-readable output")
     .action(async (numberArg, opts) => {
     let maxCallDurationSeconds;
@@ -211,13 +222,17 @@ number
         firstName: opts.firstName,
         lastName: opts.lastName,
         avatar: opts.avatar,
+        whatsappName: opts.whatsappName,
+        whatsappAvatar: opts.whatsappAvatar,
         json: !!opts.json,
     }));
 });
 const message = program
     .command("message")
-    .description("Send an SMS, optionally with media (MMS). POST /api/v1/messages.")
+    .description("Send a message to a number or a group, optionally with media (MMS). POST /api/v1/messages.")
     .option("--to <e164>", "destination phone number, E.164 (e.g. +14155551234)")
+    .option("--group <id>", "send into a group conversation instead (see `dial group list`); the sending line comes from the group. Exclusive with --to")
+    .option("--channel <imessage|whatsapp>", "which channel to send on, for a line carrying both; omit to use the number's own default")
     .option("--body <text>", "message body")
     .option("--from-number <ref>", "number to send from: id, owned E.164, or nickname (defaults to onboard's number; exclusive with --from-number-id)")
     .option("--from-number-id <id>", "phoneNumberId to send from (defaults to onboard's number; exclusive with --from-number)")
@@ -225,8 +240,11 @@ const message = program
     .option("--force-audio-file", "send an audio attachment as a regular file attachment instead of an iMessage voice message")
     .option("--json", "machine-readable output")
     .action(async (opts) => {
-    if (!opts.to) {
-        console.error("error: --to is required to send a message. Use `dial message list` to list, or `dial message --help` for usage.");
+    // A destination is still required — it just has two forms now. The exactly-one
+    // rule itself lives in runMessageSend, so the MCP tool and the verb enforce it
+    // from one place; this only keeps the familiar message for the common mistake.
+    if (!opts.to && !opts.group) {
+        console.error("error: --to or --group is required to send a message. Use `dial message list` to list, `dial group list` for your groups, or `dial message --help` for usage.");
         process.exit(2);
     }
     if (!opts.body && (opts.media ?? []).length === 0) {
@@ -235,6 +253,8 @@ const message = program
     }
     process.exit(await runMessageSend({
         to: opts.to,
+        group: opts.group,
+        channel: opts.channel,
         body: opts.body,
         fromNumber: opts.fromNumber,
         fromNumberId: opts.fromNumberId,
@@ -265,15 +285,25 @@ message
     .command("list")
     .description("List recent messages on your account. GET /api/v1/messages.")
     .option("--number-id <id>", "filter to a single phone number")
+    .option("--group <id>", "filter to one group conversation (see `dial group list`)")
     .option("--direction <dir>", "inbound or outbound")
     .option("--since <iso8601>", "only messages created after this timestamp")
     .option("--json", "machine-readable output")
     .action(async (opts) => process.exit(await runMessageList({
     numberId: opts.numberId,
+    group: opts.group,
     direction: opts.direction,
     since: opts.since,
     json: !!opts.json,
 })));
+const group = program
+    .command("group")
+    .description("Group conversations your lines are in (WhatsApp).");
+group
+    .command("list")
+    .description("List the group conversations your lines are in. GET /api/v1/groups.")
+    .option("--json", "machine-readable output")
+    .action(async (opts) => process.exit(await runGroupList({ json: !!opts.json })));
 const typing = program
     .command("typing")
     .description("Show or clear a typing indicator. iMessage numbers display it; SMS numbers ignore it. POST /api/v1/typing.");
@@ -282,6 +312,7 @@ typing
     .description("Show a typing indicator to a recipient, as if composing a message from your number.")
     .option("--to-number <e164>", "recipient phone number, E.164 (e.g. +14155551234)")
     .option("--from-number <ref>", "number the indicator appears from: id, owned E.164, or nickname (defaults to onboard's number)")
+    .option("--channel <imessage|whatsapp>", "which channel to show it on, for a line carrying both; omit to use the number's own default. Typing inside a group isn't supported")
     .option("--json", "machine-readable output")
     .action(async (opts) => {
     if (!opts.toNumber) {
@@ -291,6 +322,7 @@ typing
     process.exit(await runTypingStart({
         toNumber: opts.toNumber,
         fromNumber: opts.fromNumber,
+        channel: opts.channel,
         json: !!opts.json,
     }));
 });
@@ -299,6 +331,7 @@ typing
     .description("Clear a typing indicator previously shown with `typing start`.")
     .option("--to-number <e164>", "recipient phone number, E.164 (e.g. +14155551234)")
     .option("--from-number <ref>", "number the indicator appears from: id, owned E.164, or nickname (defaults to onboard's number)")
+    .option("--channel <imessage|whatsapp>", "which channel to clear it on; pass the same channel `typing start` was given")
     .option("--json", "machine-readable output")
     .action(async (opts) => {
     if (!opts.toNumber) {
@@ -308,6 +341,7 @@ typing
     process.exit(await runTypingStop({
         toNumber: opts.toNumber,
         fromNumber: opts.fromNumber,
+        channel: opts.channel,
         json: !!opts.json,
     }));
 });

package/dist/commands/group/list.js

@@ -0,0 +1,28 @@
+import { listGroups } from "../../lib/ops/groups.js";
+import { isDialError } from "../../lib/ops/errors.js";
+import { printDialError } from "../../lib/cli-error.js";
+export async function runGroupList(opts) {
+    try {
+        const groups = await listGroups();
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: true, groups }));
+            return 0;
+        }
+        if (groups.length === 0) {
+            console.log("no groups. a group appears here once one of your lines is added to it.");
+            return 0;
+        }
+        for (const g of groups) {
+            // A name Dial could not read is rendered as a dash — never the literal "null",
+            // and never the group id standing in for a name, which would read as one.
+            const name = g.name ?? "—";
+            console.log(`${g.id}  ${name}`);
+        }
+        return 0;
+    }
+    catch (e) {
+        if (isDialError(e))
+            return printDialError(opts.json, e);
+        throw e;
+    }
+}

package/dist/commands/message/list.js

@@ -5,6 +5,7 @@ export async function runMessageList(opts) {
     try {
         const messages = await listMessages({
             numberId: opts.numberId,
+            groupId: opts.group,
             direction: opts.direction,
             since: opts.since,
         });
@@ -18,7 +19,10 @@ export async function runMessageList(opts) {
         }
         for (const m of messages) {
             const mediaTag = m.media && m.media.length > 0 ? `  [${m.media.length} media]` : "";
-            console.log(`${m.createdAt}  ${(m.direction ?? "").padEnd(8)}  ${m.from} -> ${m.to}  ${m.body}${mediaTag}`);
+            // A group message has no `to`: the destination is the group. Naming it keeps the
+            // column meaningful instead of printing an empty slot.
+            const destination = m.to ?? `group ${m.groupId}`;
+            console.log(`${m.createdAt}  ${(m.direction ?? "").padEnd(8)}  ${m.from} -> ${destination}  ${m.body}${mediaTag}`);
         }
         return 0;
     }

package/dist/commands/message/send.js

@@ -1,13 +1,28 @@
 import { sendMessage } from "../../lib/ops/messages.js";
 import { isDialError } from "../../lib/ops/errors.js";
 import { printDialError } from "../../lib/cli-error.js";
+/** The channels the API accepts. Checked locally so a typo never becomes a 400. */
+export const CHANNELS = ["imessage", "whatsapp"];
 export async function runMessageSend(opts) {
+    // Both destination checks happen BEFORE any HTTP call: a caller who gave two
+    // destinations, or none, gets told what to fix rather than a server rejection
+    // they have to map back to their own flags.
+    if ((opts.to === undefined) === (opts.group === undefined)) {
+        console.error("error: provide exactly one of --to and --group.");
+        return 2;
+    }
+    if (opts.channel !== undefined && !CHANNELS.includes(opts.channel)) {
+        console.error(`error: --channel must be one of ${CHANNELS.join(", ")}.`);
+        return 2;
+    }
     try {
         const m = await sendMessage({
             to: opts.to,
+            groupId: opts.group,
             body: opts.body,
             fromNumber: opts.fromNumber,
             fromNumberId: opts.fromNumberId,
+            channel: opts.channel,
             media: opts.media,
             forceAudioFile: opts.forceAudioFile,
         });
@@ -18,7 +33,12 @@ export async function runMessageSend(opts) {
             console.log(`sent.`);
             console.log(`  channel:  ${m.channel}`);
             console.log(`  from:     ${m.from}`);
-            console.log(`  to:       ${m.to}`);
+            // A group message has no `to` — the destination is the group — so print the
+            // group instead of an empty line that reads like a bug.
+            if (m.groupId)
+                console.log(`  group:    ${m.groupId}`);
+            else
+                console.log(`  to:       ${m.to}`);
             console.log(`  body:     ${m.body}`);
             for (const item of m.media ?? []) {
                 console.log(`  media:    ${item.url} (${item.contentType})`);

package/dist/commands/number/purchase.js

@@ -2,6 +2,13 @@ import { purchaseNumber } from "../../lib/ops/numbers.js";
 import { isDialError } from "../../lib/ops/errors.js";
 import { printDialError } from "../../lib/cli-error.js";
 export async function runNumberPurchase(opts) {
+    // WhatsApp rides on an iMessage line, so there is no standard-number combination to
+    // ask for. Refused here, before spending anything, and naming the requirement rather
+    // than relaying a 400 the caller has to map back to their flags.
+    if (opts.whatsapp && !opts.includeImessage) {
+        console.error("error: --whatsapp requires --include-imessage (WhatsApp is a channel on an iMessage line).");
+        return 2;
+    }
     try {
         const n = await purchaseNumber({
             inboundInstruction: opts.inboundInstruction,
@@ -10,6 +17,7 @@ export async function runNumberPurchase(opts) {
             inboundLanguage: opts.inboundLanguage,
             areaCode: opts.areaCode,
             includeImessage: opts.includeImessage,
+            whatsapp: opts.whatsapp,
         });
         if (opts.json) {
             console.log(JSON.stringify({ ok: true, number: n }));

package/dist/commands/number/set.js

@@ -17,6 +17,8 @@ export async function runNumberSet(opts) {
             ...(opts.firstName !== undefined ? { firstName: opts.firstName } : {}),
             ...(opts.lastName !== undefined ? { lastName: opts.lastName } : {}),
             ...(opts.avatar !== undefined ? { avatar: opts.avatar } : {}),
+            ...(opts.whatsappName !== undefined ? { whatsappName: opts.whatsappName } : {}),
+            ...(opts.whatsappAvatar !== undefined ? { whatsappAvatar: opts.whatsappAvatar } : {}),
         });
         if (opts.json) {
             console.log(JSON.stringify({ ok: true, number: n }));
@@ -34,6 +36,10 @@ export async function runNumberSet(opts) {
                 console.log(`  display name:          ${[n.firstName, n.lastName].filter(Boolean).join(" ")}`);
                 console.log(`  avatar:                ${n.avatarUrl ?? ""}`);
             }
+            if (n.whatsappName != null || n.whatsappAvatarUrl != null) {
+                console.log(`  whatsapp name:         ${n.whatsappName ?? ""}`);
+                console.log(`  whatsapp avatar:       ${n.whatsappAvatarUrl ?? ""}`);
+            }
         }
         return 0;
     }

package/dist/commands/number/whatsapp.js

@@ -0,0 +1,26 @@
+import { addWhatsappToNumber, resolveNumberId } from "../../lib/ops/numbers.js";
+import { isDialError } from "../../lib/ops/errors.js";
+import { printDialError } from "../../lib/cli-error.js";
+export async function runNumberWhatsapp(opts) {
+    try {
+        const id = await resolveNumberId(opts.number);
+        const n = await addWhatsappToNumber(id);
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: true, number: n }));
+            return 0;
+        }
+        console.log(`connecting WhatsApp.`);
+        console.log(`  number:   ${n.number}`);
+        console.log(`  id:       ${n.id}`);
+        // The track's own status, not the number's: they are independent, and it is this
+        // one the caller is waiting on.
+        console.log(`  whatsapp: ${n.whatsapp?.status ?? "provisioning"}`);
+        console.log(`\nsetup runs in the background. poll \`dial number list\` until whatsapp is ready.`);
+        return 0;
+    }
+    catch (e) {
+        if (isDialError(e))
+            return printDialError(opts.json, e);
+        throw e;
+    }
+}

package/dist/commands/typing/start.js

@@ -1,12 +1,26 @@
 import { setTyping } from "../../lib/ops/typing.js";
 import { isDialError } from "../../lib/ops/errors.js";
 import { printDialError } from "../../lib/cli-error.js";
+/** The channels the API accepts. Checked locally so a typo never becomes a 400. */
+export const TYPING_CHANNELS = ["imessage", "whatsapp"];
+/**
+ * Validate `--channel` before any request. Shared by start and stop so the two
+ * cannot drift into accepting different words for the same thing.
+ */
+export function invalidChannel(channel) {
+    return (channel !== undefined && !TYPING_CHANNELS.includes(channel));
+}
 export async function runTypingStart(opts) {
+    if (invalidChannel(opts.channel)) {
+        console.error(`error: --channel must be one of ${TYPING_CHANNELS.join(", ")}.`);
+        return 2;
+    }
     try {
         const result = await setTyping({
             toNumber: opts.toNumber,
             value: true,
             fromNumber: opts.fromNumber,
+            channel: opts.channel,
         });
         if (opts.json) {
             console.log(JSON.stringify(result));

package/dist/commands/typing/stop.js

@@ -1,12 +1,18 @@
 import { setTyping } from "../../lib/ops/typing.js";
 import { isDialError } from "../../lib/ops/errors.js";
 import { printDialError } from "../../lib/cli-error.js";
+import { invalidChannel, TYPING_CHANNELS } from "./start.js";
 export async function runTypingStop(opts) {
+    if (invalidChannel(opts.channel)) {
+        console.error(`error: --channel must be one of ${TYPING_CHANNELS.join(", ")}.`);
+        return 2;
+    }
     try {
         const result = await setTyping({
             toNumber: opts.toNumber,
             value: false,
             fromNumber: opts.fromNumber,
+            channel: opts.channel,
         });
         if (opts.json) {
             console.log(JSON.stringify(result));

package/dist/lib/ops/groups.js

@@ -0,0 +1,16 @@
+import { apiGet } from "../api.js";
+import { maybeAuth } from "./auth.js";
+import { DialError } from "./errors.js";
+/**
+ * The group conversations the account's lines are in.
+ *
+ * Shared by `dial group list` and the local MCP `list_groups` tool, so both speak to
+ * the API through one place and inherit the saved key the same way.
+ */
+export async function listGroups() {
+    const auth = maybeAuth();
+    const res = await apiGet("/api/v1/groups", auth?.apiKey);
+    if (!res.ok)
+        throw new DialError("list_failed", res.error, res.status);
+    return res.data.groups ?? [];
+}

package/dist/lib/ops/messages.js

@@ -46,20 +46,31 @@ function readMediaFile(path) {
 }
 export async function sendMessage(opts) {
     const auth = maybeAuth();
-    const from = resolveFromSelector(auth, opts);
+    // A group already belongs to one of the account's lines, so a group send needs no
+    // from-number — and must not inherit the SAVED DEFAULT one, because the server
+    // refuses a from-number that disagrees with the group. Inheriting it would turn
+    // the onboarding convenience into a failed send. An explicitly passed one is still
+    // forwarded, and still checked server-side.
+    const explicitFrom = opts.fromNumber !== undefined || opts.fromNumberId !== undefined;
+    const from = opts.groupId && !explicitFrom ? {} : resolveFromSelector(auth, opts);
     const media = opts.media ?? [];
     if (media.length > MAX_MEDIA_ITEMS) {
         throw new DialError("too_much_media", `at most ${MAX_MEDIA_ITEMS} media items are allowed per message (got ${media.length})`);
     }
-    // No `channel`: the server determines it from the from-number (a standard number
-    // sends SMS; an iMessage number sends iMessage with RCS/SMS fallback) and its send
-    // schema is strict — sending a stale `channel` field is rejected as a 400.
+    // `channel` is sent only when the caller named one. Omitted, the server uses the
+    // from-number's own default (a standard number sends SMS; an iMessage number sends
+    // iMessage with RCS/SMS fallback) — and the send schema is strict, so an empty or
+    // stale field would be a 400 rather than a no-op.
+    // Each destination likewise appears only when given: the server enforces the
+    // to/groupId XOR, and a key present-but-empty reads as a second destination.
     // URLs-only goes as plain JSON; any local file switches to multipart.
     const hasFiles = media.some((m) => !isHttpUrl(m));
     let res;
     if (!hasFiles) {
         res = await apiPost("/api/v1/messages", {
-            to: opts.to,
+            ...(opts.to !== undefined ? { to: opts.to } : {}),
+            ...(opts.groupId !== undefined ? { groupId: opts.groupId } : {}),
+            ...(opts.channel !== undefined ? { channel: opts.channel } : {}),
             ...(opts.body ? { body: opts.body } : {}),
             ...from,
             ...(media.length ? { mediaUrls: media } : {}),
@@ -68,7 +79,12 @@ export async function sendMessage(opts) {
     }
     else {
         const form = new ApiFormData();
-        form.set("to", opts.to);
+        if (opts.to !== undefined)
+            form.set("to", opts.to);
+        if (opts.groupId !== undefined)
+            form.set("groupId", opts.groupId);
+        if (opts.channel !== undefined)
+            form.set("channel", opts.channel);
         if (opts.body)
             form.set("body", opts.body);
         for (const [field, value] of Object.entries(from))
@@ -95,6 +111,8 @@ export async function listMessages(opts) {
     const params = new URLSearchParams();
     if (opts.numberId)
         params.set("numberId", opts.numberId);
+    if (opts.groupId)
+        params.set("groupId", opts.groupId);
     if (opts.direction)
         params.set("direction", opts.direction);
     if (opts.since)

package/dist/lib/ops/numbers.js

@@ -51,11 +51,55 @@ export async function purchaseNumber(opts) {
         body.capabilities = ["sms", "call", "imessage"];
     else if (opts.areaCode)
         body.areaCode = opts.areaCode;
+    if (opts.whatsapp)
+        body.whatsapp = true;
     const res = await apiPost("/api/v1/numbers", body, auth?.apiKey);
     if (!res.ok)
         throw new DialError("purchase_failed", res.error, res.status);
     return res.data.number;
 }
+/**
+ * Resolve a number reference — an id, an owned E.164, or a nickname — to its id.
+ *
+ * The REST API keys numbers by id while every CLI verb takes whichever form the caller
+ * has to hand, so one lookup serves them all. An id is returned as given when it
+ * matches a number the account owns, which also keeps a copy-pasted id from a previous
+ * `dial number list` working.
+ */
+export async function resolveNumberId(ref) {
+    const auth = maybeAuth();
+    const list = await apiGet("/api/v1/numbers", auth?.apiKey);
+    if (!list.ok)
+        throw new DialError("list_failed", list.error, list.status);
+    const match = list.data.numbers.find((n) => n.id === ref || n.number === ref || n.nickname === ref);
+    if (!match) {
+        const known = list.data.numbers.map((n) => n.number).join(", ") || "(none)";
+        throw new DialError("number_not_found", `No phone number ${ref} on your account. Yours: ${known}.`);
+    }
+    return match.id;
+}
+/** Copy for the 404 both WhatsApp provisioning paths answer without beta access. */
+export const WHATSAPP_NOT_ENABLED = "WhatsApp is in beta and isn't enabled for this account. " +
+    "See https://docs.getdial.ai/documentation/capabilities/whatsapp to request access.";
+/**
+ * Connect WhatsApp to a number the account already holds
+ * (POST /api/v1/numbers/{id}/whatsapp).
+ *
+ * A 404 means one of two things — no such number, or no beta access — and the API
+ * cannot distinguish them by design: to an account without access the endpoint does
+ * not exist. Reported as the access message, because "not found" on a number the
+ * caller just listed reads as a typo and sends them looking in the wrong place.
+ */
+export async function addWhatsappToNumber(numberId) {
+    const auth = maybeAuth();
+    const res = await apiPost(`/api/v1/numbers/${encodeURIComponent(numberId)}/whatsapp`, {}, auth?.apiKey);
+    if (!res.ok) {
+        if (res.status === 404)
+            throw new DialError("whatsapp_unavailable", WHATSAPP_NOT_ENABLED, 404);
+        throw new DialError("whatsapp_failed", res.error, res.status);
+    }
+    return res.data.number;
+}
 export async function setNumberProperties(opts) {
     const body = {};
     if (opts.inboundInstruction !== undefined)
@@ -73,14 +117,21 @@ export async function setNumberProperties(opts) {
         body.firstName = opts.firstName;
     if (opts.lastName !== undefined)
         body.lastName = opts.lastName;
+    if (opts.whatsappName !== undefined)
+        body.whatsappName = opts.whatsappName;
     // A URL avatar goes in the JSON body; a local file forces multipart (below).
     // Read + validate the file up front, before any API round-trip, so a bad
     // path or unsupported type fails fast.
     const avatarFile = opts.avatar !== undefined && !isHttpUrl(opts.avatar) ? readAvatarFile(opts.avatar) : null;
     if (opts.avatar !== undefined && !avatarFile)
         body.avatarUrl = opts.avatar;
-    if (Object.keys(body).length === 0 && !avatarFile) {
-        throw new DialError("bad_request", "Provide at least one property to update (inboundInstruction, inboundVoiceGender, inboundLanguage, nickname, maxCallDurationSeconds, firstName, lastName, or avatar).");
+    const whatsappAvatarFile = opts.whatsappAvatar !== undefined && !isHttpUrl(opts.whatsappAvatar)
+        ? readAvatarFile(opts.whatsappAvatar)
+        : null;
+    if (opts.whatsappAvatar !== undefined && !whatsappAvatarFile)
+        body.whatsappAvatarUrl = opts.whatsappAvatar;
+    if (Object.keys(body).length === 0 && !avatarFile && !whatsappAvatarFile) {
+        throw new DialError("bad_request", "Provide at least one property to update (inboundInstruction, inboundVoiceGender, inboundLanguage, nickname, maxCallDurationSeconds, firstName, lastName, avatar, whatsappName, or whatsappAvatar).");
     }
     const auth = maybeAuth();
     // The REST API keys numbers by id; the CLI/tool takes the E.164 number for ergonomics,
@@ -97,11 +148,18 @@ export async function setNumberProperties(opts) {
     // A local avatar file forces a multipart PATCH: every scalar field goes in as a
     // text part alongside the uploaded `avatar` file. Otherwise a plain JSON PATCH.
     let res;
-    if (avatarFile) {
+    if (avatarFile || whatsappAvatarFile) {
         const form = new ApiFormData();
         for (const [field, value] of Object.entries(body))
             form.set(field, String(value));
-        form.append("avatar", new Blob([new Uint8Array(avatarFile.data)], { type: avatarFile.contentType }), avatarFile.name);
+        if (avatarFile) {
+            form.append("avatar", new Blob([new Uint8Array(avatarFile.data)], { type: avatarFile.contentType }), avatarFile.name);
+        }
+        if (whatsappAvatarFile) {
+            form.append("whatsappAvatar", new Blob([new Uint8Array(whatsappAvatarFile.data)], {
+                type: whatsappAvatarFile.contentType,
+            }), whatsappAvatarFile.name);
+        }
         res = await apiPatchMultipart(path, form, auth?.apiKey);
     }
     else {

package/dist/lib/ops/typing.js

@@ -9,7 +9,13 @@ import { DialError } from "./errors.js";
 export async function setTyping(opts) {
     const auth = maybeAuth();
     const fromNumber = requireFromNumber(auth, opts.fromNumber);
-    const res = await apiPost("/api/v1/typing", { toNumber: opts.toNumber, value: opts.value, fromNumber }, auth?.apiKey);
+    const res = await apiPost("/api/v1/typing", {
+        toNumber: opts.toNumber,
+        value: opts.value,
+        fromNumber,
+        // Only when named: the typing schema is strict, so an empty field is a 400.
+        ...(opts.channel !== undefined ? { channel: opts.channel } : {}),
+    }, auth?.apiKey);
     if (!res.ok)
         throw new DialError("typing_failed", res.error, res.status);
     return res.data;

package/dist/mcp/schemas.js

@@ -53,13 +53,46 @@ export const phoneNumberSchema = z
         .nullable()
         .optional()
         .describe("URL of the number's iMessage avatar photo; null when unset or not an iMessage number"),
+    whatsappName: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("WhatsApp display name; null on numbers without a WhatsApp track"),
+    whatsappAvatarUrl: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("URL of the number's WhatsApp avatar; null when unset"),
 })
     .passthrough();
+/**
+ * A group conversation. Mirrors the hosted server's `groupSchema` — `createdAt` is a
+ * string, never a z.date(), because a Date is unrepresentable in JSON Schema and one
+ * bad schema fails the whole `tools/list`.
+ */
+export const groupSchema = z.object({
+    id: z.string().describe("Group id — pass as groupId to send_message or list_messages"),
+    name: z
+        .string()
+        .nullable()
+        .describe("The group's current name, or null when no line could report it in time"),
+    createdAt: z
+        .string()
+        .optional()
+        .describe("ISO-8601: when Dial first learned of this group (a join, or its first message)"),
+});
 export const messageSchema = z
     .object({
     id: z.string(),
-    from: z.string(),
-    to: z.string(),
+    from: z.string().describe("Sender, E.164. On a group message, the participant who sent it"),
+    to: z
+        .string()
+        .nullable()
+        .describe("Recipient, E.164 — null on a group message, whose destination is groupId"),
+    groupId: z
+        .string()
+        .nullish()
+        .describe("The group this message belongs to, or null for a one-to-one conversation"),
     body: z.string(),
     channel: z.string().optional(),
     direction: z.string().optional(),

package/dist/mcp/tools/index.js

@@ -6,6 +6,7 @@ import { replyToMessageTool } from "./reply-to-message.js";
 import { startTypingTool } from "./start-typing.js";
 import { stopTypingTool } from "./stop-typing.js";
 import { listMessagesTool } from "./list-messages.js";
+import { listGroupsTool } from "./list-groups.js";
 import { placeCallTool } from "./place-call.js";
 import { listCallsTool } from "./list-calls.js";
 import { getCallTool } from "./get-call.js";
@@ -31,6 +32,7 @@ export const tools = [
     startTypingTool,
     stopTypingTool,
     listMessagesTool,
+    listGroupsTool,
     placeCallTool,
     listCallsTool,
     getCallTool,

package/dist/mcp/tools/list-groups.js

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import { jsonResult } from "../result.js";
+import { listGroups } from "../../lib/ops/groups.js";
+import { groupSchema } from "../schemas.js";
+export const listGroupsTool = {
+    name: "list_groups",
+    config: {
+        title: "List Groups",
+        description: "List the group conversations your lines are in. A group is a conversation that isn't a phone " +
+            "number, so it has an id of its own: pass it as groupId to send_message, or to list_messages to " +
+            "read that conversation. Groups exist on WhatsApp lines. " +
+            "A group's name can be null — it is read live from the line holding the conversation, so a line " +
+            "that can't answer in time yields a null name rather than hiding the group. " +
+            "There is no join event: list again to see a group your line was just added to.",
+        inputSchema: {},
+        outputSchema: { groups: z.array(groupSchema) },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    run: async () => jsonResult({ groups: await listGroups() }),
+};

package/dist/mcp/tools/list-messages.js

@@ -4,6 +4,10 @@ import { listMessages } from "../../lib/ops/messages.js";
 import { messageSchema } from "../schemas.js";
 const inputSchema = {
     numberId: z.string().optional().describe("Filter to a single phone number id"),
+    groupId: z
+        .string()
+        .optional()
+        .describe("Filter to one group conversation (see list_groups). Combines with the other filters"),
     direction: z.enum(["inbound", "outbound"]).optional().describe("Filter by direction"),
     since: z.string().optional().describe("Only messages created after this ISO-8601 timestamp"),
 };
@@ -11,7 +15,9 @@ export const listMessagesTool = {
     name: "list_messages",
     config: {
         title: "List Messages",
-        description: "List recent messages on your account, newest first.",
+        description: "List recent messages on your account, newest first. Pass groupId to read one group " +
+            "conversation. On a group message `to` is null and the destination is groupId; which of your " +
+            "numbers the conversation is on is phoneNumberId.",
         inputSchema,
         outputSchema: { messages: z.array(messageSchema) },
         annotations: { readOnlyHint: true, openWorldHint: true },
@@ -19,6 +25,7 @@ export const listMessagesTool = {
     run: async (args) => jsonResult({
         messages: await listMessages({
             numberId: args.numberId,
+            groupId: args.groupId,
             direction: args.direction,
             since: args.since,
         }),

package/dist/mcp/tools/send-message.js

@@ -3,7 +3,20 @@ import { jsonResult } from "../result.js";
 import { sendMessage, MAX_MEDIA_ITEMS } from "../../lib/ops/messages.js";
 import { messageSchema } from "../schemas.js";
 const inputSchema = {
-    to: z.string().min(7).describe("Destination phone number, E.164 (e.g. +14155550123)"),
+    to: z
+        .string()
+        .min(7)
+        .optional()
+        .describe("Destination phone number, E.164 (e.g. +14155550123). Provide exactly one of to or groupId"),
+    groupId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("A group conversation to send into (see list_groups), instead of a to number. The sending line comes from the group, so no from-number is needed. Provide exactly one of to or groupId"),
+    channel: z
+        .enum(["imessage", "whatsapp"])
+        .optional()
+        .describe("Which channel to send on, for a line that carries more than one. Omit to use the number's own default — a standard number sends SMS, an iMessage number sends iMessage. 'whatsapp' needs a line whose WhatsApp channel is ready; 'imessage' is refused on a number without an iMessage rail"),
     body: z
         .string()
         .optional()
@@ -31,7 +44,10 @@ export const sendMessageTool = {
     name: "send_message",
     config: {
         title: "Send message",
-        description: "Send a message from one of your Dial numbers, optionally with media attachments (MMS). On an iMessage number, a single audio attachment is delivered as a voice message unless forceAudioFile is true.",
+        description: "Send a message from one of your Dial numbers — to a phone number, or into a group conversation — " +
+            "optionally with media attachments (MMS). On an iMessage number, a single audio attachment is " +
+            "delivered as a voice message unless forceAudioFile is true. " +
+            "Address it with exactly one of to or groupId. WhatsApp sends are text-only.",
         inputSchema,
         outputSchema: { message: messageSchema },
         annotations: { openWorldHint: true },
@@ -39,6 +55,8 @@ export const sendMessageTool = {
     run: async (args) => jsonResult({
         message: await sendMessage({
             to: args.to,
+            groupId: args.groupId,
+            channel: args.channel,
             body: args.body,
             fromNumber: args.fromNumber,
             fromNumberId: args.fromNumberId,

package/dist/mcp/tools/set-number-properties.js

@@ -44,12 +44,21 @@ const inputSchema = {
         .url()
         .optional()
         .describe("Public image URL to set as the number's iMessage avatar photo (the server downloads it). jpeg/png/gif/webp, max 5 MB. iMessage numbers only. The photo can be replaced but not removed."),
+    whatsappName: z
+        .string()
+        .optional()
+        .describe("WhatsApp display name shown to recipients. 1-25 chars, no reserved verification marks. WhatsApp-ready numbers only; the call blocks until WhatsApp applies it."),
+    whatsappAvatarUrl: z
+        .string()
+        .url()
+        .optional()
+        .describe("Public image URL to set as the number's WhatsApp avatar (the server downloads it). Square jpeg or png between 192x192 and 640x640 (not resized). WhatsApp-ready numbers only."),
 };
 export const setNumberPropertiesTool = {
     name: "set_number_properties",
     config: {
         title: "Set Number Properties",
-        description: "Update a phone number's properties: its inbound instruction (the system prompt for inbound calls), inbound voice gender, inbound language, nickname, and — for iMessage numbers — its display identity (firstName, lastName, avatarUrl shown beside its messages). Provide at least one.",
+        description: "Update a phone number's properties: its inbound instruction (the system prompt for inbound calls), inbound voice gender, inbound language, nickname, and — for iMessage numbers — its display identity (firstName, lastName, avatarUrl), and for WhatsApp-ready numbers its WhatsApp identity (whatsappName, whatsappAvatarUrl). Provide at least one.",
         inputSchema,
         outputSchema: { number: phoneNumberSchema },
         annotations: { openWorldHint: true },
@@ -69,6 +78,10 @@ export const setNumberPropertiesTool = {
                 ? { maxCallDurationSeconds: args.maxCallDurationSeconds }
                 : {}),
             ...(args.firstName !== undefined ? { firstName: args.firstName } : {}),
+            ...(args.whatsappName !== undefined ? { whatsappName: args.whatsappName } : {}),
+            ...(args.whatsappAvatarUrl !== undefined
+                ? { whatsappAvatar: args.whatsappAvatarUrl }
+                : {}),
             ...(args.lastName !== undefined ? { lastName: args.lastName } : {}),
             ...(args.avatarUrl !== undefined ? { avatar: args.avatarUrl } : {}),
         }),

package/dist/mcp/tools/start-typing.js

@@ -7,6 +7,10 @@ const inputSchema = {
         .string()
         .min(1)
         .describe("Number the indicator appears from: a phone number id, one of your numbers in E.164, or a nickname"),
+    channel: z
+        .enum(["imessage", "whatsapp"])
+        .optional()
+        .describe("Which channel to show it on, for a line that carries more than one. Omit to use the number's own default. Typing inside a group is not supported"),
 };
 export const startTypingTool = {
     name: "start_typing",
@@ -24,6 +28,7 @@ export const startTypingTool = {
     run: async (args) => jsonResult(await setTyping({
         toNumber: args.toNumber,
         fromNumber: args.fromNumber,
+        channel: args.channel,
         value: true,
     })),
 };

package/dist/mcp/tools/stop-typing.js

@@ -7,6 +7,10 @@ const inputSchema = {
         .string()
         .min(1)
         .describe("Number the indicator appears from: a phone number id, one of your numbers in E.164, or a nickname"),
+    channel: z
+        .enum(["imessage", "whatsapp"])
+        .optional()
+        .describe("Which channel to clear it on, for a line that carries more than one. Omit to use the number's own default. Pass the same channel start_typing was given"),
 };
 export const stopTypingTool = {
     name: "stop_typing",
@@ -22,6 +26,7 @@ export const stopTypingTool = {
     run: async (args) => jsonResult(await setTyping({
         toNumber: args.toNumber,
         fromNumber: args.fromNumber,
+        channel: args.channel,
         value: false,
     })),
 };

package/dist/mcp/tools/tool-names.js

@@ -0,0 +1,54 @@
+/**
+ * The tool names this server is expected to expose, split into the half it shares with
+ * the hosted server and the half only a local install can offer.
+ *
+ * There are THREE copies of the MCP tool surface, and nothing but a check keeps them in
+ * step:
+ *
+ *   1. the hosted Remote server (`frontend/src/lib/mcp/tools/tool-names.ts` — the twin
+ *      of this file, whose contents must equal OPERATIONAL_TOOL_NAMES exactly, in the
+ *      same order),
+ *   2. this registry,
+ *   3. the published Remote/Local matrix in `dial-docs`
+ *      (`fern/docs/pages/integrations/tools/mcp.mdx`).
+ *
+ * A tool added to one and forgotten in another is the drift AGENTS.md forbids, and it is
+ * invisible in review because each file reads correctly on its own. Asserting the
+ * registry against these lists turns that into a failing build instead.
+ *
+ * If the two files ever disagree, the fix is the SERVER that is missing a tool — never
+ * an edited list.
+ */
+export const OPERATIONAL_TOOL_NAMES = [
+    "get_account_status",
+    "list_numbers",
+    "purchase_number",
+    "set_number_properties",
+    "send_message",
+    "reply_to_message",
+    "start_typing",
+    "stop_typing",
+    "list_messages",
+    "list_groups",
+    "place_call",
+    "list_calls",
+    "get_call",
+    "wait_for_event",
+];
+/**
+ * Verbs only the local server has: they touch this machine (onboarding, the listen
+ * daemon, local event fan-out), which is why the Local server is a strict superset of
+ * the Remote one rather than a different surface.
+ */
+export const LOCAL_ONLY_TOOL_NAMES = [
+    "auth_login",
+    "auth_verify_otp",
+    "auth_register_number",
+    "listen_install",
+    "listen_uninstall",
+    "listen_status",
+    "add_url_target",
+    "add_command_target",
+    "remove_local_target",
+    "list_local_targets",
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getdial/cli",
-  "version": "0.37.2",
+  "version": "0.39.0",
   "description": "Dial CLI — install, sign up, and run the local listen service.",
   "license": "MIT",
   "repository": {