> ## Documentation Index
> Fetch the complete documentation index at: https://plivo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Messaging

> Send and list SMS, MMS and WhatsApp messages; manage 10DLC and Powerpacks.

Send SMS, MMS or WhatsApp messages and check delivery. After [logging in](https://plivo.com/docs/cli/install.md#log-in-with-a-browser), replace the example numbers with an enabled sender and your test recipient:

```bash theme={null}
plivo messaging sms send --src 14155550100 --dst 14155550101 \
  --text "Hello from Plivo" --dry-run
```

Replace `--dry-run` with `--yes` to send the billed message. Check delivery with `plivo messaging get "<message_uuid>"`, using the message UUID the send returns.

SMS is text messaging; MMS adds media. Numbers use E.164 format with a country code, such as `+14155550100`. US application-to-person (A2P) messaging from a ten-digit local number needs 10DLC registration before you send.

Command syntax: replace `<values>` and omit `[flags]` unless adding options. Global flags (`-o`, `--query`, `--dry-run`, `--yes`, `--schema`) and the paging flags `--all`, `--limit` and `--offset` on every list: see [Configuration](https://plivo.com/docs/cli/configure.md).

## Filter message lists by date

`plivo messaging sms list`, `mms list` and `whatsapp list` take the same flags (dates below are examples):

```bash theme={null}
plivo messaging sms list --since 2026-10-01
plivo messaging whatsapp list --since 2026-10-01 --until 2026-10-07 --all -o json
```

| Flag | Description |
| - | - |
| `--since <value>` | sent or received at or after this UTC time (`YYYY-MM-DD[ HH:MM[:SS]]`), within the last 90 days. Same as `--from-date` |
| `--until <value>` | sent or received at or before this UTC time. A bare date includes the whole day. Needs `--since`. Same as `--to-date` |
| `--direction <value>` | inbound\|outbound |
| `--state <value>` | queued\|sent\|delivered\|undelivered\|failed\|received |

Plivo searches only the last 90 days. A range starting earlier is refused before any request, with the earliest date you can use.

The Message API can't filter by number, so `--from` and `--to` are refused with `BAD_FLAG`. Use `--query` with `--all` instead:

```bash theme={null}
plivo messaging sms list --since 2026-10-01 --all --query "data.objects[?from_number=='14155550100']"
```

## SMS

For US local numbers, register a business profile, a brand and a campaign (your messaging use case), then link the number to the campaign. Toll-free numbers use a separate verification request. A Powerpack groups numbers for sending.

### Send and list SMS

| Command | What it does |
| - | - |
| `plivo messaging sms list [flags]` | List SMS messages. Flags: see [Filter message lists by date](#filter-message-lists-by-date) |
| `plivo messaging sms send [flags]` | Send an SMS (requires --yes; spends money: use --dry-run to preview) |

> [accordion] plivo messaging sms send
>
> `whatsapp send` takes the same flags; `mms send` adds `--media-url`.
>
> | Flag | Description |
> | - | - |
> | `--dst <value>` | destination number; quote multiple destinations joined by `<`, for example `"14155550101<14155550102"` (required) |
> | `--explain` | narrate in plain English before executing |
> | `--method <value>` | callback method GET\|POST (default "POST") |
> | `--src <value>` | sender (E.164, shortcode, or sender ID) (required) |
> | `--text <value>` | message body (required) |
> | `--url <value>` | callback URL for delivery status |

### 10DLC registration

| Command | What it does |
| - | - |
| `plivo messaging sms 10dlc` | US A2P 10DLC registration: brands, campaigns, links |
| `plivo messaging sms 10dlc brands` | 10DLC brand registration (US A2P 10-digit-long-code messaging) |
| `plivo messaging sms 10dlc campaigns` | 10DLC campaign registration (use cases for a brand) |
| `plivo messaging sms 10dlc links` | 10DLC number-to-campaign linking |
| `plivo messaging sms 10dlc brands create [flags]` | Register a new brand (spends money: The Campaign Registry (TCR) registration fee, requires --yes) |
| `plivo messaging sms 10dlc brands get <brand_id>` | Get a brand by ID |
| `plivo messaging sms 10dlc brands list [flags]` | List registered brands |
| `plivo messaging sms 10dlc campaigns create [flags]` | Register a new campaign (spends money: TCR fee, requires --yes) |
| `plivo messaging sms 10dlc campaigns get <campaign_id>` | Get a campaign by ID |
| `plivo messaging sms 10dlc campaigns list [flags]` | List campaigns. `--brand-id` filters by brand |
| `plivo messaging sms 10dlc campaigns update <campaign_id> [flags]` | Update a failed campaign (spends money: carrier review fee, requires --yes) |
| `plivo messaging sms 10dlc links create [flags]` | Link a number to a campaign |
| `plivo messaging sms 10dlc links delete <campaign_id> <number>` | Unlink a number from a campaign (requires --yes) |
| `plivo messaging sms 10dlc links list [flags]` | List the numbers linked to a campaign, with each link's status |

> [accordion] plivo messaging sms 10dlc brands create
>
> | Flag | Description |
> | - | - |
> | `--alias <value>` | human-friendly alias (required) |
> | `--brand-type <value>` | registration type, STANDARD\|STARTER; sent only when given |
> | `--profile-uuid <value>` | the 10DLC profile holding the company's details (required) |
> | `--secondary-vetting` | STANDARD only: send the brand for secondary vetting, a separate fee (default true) |
>
> A brand is registered from a 10DLC profile holding the company's legal name, employer identification number (EIN), address, website and contact. A profile registers one brand. List profiles with `plivo api GET /Profile/`; create one in the console or with `plivo api POST /Profile/`. Without `--brand-type` the API registers a `STANDARD` brand, which needs a profile with an EIN and is sent for secondary vetting (a separate one-time fee) unless you pass `--secondary-vetting=false`.
>
> There is no brand update: the API has none.

> [accordion] plivo messaging sms 10dlc campaigns create
>
> | Flag | Description |
> | - | - |
> | `--affiliate-marketing` | affiliate marketing campaign |
> | `--age-gated` | campaign targets adult content |
> | `--alias <value>` | human-friendly alias (required) |
> | `--brand-id <value>` | brand to register under (required) |
> | `--description <value>` | what this campaign does (required) |
> | `--direct-lending` | direct-lending arrangements |
> | `--embedded-link` | messages contain links |
> | `--embedded-phone` | messages contain phone numbers |
> | `--help-keywords <value>` | comma-separated help keywords (default "HELP") |
> | `--help-message <value>` | auto-reply to HELP (required) |
> | `--message-flow <value>` | describe how recipients opt in (required) |
> | `--opt-in-keywords <value>` | opt-in keywords (default "START") |
> | `--opt-in-message <value>` | opt-in confirmation message |
> | `--opt-out-keywords <value>` | opt-out keywords (default "STOP") |
> | `--opt-out-message <value>` | auto-reply to STOP (required) |
> | `--sample-message-1 <value>` | sample message (required) |
> | `--sample-message-2 <value>` | second sample message (required) |
> | `--sub-usecases <value>` | comma-separated sub use cases |
> | `--subscriber-help` | declare that a HELP reply tells recipients how to reach you (required) |
> | `--subscriber-optin` | declare that you collect and process opt-ins (required) |
> | `--subscriber-optout` | declare that you process opt-outs (required) |
> | `--usecase <value>` | primary use case, e.g. MARKETING, MIXED (required) |
> | `--vertical <value>` | industry, e.g. TECHNOLOGY, RETAIL, HEALTHCARE (required) |

> [accordion] plivo messaging sms 10dlc campaigns update
>
> | Flag | Description |
> | - | - |
> | `--description <value>` | new description |
> | `--message-flow <value>` | new message flow |
> | `--sample-message-1 <value>` | new sample 1 |
> | `--sample-message-2 <value>` | new sample 2 |
>
> Each update sends the campaign to the carriers for review again and is charged, so it needs `--yes` (or `--dry-run` to preview). The API allows updates only for a campaign whose registration failed (`registration_status` `FAILED`).

> [accordion] plivo messaging sms 10dlc links create and list
>
> | Flag | Description |
> | - | - |
> | `--campaign-id <value>` | 10DLC campaign id (required on both) |
> | `--number <value>` | `create`: the number, digits with the country code, e.g. 14155550100 (required). `list`: only this number's link (no --limit, --offset or --all) |

### Toll-free verification

| Command | What it does |
| - | - |
| `plivo messaging sms tollfree` | Toll-free verification (US TFN messaging compliance) |
| `plivo messaging sms tollfree get <uuid>` | Get a toll-free verification request by its uuid |
| `plivo messaging sms tollfree list [flags]` | List toll-free verification requests. `--status` filters: SUBMITTED\|PROCESSING\|APPROVED\|REJECTED\|UPDATE\_REQUIRED |
| `plivo messaging sms tollfree submit [flags]` | Submit a toll-free number for verification |

> [accordion] plivo messaging sms tollfree submit
>
> | Flag | Description |
> | - | - |
> | `--message-volume <value>` | messages a month: 10, 100, 1000, 10000, 100000, 250000, 500000, 750000, 1000000, 5000000 or 10,000,000+ (required) |
> | `--number <value>` | the toll-free number: digits with the country code, e.g. 18005550100 (required) |
> | `--opt-in-image-url <value>` | URL of an image or document that shows the opt-in (required) |
> | `--opt-in-type <value>` | how recipients opt in: VERBAL\|WEB\_FORM\|PAPER\_FORM\|VIA\_TEXT\|MOBILE\_QR\_CODE (required) |
> | `--privacy-policy-link <value>` | public URL of your privacy policy (required) |
> | `--production-message-content <value>` | sample messages you will send (required) |
> | `--profile-uuid <value>` | the profile holding the business's details (required) |
> | `--terms-and-conditions-link <value>` | public URL of your terms and conditions (required) |
> | `--use-case <value>` | use case, or several comma-separated, e.g. 2FA,CUSTOMER\_CARE (required) |
> | `--use-case-summary <value>` | how the number's messages are used (required) |
>
> Submits one number. The business's details come from a profile, the same kind 10DLC brands use. List yours with `plivo api GET /Profile/`.

### Powerpacks

| Command | What it does |
| - | - |
| `plivo messaging sms powerpacks` | Powerpacks: number pools for high-volume SMS |
| `plivo messaging sms powerpacks create [flags]` | Create a powerpack |
| `plivo messaging sms powerpacks delete <uuid>` | Delete a powerpack (requires --yes) |
| `plivo messaging sms powerpacks get <uuid>` | Get a powerpack by uuid |
| `plivo messaging sms powerpacks list [flags]` | List powerpacks |
| `plivo messaging sms powerpacks numbers` | Manage numbers inside a powerpack |
| `plivo messaging sms powerpacks update <uuid> [flags]` | Update a powerpack. Flags: `--name`, `--local-connect true\|false`, `--sticky-sender true\|false` |
| `plivo messaging sms powerpacks numbers add <uuid> <number>` | Add a number to a powerpack |
| `plivo messaging sms powerpacks numbers list <uuid> [flags]` | List numbers attached to a powerpack |
| `plivo messaging sms powerpacks numbers remove <uuid> <number>` | Remove a number from a powerpack (requires --yes) |

> [accordion] plivo messaging sms powerpacks create
>
> | Flag | Description |
> | - | - |
> | `--application-id <value>` | application uuid (when application-type=xml\_application) |
> | `--application-type <value>` | default\_message\|xml\_application |
> | `--local-connect` | use a local-prefix-matching number |
> | `--name <value>` | powerpack name (required) |
> | `--number-priority <value>` | ordered priority list (e.g. "local,tollfree") |
> | `--sticky-sender` | send from same number to same recipient |

## MMS

Send multimedia messages in the US or Canada from an MMS-enabled sender, with a publicly reachable media URL:

```bash theme={null}
plivo messaging mms send --src 14155550100 --dst 14155550101 \
  --text "Your image" --media-url https://example.com/image.jpg --dry-run
```

| Command | What it does |
| - | - |
| `plivo messaging mms list [flags]` | List MMS messages. Flags: see [Filter message lists by date](#filter-message-lists-by-date) |
| `plivo messaging mms send [flags]` | Send an MMS (requires --yes; spends money: use --dry-run to preview) |

`mms send` takes the [`sms send` flags](#send-and-list-sms) plus `--media-url <value>`: URL of a hosted image or media file to attach (repeatable, up to 10).

## WhatsApp

Use a sender connected to Plivo's WhatsApp Business API. The CLI sends text with `--text`; it has no template flag. For a text reply allowed by your WhatsApp conversation:

```bash theme={null}
plivo messaging whatsapp send --src 14155550100 --dst 14155550101 \
  --text "Thanks for your message" --dry-run
```

For template payloads, use [Any REST endpoint](https://plivo.com/docs/cli/apis/api.md) with the [Message API](https://plivo.com/docs/messaging/api/message/send-a-message).

| Command | What it does |
| - | - |
| `plivo messaging whatsapp list [flags]` | List WhatsApp messages. Flags: see [Filter message lists by date](#filter-message-lists-by-date) |
| `plivo messaging whatsapp send [flags]` | Send a WhatsApp message (requires --yes; spends money: use --dry-run to preview). Same flags as [`sms send`](#send-and-list-sms) |

## Diagnose a message

Give the CLI a message UUID and it explains why the message failed: the error code, the carrier response, and what to change. Find IDs with the `list` commands above.

| Command | What it does |
| - | - |
| `plivo messaging sms diagnose <message_uuid>` | Explain what happened to an SMS |
| `plivo messaging mms diagnose <message_uuid>` | Explain what happened to an MMS |
| `plivo messaging whatsapp diagnose <message_uuid>` | Explain what happened to a WhatsApp message |

Answers usually take 30 to 120 seconds. Only messages on your own account can be diagnosed. `diagnose` and `plivo ask` share a limit of 5 requests per 60 seconds per account. With `-o json` it prints one result with fixed fields, and it exits `3` if the analysis fails or stops early; see [Read the result in a script](https://plivo.com/docs/cli/voice-agent/diagnose-call.md#read-the-result-in-a-script).

## Get any message

| Command | What it does |
| - | - |
| `plivo messaging get <message_uuid>` | Get a message by UUID (works for SMS, MMS, and WhatsApp) |