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

# Batch SMS: AI-assisted drafting and rewrites

> Draft a batch SMS message from a short prompt, or rewrite the current draft with Improve, Shorter, Professional, or Friendly — the per-compose-step AI assist on the Batch SMS wizard.

# Batch SMS AI assist

The **Messages → Batch SMS** wizard's **Compose & Preview** step has an AI assist toggle beside the **Message** field. It drafts fresh copy from a short prompt and rewrites the current draft into a tighter or different tone — without leaving the wizard. Generated or rewritten text lands in the shared message body the same way a typed draft does: the segment counter, cost estimate, and per-recipient preview recompute on whatever lands there, and nothing is sent until you review and confirm the **Send** step.

This guide covers the two workflows the toggle exposes and what happens when the model returns nothing useful. For the wizard steps around it — recipients, segments, cost, and the send contract — see [Batch SMS: one-off multi-recipient sending](/guides/messages-batch-sms). For saved drafts and sent history, see [Batch Send drafts & history](/guides/messages-batch-drafts-and-history).

## 1. What the toggle is

On the **Compose & Preview** step, a Sparkles button sits beside the character and segment counter above the **Message** field. Clicking it opens an inline menu with two parts:

* **Rewrite chips** that act on the current message body — **Improve**, **Shorter**, **Professional tone**, and **Friendly tone**.
* **A prompt input** with a **Generate draft** button that drafts a new message from a short description.

The toggle is off by default and never blocks manual typing or the variable picker. Open it to draft or polish, close it to keep editing by hand. The menu is a compose-time convenience only — it never sends anything on its own.

The two parts call two endpoints behind the scenes:

| Action | Endpoint | What it sends |
| - | - | - |
| Rewrite (Improve / Shorter / Professional / Friendly) | `POST /ai/improve-text` | the current message body and the rewrite action (and tone, for the two tone options) |
| Generate from a prompt | `POST /ai/generate-content` | the prompt you typed, with `channel: sms` |

Both responses resolve through the same helper, so a well-formed response writes into the message body and a bad one surfaces a clear error instead of silently doing nothing.

## 2. Generate a draft from a prompt

Use this when you have a goal in mind but not the words. Open the AI assist menu, type a short prompt in the input, and click **Generate draft**.

1. The prompt must be non-empty — an empty prompt is rejected with a toast before any request fires.
2. The wizard calls `POST /ai/generate-content` with your prompt, `channel: sms`, and a professional tone.
3. The returned text replaces the message body. A success toast confirms it landed.
4. The segment counter, cost estimate, and per-recipient preview recompute against the new body, exactly as if you had typed it.

You can then edit the draft by hand, insert `{{variable}}` chips from the picker below, or run a rewrite on it. The generated draft is a starting point, not a commitment — the **Send** step still requires a manual confirm.

### Example

A clinic uploading a CSV of appointment recipients wants a reminder that is short and friendly. Open the AI assist menu and type:

```
Remind patients about their dental cleaning appointment tomorrow at 2pm, friendly tone, include opt-out
```

Click **Generate draft**. The message body fills with something like:

```
Hi {{first_name}}, this is a friendly reminder for your dental cleaning tomorrow at 2pm. Reply STOP to opt out.
```

The `{{first_name}}` variable was not in the prompt — you add it afterward from the **Insert variable** chips so each recipient's first name interpolates at send time. The segment counter and cost estimate update the moment the variable is in the body.

## 3. Rewrite the current draft

Use this when you already have a draft and want to tighten or retone it. The rewrite chips act on the current message body — they are disabled until there is body text to act on. Clicking a chip with an empty body is rejected with a toast ("Write a message first") before any request fires.

| Chip | What it does |
| - | - |
| **Improve** | Tightens phrasing and fixes awkward wording while keeping the meaning and length roughly the same. |
| **Shorter** | Cuts the draft down — fewer segments, lower per-recipient cost. |
| **Professional tone** | Rewrites the draft in a more formal register. |
| **Friendly tone** | Rewrites the draft in a warmer, more casual register. |

Each chip calls `POST /ai/improve-text` with the current body and the matching action (and tone, for the two tone options). The returned text replaces the body and a success toast confirms it. Run another chip on the result to iterate.

### Example

You have a draft that is correct but blunt:

```
Your order shipped. Track it at https://example.com/track. Reply STOP to opt out.
```

Click **Friendly tone**. The body rewrites to something like:

```
Great news — your order is on its way! Track it here: https://example.com/track. Reply STOP to opt out anytime.
```

The segment counter drops or holds depending on the rewrite; the cost estimate follows the segment count. Click **Shorter** next if the friendly version pushed the draft over one segment and you want the cost back down.

## 4. How variables coexist with AI output

`{{variable}}` placeholders are resolved per recipient at send time, not by the AI. Generated and rewritten text is plain body text — it lands in the shared message body the same way a hand-typed draft does, so:

* **Variables you insert after generating still interpolate.** Type or insert `{{first_name}}` into the generated body and each recipient's first name fills in at send time, exactly as it does for a typed draft. The AI does not need to know about your CSV columns.
* **The segment and cost previews recompute on the resolved body.** A generated body with a `{{first_name}}` chip is segmented against the longest resolved value per recipient, the same as a typed body with the same chip. The [Batch SMS guide](/guides/messages-batch-sms) covers how segments and per-country cost are counted.
* **Unresolved variables are still flagged.** If a generated or rewritten body references a variable name that is not in your CSV headers, or a referenced variable is empty for one or more recipients, the **Unresolved variables** warning appears under the body and blocks the **Next: Send** button until you fix it (add the column, correct the variable, or remove it).

The AI assist and the variable picker are separate controls on the same step — one writes text, the other inserts placeholders. Use them together: generate the wording, then insert the personalization chips.

## 5. When the model returns nothing useful

The assist never silently no-ops. If a call returns an empty body or a payload the wizard cannot read as text — an empty string, a shape the response envelope did not expect, or whitespace only — the wizard shows an error toast ("AI produced no content — refine and retry") and leaves the current message body untouched. The field stays fully editable; you can type or paste a draft by hand and proceed without the AI.

A workspace failure — rate limiting, an offline call, or no AI entitlement on the tenant — surfaces the same way: a toast error names the failure, the textarea and variable picker stay usable, and nothing is sent. The AI assist is an optional convenience; the wizard works end-to-end without it.

If the assist keeps failing, see the [Troubleshooting hub](/reference/troubleshooting-hub) for rate-limit and AI-upstream error guides, or draft and paste the message by hand.

## 6. Compliance and send posture

Generated and rewritten copy is still subject to the same gates as a typed draft:

* **Nothing is sent automatically.** The AI assist only writes into the message body on the **Compose & Preview** step. Sending requires the manual **Confirm** on the **Send** step, which re-reads the sender, recipient count, estimated cost, and destination chips before the batch fires.
* **Opt-out and suppression still apply.** Whatever the body says, the batch is filtered against your tenant's opt-out list and suppression rules at send time — a generated message that reaches a recipient who opted out is still suppressed, the same as a typed one. See [Opt-out lists and suppression](/guides/opt-out-lists).
* **Carrier and brand rules still apply.** Generated copy must still meet your registered-sender and brand rules for the destination — a friendly tone does not waive 10DLC campaign or alphanumeric-sender restrictions. See [Compliance posture overview](/compliance/posture-overview).
* **Compliance is tenant-owned.** Quiet hours, country allowlists, and consent rules are configured per tenant; the AI assist inherits whatever your organization has set. It does not add a platform-side gate of its own.

Review the generated body the same way you would a typed one before confirming the send.

## See also

* [Batch SMS: one-off multi-recipient sending](/guides/messages-batch-sms) — the wizard this toggle lives on
* [Batch Send drafts & history](/guides/messages-batch-drafts-and-history) — resume, rename, and delete saved batch drafts
* [Opt-out lists and suppression](/guides/opt-out-lists) — how tenant-level opt-out and suppression gates filter the batch
* [Compliance posture overview](/compliance/posture-overview) — tenant-owned compliance controls
* [Messaging API reference](/api-reference/endpoints/messaging) — request/response schemas for every channel


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.