plazbot-cli 0.4.1 → 0.5.1

package/dist/commands/whatsapp/chat.js

@@ -1,75 +1,74 @@
 import { Command } from 'commander';
-import { Message } from 'plazbot';
-import { getStoredCredentials } from '../../utils/credentials.js';
-import { logger } from '../../utils/logger.js';
-import { addExamples } from '../../utils/help.js';
+import { addExamples, addNotes } from '../../utils/help.js';
 import { createSpinner } from '../../utils/ui.js';
+import { fail, describeError } from '../../utils/output.js';
+import { requireInteractive } from '../../utils/confirm.js';
+import { phoneOption, normalizePhone } from '../../utils/phone.js';
+import { ensureApiSuccess, getMessageClient } from './shared.js';
 import readline from 'readline';
 import chalk from 'chalk';
+const green = chalk.hex('#25D366');
 export const whatsappChatCommand = new Command('chat')
-    .description('Interactive direct chat over WhatsApp')
-    .argument('<phone>', 'Destination phone number (with country code)')
+    .description('Send messages to a WhatsApp number from an interactive prompt (send-only)')
+    .addOption(phoneOption('Recipient number in international format, e.g. +51912345678'))
+    .argument('[phone]', 'Recipient number (legacy positional form of --phone)')
     .option('--dev', 'Use development environment', false)
-    .action(async (phone, options) => {
+    .action(async (positional, options) => {
     try {
-        const credentials = await getStoredCredentials();
-        const messageClient = new Message({
-            workspaceId: credentials.workspace,
-            apiKey: credentials.apiKey,
-            zone: credentials.zone,
-            ...(options.dev && { customUrl: "http://localhost:5090" })
-        });
-        const rl = readline.createInterface({
-            input: process.stdin,
-            output: process.stdout,
-        });
-        console.clear();
+        const phone = normalizePhone(options.phone ?? positional);
+        requireInteractive('WhatsApp chat', `Send a single message instead: plazbot whatsapp send-message -p +${phone} -m "Hello"`);
+        const messageClient = await getMessageClient(options.dev);
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const line = (text) => green('  │') + text.padEnd(60) + green('│');
         console.log();
-        console.log(chalk.hex('#25D366')('  ┌' + '─'.repeat(50) + '┐'));
-        console.log(chalk.hex('#25D366')('  │') + chalk.bold(`  WhatsApp Chat`).padEnd(60) + chalk.hex('#25D366')('│'));
-        console.log(chalk.hex('#25D366')('  │') + chalk.gray(`  Destination: ${phone}`).padEnd(60) + chalk.hex('#25D366')('│'));
-        console.log(chalk.hex('#25D366')('  │') + chalk.gray('  /exit to quit').padEnd(60) + chalk.hex('#25D366')('│'));
-        console.log(chalk.hex('#25D366')('  └' + '─'.repeat(50) + '┘'));
+        console.log(green('  ┌' + '─'.repeat(50) + '┐'));
+        console.log(line(chalk.bold('  WhatsApp chat (send-only)')));
+        console.log(line(chalk.gray(`  To: +${phone}`)));
+        console.log(line(chalk.gray('  Type /exit to quit')));
+        console.log(green('  └' + '─'.repeat(50) + '┘'));
+        console.log(chalk.gray("  Replies from the contact are not shown here; see them in the Plazbot inbox."));
+        console.log(chalk.gray("  Free-form text only works within 24h of the contact's last message."));
         console.log();
+        rl.on('close', () => process.exit(0));
         const ask = () => {
-            rl.question(chalk.hex('#25D366')('  > '), async (message) => {
-                if (!message.trim()) {
-                    ask();
-                    return;
-                }
-                if (message.toLowerCase() === '/exit') {
+            rl.question(green('  > '), async (message) => {
+                const text = message.trim();
+                if (!text)
+                    return ask();
+                if (text.toLowerCase() === '/exit' || text.toLowerCase() === '/quit') {
                     console.log(chalk.gray('\n  Chat ended.\n'));
                     rl.close();
                     return;
                 }
+                const spinner = createSpinner('Sending...').start();
                 try {
-                    const spinner = createSpinner('Sending...');
-                    spinner.start();
-                    await messageClient.onWhatsappMessage({
-                        message,
-                        to: phone,
-                    });
+                    const response = await messageClient.onWhatsappMessage({ message: text, to: phone });
+                    ensureApiSuccess(response, 'The message was not sent', 'Outside the 24h window use: plazbot whatsapp send-template');
                     spinner.succeed('Sent');
-                    ask();
                 }
                 catch (error) {
-                    const msg = error instanceof Error ? error.message : 'Error';
-                    console.log(chalk.hex('#EF5350')(`  ✖ ${msg}`));
-                    ask();
+                    const { message: msg, hint } = describeError(error);
+                    spinner.fail(msg);
+                    if (hint)
+                        console.log(chalk.gray(`  ${hint}`));
                 }
+                ask();
             });
         };
         ask();
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : 'Unknown error';
-        logger.error(message);
-        process.exit(1);
+        fail(error);
     }
 });
 addExamples(whatsappChatCommand, [
-    { description: 'Open an interactive chat with a WhatsApp number',
+    { description: 'Open a send-only chat with a number',
+        command: 'plazbot whatsapp chat -p +51912345678' },
+    { description: 'Legacy positional form (still supported)',
         command: 'plazbot whatsapp chat 51912345678' },
-    { description: 'Chat through the development backend',
-        command: 'plazbot whatsapp chat 51912345678 --dev' },
+]);
+addNotes(whatsappChatCommand, [
+    'Send-only: incoming replies are not shown in the terminal. Read them in the Plazbot inbox or via your webhook.',
+    "WhatsApp only allows free-form text within 24 hours of the contact's last message; outside it use send-template.",
+    'Needs an interactive terminal. For scripts use plazbot whatsapp send-message.',
 ]);

package/dist/commands/whatsapp/connect-flow.js

@@ -3,6 +3,7 @@ import chalk from 'chalk';
 import ora from 'ora';
 import { apiBaseUrl } from '../../utils/credentials.js';
 import { openBrowser } from '../../utils/open-browser.js';
+import { CliError } from '../../utils/output.js';
 /**
  * Lógica compartida de conexión de números de WhatsApp (connect y setup).
  * Mismo flujo que el panel: link de onboarding co.plzb.link → el usuario completa
@@ -33,9 +34,9 @@ export async function fetchIntegrations(creds, dev = false) {
     }
     catch (error) {
         if (axios.isAxiosError(error) && error.response?.status === 401) {
-            throw new Error("Tu sesión no es válida o fue revocada. Ejecuta 'plazbot login'.");
+            throw new CliError('Your session is invalid or was revoked.', 'unauthorized', "Run 'plazbot login' to sign in again.");
         }
-        throw new Error('No se pudieron cargar las integraciones del workspace.');
+        throw new CliError('Could not load the workspace integrations.', 'api_error', 'Try again in a few seconds.');
     }
 }
 export function whatsappNumbers(all) {
@@ -67,13 +68,13 @@ export async function getOnboardingLink(creds, business, dev = false) {
         }
         catch (error) {
             if (axios.isAxiosError(error) && error.response?.status === 401) {
-                throw new Error("Tu sesión no es válida o fue revocada. Ejecuta 'plazbot login'.");
+                throw new CliError('Your session is invalid or was revoked.', 'unauthorized', "Run 'plazbot login' to sign in again.");
             }
             link = null;
         }
     }
     if (!link?.token)
-        throw new Error('No se pudo obtener el link de conexión.');
+        throw new CliError('Could not get the connection link.', 'api_error', 'Try again, or connect the number from the panel → Integrations.');
     return { url: link.shortUrl || `${ONBOARDING_SHORT_DOMAIN}/${link.token}`, expiresAt: link.expiresAt };
 }
 export async function activateIntegration(creds, integrationId, dev = false) {
@@ -97,15 +98,15 @@ export async function connectNewNumber(creds, opts) {
     const opened = opts.openInBrowser !== false && openBrowser(url);
     const border = chalk.hex('#25D366');
     console.log();
-    console.log(border('  ┃ ') + chalk.bold(opened ? 'Abrimos el registro de Meta en tu navegador.' : 'Abre este link en tu navegador:'));
+    console.log(border('  ┃ ') + chalk.bold(opened ? 'We opened the Meta sign-up in your browser.' : 'Open this link in your browser:'));
     console.log(border('  ┃ ') + chalk.hex('#22d3ee').underline(url));
     console.log(border('  ┃ ') + chalk.gray(opts.business
-        ? 'Inicia sesión con Facebook y vincula tu app WhatsApp Business escaneando el QR.'
-        : 'Inicia sesión con Facebook, elige o crea tu cuenta de WhatsApp Business y verifica el número.'));
+        ? 'Sign in with Facebook and link your WhatsApp Business app by scanning the QR code.'
+        : 'Sign in with Facebook, choose or create your WhatsApp Business account and verify the number.'));
     if (expiresAt)
-        console.log(border('  ┃ ') + chalk.gray(`El link vence el ${new Date(expiresAt).toLocaleDateString('es-ES', { day: 'numeric', month: 'long' })}.`));
+        console.log(border('  ┃ ') + chalk.gray(`The link expires on ${new Date(expiresAt).toLocaleDateString('en-US', { month: 'long', day: 'numeric' })}.`));
     console.log();
-    const spinner = ora({ text: chalk.gray('Esperando la conexión... (Ctrl+C para cancelar)'), spinner: 'dots', color: 'cyan' }).start();
+    const spinner = ora({ text: chalk.gray('Waiting for the connection... (Ctrl+C to cancel)'), spinner: 'dots', color: 'cyan' }).start();
     const intervalMs = 5000;
     const deadline = Date.now() + (opts.timeoutMs ?? 10 * 60 * 1000);
     const startedAt = Date.now();
@@ -115,14 +116,14 @@ export async function connectNewNumber(creds, opts) {
             const fresh = whatsappNumbers(await fetchIntegrations(creds, dev)).filter(ig => !prevIds.has(ig.id));
             if (fresh.length > 0) {
                 const detected = fresh[0];
-                spinner.succeed(chalk.hex('#4ade80')(`Número detectado: ${integrationLabel(detected)}`));
-                const act = ora({ text: chalk.gray('Activando el número...'), spinner: 'dots', color: 'green' }).start();
+                spinner.succeed(chalk.hex('#4ade80')(`Number detected: ${integrationLabel(detected)}`));
+                const act = ora({ text: chalk.gray('Activating the number...'), spinner: 'dots', color: 'green' }).start();
                 if (await activateIntegration(creds, detected.id, dev)) {
-                    act.succeed(chalk.hex('#4ade80')('Número activo'));
+                    act.succeed(chalk.hex('#4ade80')('Number active'));
                     detected.isActive = 1;
                 }
                 else {
-                    act.warn(chalk.hex('#FFA726')('No se pudo activar automáticamente. Actívalo en el panel → Integraciones.'));
+                    act.warn(chalk.hex('#FFA726')('Could not activate it automatically. Activate it in the panel → Integrations.'));
                 }
                 return detected;
             }
@@ -130,8 +131,8 @@ export async function connectNewNumber(creds, opts) {
         catch {
             // error puntual: seguir esperando
         }
-        spinner.text = chalk.gray(`Esperando la conexión... ${Math.floor((Date.now() - startedAt) / 1000)}s (Ctrl+C para cancelar)`);
+        spinner.text = chalk.gray(`Waiting for the connection... ${Math.floor((Date.now() - startedAt) / 1000)}s (Ctrl+C to cancel)`);
     }
-    spinner.warn(chalk.hex('#FFA726')('No detectamos una conexión nueva a tiempo.'));
+    spinner.warn(chalk.hex('#FFA726')('No new connection was detected in time.'));
     return null;
 }

package/dist/commands/whatsapp/connect.js

@@ -2,26 +2,31 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import ora from 'ora';
 import { getStoredCredentials } from '../../utils/credentials.js';
-import { logger } from '../../utils/logger.js';
-import { addExamples } from '../../utils/help.js';
+import { addExamples, addNotes } from '../../utils/help.js';
 import { theme, section } from '../../utils/ui.js';
+import { fail } from '../../utils/output.js';
 import { connectNewNumber, fetchIntegrations, integrationLabel, whatsappNumbers } from './connect-flow.js';
 export const whatsappConnectCommand = new Command('connect')
-    .description('Conecta un número de WhatsApp al workspace')
-    .option('--business', 'Conectar tu app WhatsApp Business actual (coexistencia)', false)
-    .option('--no-browser', 'No abrir el navegador automáticamente')
-    .option('--dev', 'Usar el entorno de desarrollo local', false)
+    .description('Connect a WhatsApp number to the workspace (Meta sign-up in the browser)')
+    .option('--business', 'Connect your existing WhatsApp Business app (coexistence, linked by QR)', false)
+    .option('--no-browser', 'Print the link instead of opening the browser')
+    .option('--dev', 'Use development environment', false)
     .action(async (options) => {
     try {
         const credentials = await getStoredCredentials();
-        console.log(section(options.business ? 'Conectar WhatsApp Business' : 'Conectar WhatsApp'));
-        const loadSpinner = ora({ text: chalk.gray('Cargando números conectados...'), spinner: 'dots', color: 'green' }).start();
-        const existing = whatsappNumbers(await fetchIntegrations(credentials, options.dev));
-        loadSpinner.stop();
+        console.log(section(options.business ? 'Connect WhatsApp Business' : 'Connect WhatsApp'));
+        const loadSpinner = ora({ text: chalk.gray('Loading connected numbers...'), spinner: 'dots', color: 'green' }).start();
+        let existing;
+        try {
+            existing = whatsappNumbers(await fetchIntegrations(credentials, options.dev));
+        }
+        finally {
+            loadSpinner.stop();
+        }
         if (existing.length > 0) {
-            console.log(theme.muted(`  ${existing.length} número(s) ya conectado(s):`));
+            console.log(theme.muted(`  ${existing.length} number(s) already connected:`));
             existing.forEach(ig => {
-                const status = ig.isActive ? chalk.hex('#66BB6A')('activo') : chalk.hex('#EF5350')('inactivo');
+                const status = ig.isActive ? chalk.hex('#66BB6A')('active') : chalk.hex('#EF5350')('inactive');
                 console.log(`    ${theme.muted('•')} ${integrationLabel(ig)}  ${status}`);
             });
         }
@@ -32,22 +37,32 @@ export const whatsappConnectCommand = new Command('connect')
         });
         console.log();
         if (detected) {
-            console.log(theme.success(`  WhatsApp conectado: ${integrationLabel(detected)}`));
+            console.log(theme.success(`  WhatsApp connected: ${integrationLabel(detected)}`));
+            if (!detected.isActive) {
+                console.log(theme.muted('  The number is not active yet. Activate it in the panel → Integrations.'));
+            }
+            console.log();
+            console.log(theme.muted('  Next step:'));
+            console.log(`    ${chalk.cyan('plazbot whatsapp setup')}   ${theme.muted('Send and receive your first message')}`);
             console.log();
-            console.log(theme.muted('  Siguiente paso:'));
-            console.log(`    ${chalk.cyan('plazbot whatsapp setup')}   ${theme.muted('Prueba enviar y recibir tu primer mensaje')}`);
         }
         else {
-            console.log(theme.muted('  Puedes intentarlo otra vez con: plazbot whatsapp connect'));
+            console.log(theme.muted('  Try again with: plazbot whatsapp connect'));
+            console.log();
+            process.exit(1);
         }
-        console.log();
     }
     catch (error) {
-        logger.error(error instanceof Error ? error.message : 'Error desconocido');
-        process.exit(1);
+        fail(error);
     }
 });
 addExamples(whatsappConnectCommand, [
-    { description: 'Conectar un número con WhatsApp API', command: 'plazbot whatsapp connect' },
-    { description: 'Conectar tu app WhatsApp Business actual', command: 'plazbot whatsapp connect --business' },
+    { description: 'Connect a number with the WhatsApp API', command: 'plazbot whatsapp connect' },
+    { description: 'Connect your existing WhatsApp Business app', command: 'plazbot whatsapp connect --business' },
+    { description: 'Print the link (e.g. to open it on another device)', command: 'plazbot whatsapp connect --no-browser' },
+]);
+addNotes(whatsappConnectCommand, [
+    'The CLI waits up to 10 minutes for the new number to appear, then activates it.',
+    'If automatic activation fails, activate the number in the panel → Integrations.',
+    'The connection link is reused while it is valid and regenerated when it expires.',
 ]);

package/dist/commands/whatsapp/delete-webhook.js

@@ -1,34 +1,51 @@
-import { Command } from 'commander';
-import { Message } from 'plazbot';
-import { getStoredCredentials } from '../../utils/credentials.js';
+import { Command, Option } from 'commander';
 import { logger } from '../../utils/logger.js';
-import { addExamples } from '../../utils/help.js';
+import { addExamples, addNotes } from '../../utils/help.js';
+import { createSpinner } from '../../utils/ui.js';
+import { jsonOption, isJsonMode, printJson, fail } from '../../utils/output.js';
+import { addYesOption, confirmAction } from '../../utils/confirm.js';
+import { phoneOption, normalizePhone } from '../../utils/phone.js';
+import { ensureApiSuccess, getMessageClient } from './shared.js';
 export const deleteWebhookCommand = new Command('delete-webhook')
-    .description('Delete the WhatsApp webhook')
-    .requiredOption('-n, --number <phone>', 'WhatsApp number (with country code, e.g.: 51912345678)')
-    .option('--dev', 'Use development environment', false)
-    .action(async (options) => {
+    .description('Remove the incoming-messages webhook from a WhatsApp number')
+    .addOption(phoneOption('Your connected WhatsApp number in international format, e.g. +51912345678'))
+    .addOption(new Option('-n, --number <phone>', 'Alias of --phone').hideHelp())
+    .addOption(jsonOption())
+    .option('--dev', 'Use development environment', false);
+addYesOption(deleteWebhookCommand);
+deleteWebhookCommand.action(async (options) => {
     try {
-        const credentials = await getStoredCredentials();
-        const messageClient = new Message({
-            workspaceId: credentials.workspace,
-            apiKey: credentials.apiKey,
-            zone: credentials.zone,
-            ...(options.dev && { customUrl: "http://localhost:5090" })
-        });
-        logger.title('Deleting WhatsApp webhook');
-        logger.label('Number', options.number);
-        await messageClient.deleteWebhook({
-            number: options.number
-        });
-        logger.success('Webhook deleted successfully');
+        const phone = normalizePhone(options.phone ?? options.number);
+        if (!(await confirmAction(`Remove the webhook from +${phone}? Your server will stop receiving its messages.`, options))) {
+            logger.dim('Aborted.');
+            process.exit(1);
+        }
+        const messageClient = await getMessageClient(options.dev);
+        const spinner = createSpinner(`Removing webhook from +${phone}...`).start();
+        try {
+            const response = await messageClient.deleteWebhook({ number: phone });
+            ensureApiSuccess(response, 'The webhook was not removed');
+        }
+        catch (error) {
+            spinner.stop();
+            throw error;
+        }
+        spinner.succeed(`Webhook removed from +${phone}`);
+        if (isJsonMode())
+            printJson({ phone, deleted: true });
     }
     catch (error) {
-        logger.error(error.message);
-        process.exit(1);
+        fail(error);
     }
 });
 addExamples(deleteWebhookCommand, [
-    { description: 'Remove the webhook from a WhatsApp number',
-        command: 'plazbot whatsapp delete-webhook -n 51912345678' },
+    { description: 'Remove the webhook (asks for confirmation)',
+        command: 'plazbot whatsapp delete-webhook -p +51912345678' },
+    { description: 'Remove it without prompting (scripts and CI)',
+        command: 'plazbot whatsapp delete-webhook -p +51912345678 --yes' },
+    { description: 'Machine-readable output',
+        command: 'plazbot whatsapp delete-webhook -p +51912345678 --yes --json' },
+]);
+addNotes(deleteWebhookCommand, [
+    'Only the forwarding to your URL is removed; the number stays connected to the workspace.',
 ]);

package/dist/commands/whatsapp/index.js

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { addExamples } from '../../utils/help.js';
+import { addExamples, addNotes } from '../../utils/help.js';
 import { sendMessageCommand } from './send.js';
 import { sendTemplateCommand } from './send-template.js';
 import { registerWebhookCommand } from './register-webhook.js';
@@ -11,29 +11,28 @@ import { whatsappSetupCommand } from './setup.js';
 import { widgetCommand } from './widget.js';
 import { channelsCommand, assignCommand } from './channels.js';
 export const whatsappCommands = new Command('whatsapp')
-    .description('WhatsApp commands: messages, templates, broadcast and more')
+    .description('WhatsApp: connect numbers, send messages and templates, broadcast, webhooks')
     .addCommand(whatsappSetupCommand)
     .addCommand(whatsappConnectCommand)
     .addCommand(sendMessageCommand)
     .addCommand(sendTemplateCommand)
-    .addCommand(registerWebhookCommand)
-    .addCommand(deleteWebhookCommand)
     .addCommand(broadcastCommand)
     .addCommand(whatsappChatCommand)
-    .addCommand(widgetCommand)
+    .addCommand(registerWebhookCommand)
+    .addCommand(deleteWebhookCommand)
     .addCommand(channelsCommand)
-    .addCommand(assignCommand);
+    .addCommand(assignCommand)
+    .addCommand(widgetCommand);
 addExamples(whatsappCommands, [
-    { description: 'Asistente: conectar WhatsApp y enviar tu primer mensaje',
+    { description: 'Guided setup: connect WhatsApp and send your first message',
         command: 'plazbot whatsapp setup' },
-    { description: 'Connect a WhatsApp number to the workspace',
-        command: 'plazbot whatsapp connect' },
-    { description: 'Send a quick message',
-        command: 'plazbot whatsapp send-message -t 51912345678 -m "Hello"' },
+    { description: 'Send a text message (within the 24h window)',
+        command: 'plazbot whatsapp send-message -p +51912345678 -m "Hello"' },
     { description: 'Send a template with variables',
-        command: 'plazbot whatsapp send-template -p 51912345678 -t welcome --var name=Anna' },
-    { description: 'Open an interactive chat',
-        command: 'plazbot whatsapp chat 51912345678' },
-    { description: 'Assign a number to an agent',
-        command: 'plazbot whatsapp assign 51912345678 agt_AbcDef123' },
+        command: 'plazbot whatsapp send-template -p +51912345678 -t welcome --var name=Anna' },
+    { description: 'Make an agent answer a number',
+        command: 'plazbot whatsapp assign -p +51912345678 -a age_AbcDef123' },
+]);
+addNotes(whatsappCommands, [
+    'Every command takes the number as -p, --phone in international format (+51912345678, "+51 912 345 678" or 51912345678).',
 ]);

package/dist/commands/whatsapp/register-webhook.js

@@ -1,37 +1,54 @@
-import { Command } from 'commander';
-import { Message } from 'plazbot';
-import { getStoredCredentials } from '../../utils/credentials.js';
+import { Command, Option } from 'commander';
 import { logger } from '../../utils/logger.js';
-import { addExamples } from '../../utils/help.js';
+import { addExamples, addNotes } from '../../utils/help.js';
+import { createSpinner } from '../../utils/ui.js';
+import { jsonOption, isJsonMode, printJson, fail, CliError } from '../../utils/output.js';
+import { phoneOption, normalizePhone } from '../../utils/phone.js';
+import { ensureApiSuccess, getMessageClient } from './shared.js';
 export const registerWebhookCommand = new Command('register-webhook')
-    .description('Register a webhook for WhatsApp')
-    .requiredOption('-n, --number <phone>', 'WhatsApp number (with country code, e.g.: 51912345678)')
-    .requiredOption('-u, --url <webhook>', 'Webhook URL')
+    .description('Register the webhook URL that receives incoming messages for a WhatsApp number')
+    .addOption(phoneOption('Your connected WhatsApp number in international format, e.g. +51912345678'))
+    .addOption(new Option('-n, --number <phone>', 'Alias of --phone').hideHelp())
+    .requiredOption('-u, --url <url>', 'Public https URL that will receive the incoming messages')
+    .addOption(jsonOption())
     .option('--dev', 'Use development environment', false)
     .action(async (options) => {
     try {
-        const credentials = await getStoredCredentials();
-        const messageClient = new Message({
-            workspaceId: credentials.workspace,
-            apiKey: credentials.apiKey,
-            zone: credentials.zone,
-            ...(options.dev && { customUrl: "http://localhost:5090" })
-        });
-        logger.title('Registering WhatsApp webhook');
-        logger.label('Number', options.number);
-        logger.label('URL', options.url);
-        await messageClient.registerWebhook({
-            number: options.number,
-            webhookUrl: options.url
-        });
-        logger.success('Webhook registered successfully');
+        const phone = normalizePhone(options.phone ?? options.number);
+        const url = String(options.url || '').trim();
+        if (!/^https?:\/\/\S+$/i.test(url)) {
+            throw new CliError(`Invalid webhook URL "${options.url}".`, 'invalid_url', 'Use a public URL, e.g. -u https://api.example.com/webhooks/whatsapp');
+        }
+        const messageClient = await getMessageClient(options.dev);
+        if (!isJsonMode()) {
+            logger.title('Registering WhatsApp webhook');
+            logger.label('Number', `+${phone}`);
+            logger.label('URL', url);
+        }
+        const spinner = createSpinner('Registering...').start();
+        try {
+            const response = await messageClient.registerWebhook({ number: phone, webhookUrl: url });
+            ensureApiSuccess(response, 'The webhook was not registered', "Check that the number is connected to this workspace ('plazbot whatsapp connect').");
+        }
+        catch (error) {
+            spinner.stop();
+            throw error;
+        }
+        spinner.succeed('Webhook registered');
+        if (isJsonMode())
+            printJson({ phone, url, registered: true });
     }
     catch (error) {
-        logger.error(error.message);
-        process.exit(1);
+        fail(error);
     }
 });
 addExamples(registerWebhookCommand, [
-    { description: 'Register an inbound webhook for a WhatsApp number',
-        command: 'plazbot whatsapp register-webhook -n 51912345678 -u https://api.example.com/webhooks/whatsapp' },
+    { description: 'Register an incoming-messages webhook for a number',
+        command: 'plazbot whatsapp register-webhook -p +51912345678 -u https://api.example.com/webhooks/whatsapp' },
+    { description: 'Same, with machine-readable output',
+        command: 'plazbot whatsapp register-webhook -p +51912345678 -u https://api.example.com/webhooks/whatsapp --json' },
+]);
+addNotes(registerWebhookCommand, [
+    'The number must be connected to the active workspace (see plazbot whatsapp connect).',
+    'Registering again replaces the previous URL. Remove it with plazbot whatsapp delete-webhook.',
 ]);