# WhatsApp on boxd

> Enables interaction with customers through the WhatsApp Business API for messaging and automation. Only supports WhatsApp Business accounts, not WhatsApp Personal accounts.

- Page: https://boxd.sh/integrations/whatsapp/
- CLI: `run whatsapp` (57 commands, 17 marked common)
- SDK: `import { whatsapp } from "@boxd/run"`; every parameter and response type is at `@boxd/run/whatsapp`
- Triggers: 1
- Connect: `run auth whatsapp` (Sign in with WhatsApp), or https://app.boxd.sh/integrations/detail/whatsapp
- All integrations: https://boxd.sh/integrations/ (Markdown: https://boxd.sh/integrations/index.md)

## From the shell

```sh
run auth whatsapp      # once: prints a link to connect your account
run whatsapp           # list its commands
run whatsapp get-template-library
```

Parameters are flags (`--flag value`); object and array parameters take a JSON string. Output is YAML, or JSON with `--json`. Calls use your own connection; `--scope <name>` uses a connection shared with your team.

## From a script

```ts
import { whatsapp } from "@boxd/run";

const result = await whatsapp.getTemplateLibrary({});
console.log(result);

whatsapp.on("message-status-updated", { phone_number_id: "…" }, async (event) => {
  // Message Status Updated: runs on this machine, once per event
  console.log(event);
});
```

Run it with `run whatsapp.run.ts`. A script that calls `.on()` keeps running as a job and handles each event.

## Commands

Required flags are listed; `run whatsapp <command> --help` lists the optional ones. "common" marks what `run whatsapp` shows without `--all`.

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `block-users` | `whatsapp.blockUsers()` | `--block-users` `--phone-number-id` | 0 | Block one or more WhatsApp users to prevent them from sending messages to your business phone number |
| `configure-conversational-automation` | `whatsapp.configureConversationalAutomation()` | `--phone-number-id` | 3 | Configure conversational automation settings for a WhatsApp Business phone number |
| `create-flow` | `whatsapp.createFlow()` | `--categories` `--endpoint-uri` `--name` | 2 | Create a new WhatsApp Flow for the WhatsApp Business Account |
| `create-max-price-agreements` | `whatsapp.createMaxPriceAgreements()` | `--business-id` `--currency` `--max-price-micros` `--message-type` `--signer-email` `--signer-name` | 0 | Create a max price agreement for WhatsApp marketing messages pricing |
| `create-message-template` | `whatsapp.createMessageTemplate()` | `--category` `--language` `--name` | 5 | Create a new message template for the WhatsApp Business Account |
| `create-qr-code` | `whatsapp.createQrCode()` | `--phone-number-id` `--prefilled-message` | 1 | Create a new QR code with a prefilled message for a WhatsApp Business phone number |
| `create-upload-session` | `whatsapp.createUploadSession()` | `--file-length` `--file-type` | 1 | Create a resumable upload session for large file uploads to WhatsApp |
| `delete-media` ·common | `whatsapp.deleteMedia()` | `--media-id` | 0 | Delete a WhatsApp media file previously uploaded via the Media API |
| `delete-message-template` | `whatsapp.deleteMessageTemplate()` | `--name` | 2 | Delete a message template from the WhatsApp Business Account by name |
| `delete-qr-code` | `whatsapp.deleteQrCode()` | `--phone-number-id` `--qr-code-id` | 0 | Delete a specific QR code from a WhatsApp Business phone number |
| `deregister-phone` ·common | `whatsapp.deregisterPhone()` | `--phone-number-id` | 0 | Deregister a WhatsApp Business phone number from the Cloud API |
| `get-activities` | `whatsapp.getActivities()` | — | 8 | Retrieve activity history for a WhatsApp Business Account |
| `get-business-account-details` | `whatsapp.getBusinessAccountDetails()` | — | 2 | Retrieve comprehensive details about a WhatsApp Business Account (WABA) |
| `get-business-compliance-info` ·common | `whatsapp.getBusinessComplianceInfo()` | `--phone-number-id` | 1 | Retrieve comprehensive business compliance information for a WhatsApp Business phone number |
| `get-business-encryption` ·common | `whatsapp.getBusinessEncryption()` | `--phone-number-id` | 1 | Retrieve the WhatsApp Business public key and its signature verification status |
| `get-business-profile` | `whatsapp.getBusinessProfile()` | `--phone-number-id` | 1 | Get the business profile information for a WhatsApp Business phone number |
| `get-client-business-accounts` ·common | `whatsapp.getClientBusinessAccounts()` | `--business-id` | 6 | Retrieve WhatsApp Business Accounts shared with or managed by a business portfolio |
| `get-commerce-settings` ·common | `whatsapp.getCommerceSettings()` | `--phone-number-id` | 0 | Get commerce settings for a WhatsApp Business phone number |
| `get-flow-assets` ·common | `whatsapp.getFlowAssets()` | `--flow-id` | 0 | List assets associated with a WhatsApp Flow |
| `get-join-requests` | `whatsapp.getJoinRequests()` | `--group-id` | 3 | Get all pending join requests for a WhatsApp group |
| `get-media-info` | `whatsapp.getMediaInfo()` | `--media-id` | 0 | Get metadata and download URL for uploaded WhatsApp media |
| `get-message-history` | `whatsapp.getMessageHistory()` | `--phone-number-id` | 5 | Retrieve message history for a WhatsApp Business phone number |
| `get-message-templates` | `whatsapp.getMessageTemplates()` | — | 8 | Get all message templates for the WhatsApp Business Account |
| `get-owned-business-accounts` ·common | `whatsapp.getOwnedBusinessAccounts()` | `--business-id` | 7 | Retrieve WhatsApp Business Accounts owned by a business portfolio |
| `get-phone-number` | `whatsapp.getPhoneNumber()` | `--phone-number-id` | 1 | Retrieve detailed information about a specific WhatsApp Business phone number |
| `get-phone-numbers` | `whatsapp.getPhoneNumbers()` | — | 2 | Retrieve all phone numbers registered to your WhatsApp Business Account |
| `get-schedules` | `whatsapp.getSchedules()` | — | 7 | Retrieve campaign schedules associated with a WhatsApp Business Account |
| `get-settings` ·common | `whatsapp.getSettings()` | `--phone-number-id` | 1 | Get Cloud API settings for a WhatsApp Business phone number |
| `get-subscribed-apps` | `whatsapp.getSubscribedApps()` | — | 2 | Get all applications currently subscribed to webhooks for a WhatsApp Business Account |
| `get-template-library` ·common | `whatsapp.getTemplateLibrary()` | — | 7 | Browse the pre-built message template library for WhatsApp Business Account |
| `get-template-status` | `whatsapp.getTemplateStatus()` | `--template-id` | 1 | Get the status and details of a specific message template |
| `list-flows` | `whatsapp.listFlows()` | — | 3 | List all WhatsApp Flows associated with the WhatsApp Business Account |
| `list-groups` | `whatsapp.listGroups()` | `--phone-number-id` | 3 | List all WhatsApp groups associated with a business phone number |
| `list-qr-codes` | `whatsapp.listQrCodes()` | `--phone-number-id` | 5 | Get a list of all QR codes for a WhatsApp Business phone number |
| `list-solutions` | `whatsapp.listSolutions()` | — | 5 | Retrieve a paginated list of Multi-Partner Solutions for a WhatsApp Business Account |
| `publish-flow` | `whatsapp.publishFlow()` | `--flow-id` | 0 | Publish a WhatsApp Flow to make it available for use |
| `register-phone` ·common | `whatsapp.registerPhone()` | `--phone-number-id` `--pin` | 4 | Register a WhatsApp Business phone number for use with WhatsApp Cloud API |
| `remove-assigned-user` ·common | `whatsapp.removeAssignedUser()` | `--user` | 1 | Remove a user's access from the WhatsApp Business Account |
| `send-contacts` | `whatsapp.sendContacts()` | `--contacts` `--phone-number-id` `--to-number` | 2 | Send contacts WhatsApp number |
| `send-interactive-buttons` | `whatsapp.sendInteractiveButtons()` | `--body-text` `--buttons` `--phone-number-id` `--to-number` | 3 | Send an interactive button message with up to 3 reply buttons to a WhatsApp user |
| `send-interactive-list` | `whatsapp.sendInteractiveList()` | `--body-text` `--button-text` `--phone-number-id` `--sections` `--to-number` | 3 | Send an interactive list message to a WhatsApp number |
| `send-location` | `whatsapp.sendLocation()` | `--address` `--latitude` `--longitude` `--name` `--phone-number-id` `--to-number` | 1 | Send a location message with coordinates, name, and address to a WhatsApp user |
| `send-media` | `whatsapp.sendMedia()` | `--link` `--media-type` `--phone-number-id` `--to-number` | 2 | Send a media message to a WhatsApp number |
| `send-media-by-id` | `whatsapp.sendMediaById()` | `--media-id` `--media-type` `--phone-number-id` `--to-number` | 3 | Send media using a media ID from previously uploaded media |
| `send-message` | `whatsapp.sendMessage()` | `--phone-number-id` `--text` `--to-number` | 2 | Send a text message to a WhatsApp user |
| `send-template-message` | `whatsapp.sendTemplateMessage()` | `--phone-number-id` `--template-name` `--to-number` | 3 | Send a template message to a WhatsApp number |
| `set-two-step-verification` ·common | `whatsapp.setTwoStepVerification()` | `--phone-number-id` `--pin` | 0 | Set or reset the two-step verification PIN for a WhatsApp Business phone number |
| `subscribe-app` ·common | `whatsapp.subscribeApp()` | — | 3 | Subscribe your application to receive webhook notifications for a WhatsApp Business Account (WABA) |
| `unsubscribe-app` | `whatsapp.unsubscribeApp()` | — | 1 | Unsubscribe your application from webhook events for a WhatsApp Business Account (WABA) |
| `update-business-account` | `whatsapp.updateBusinessAccount()` | `--flow-id` | 3 | Update metadata for a WhatsApp Flow including its name, categories, and endpoint URI |
| `update-business-profile` ·common | `whatsapp.updateBusinessProfile()` | `--phone-number-id` | 8 | Update WhatsApp Business Profile information including business details, contact information, and profile settings |
| `update-commerce-settings` | `whatsapp.updateCommerceSettings()` | `--phone-number-id` | 2 | Set or update commerce settings for a WhatsApp Business phone number |
| `update-flow-json` ·common | `whatsapp.updateFlowJson()` | `--flow-id` | 3 | Update the Flow JSON configuration for a WhatsApp Flow |
| `update-settings` | `whatsapp.updateSettings()` | `--phone-number-id` | 4 | Update Cloud API settings for a WhatsApp Business phone number |
| `upload-media` | `whatsapp.uploadMedia()` | `--file-to-upload` `--media-type` `--phone-number-id` | 0 | Upload media files (images, videos, audio, documents, stickers) to WhatsApp servers |
| `upsert-message-template` ·common | `whatsapp.upsertMessageTemplate()` | `--category` `--components` `--language` `--name` | 1 | Create or update a message template for the WhatsApp Business Account |
| `verify-code` | `whatsapp.verifyCode()` | `--code` `--phone-number-id` | 0 | Verify the OTP code for a pre-verified phone number |

## Triggers

`whatsapp.on("<event>", handler)` in a script; required config goes before the handler as an object.

| Event | Name | Required config | Description |
|---|---|---|---|
| `"message-status-updated"` | Message Status Updated | `phone_number_id` | Triggers when a WhatsApp message status changes |

## Docs

- [run CLI](https://docs.boxd.sh/cli/run): Call connected integrations from the shell, connect new ones, and run automations.
- [Quickstart](https://docs.boxd.sh/guides/integrations/quickstart): Connect an integration, call it from the shell, and turn a script into an automation.
- [Connections](https://docs.boxd.sh/guides/integrations/connections): Connect an account once, for yourself or for your whole organization.
- [Scripts](https://docs.boxd.sh/guides/automations/scripts): Typed integrations, triggers, schedules and state in a .run.ts file.
- [Jobs](https://docs.boxd.sh/guides/automations/jobs): How a script becomes a background job: states, retries, sleep and wake.
- [Beyond the catalog](https://docs.boxd.sh/guides/automations/beyond-the-catalog): Reach your own APIs, databases and cloud accounts from a script.