# WhatsApp Direct Send

> Send WhatsApp utility and authentication messages through Revora without waiting for template approval. Covers eligibility, content rules and the API.

Developers · REST API

## What is Direct Send?

Normally, every business-initiated WhatsApp message must use a template that has been submitted and approved by Meta in advance. **Direct Send** is a Meta feature that removes that step for transactional messages:

- You send the message content directly (body, optional header, footer and buttons).
- Meta checks whether it matches an existing template. If it does, that template is used.
- If not, the message is still delivered, and Meta creates a matching template in the background so future messages with the same content reuse it.
**Good for:** order and shipping updates, payment receipts, appointment reminders, delivery slots, account alerts, and one-time passcodes (OTPs). Anything where the content changes too often to manage a template for each version.

**Not for:** marketing or promotional messages. Meta does not support them through Direct Send and penalises accounts that use it for promotions (see [Content rules](#content-rules)).

| Category | Status on Meta |
| --- | --- |
| Utility | Generally available |
| Authentication (OTP) | Beta: Meta must enable it for your account |
| Marketing | Not supported |

---

## Eligibility

Your account must meet **all** of the following.

**Meta requirements**
- The WhatsApp number's messaging limit is **100K or Unlimited** unique customers per 24 hours. Meta is rolling Direct Send out in phases. Your WhatsApp Manager shows a banner when your account is eligible.
- For **authentication** messages, Meta has accepted your account into the beta.
**MyAlice requirements**
- Billing is enabled on the project. Trial projects can't use Direct Send.
- Prepaid projects have **at least 1 broadcast credit**.
- The channel is a connected WhatsApp channel in the same project as your API key.
> MyAlice checks the number's messaging limit with Meta, then caches the result for up to 7 days. If the limit goes up, it can take up to a week to reflect.

---

## Content rules

Direct Send is for **utility and authentication content only**. Meta monitors what is sent. Accounts that keep sending promotional content as "utility" are first rate-limited for 24 hours, then blocked for longer periods, and can lose Direct Send access permanently.

Avoid offers, discounts, upsells, "shop now" calls to action, and re-engagement nudges. Use a normal approved marketing template for those.

---

## API reference

### Endpoint

```
POST https://api.myalice.ai/stable/open/whatsapp/{channel_id}/direct-send-template
```

| | |
| --- | --- |
| **Auth** | Project API key in the `X-Myalice-Api-Key` header (or `api_key` query param). If the project has allowed IPs, calls must come from one of them. |
| **`channel_id`** | ID of a connected WhatsApp channel in the same project. |
| **Content type** | `application/json` |

The request is validated immediately and the message is sent **in the background**. A `200` means "queued", not "delivered".

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `customer_phone` | string | Yes | Recipient in international format. Spaces, `+` and dashes are stripped. `+880 1712-345678` works. |
| `name` | string | Yes | Your name for the message (lowercased, spaces become `_`). For utility, this becomes the template name on Meta, and every send with the same name is reported under it. |
| `category` | string | Yes | `utility` or `authentication` (any case). |
| `language` | string | Yes | Language code, e.g. `en`, `en_US`. |
| `body` | string | Yes | Message text, max 1024 characters. Supports [variables](#variables). |
| `header` | object | No | `{"type": "text" \| "image" \| "video" \| "document", "value": "..."}`. Text: max 60 characters, supports variables. Media: a public URL. **Requires at least one button.** |
| `footer` | string | No | Max 60 characters. **Requires at least one button.** |
| `buttons` | array | No | See [Buttons](#buttons). |
| `attributes` | object | No | Values for variables in the body, text header and URL button. |
| `message_send_ttl_seconds` | integer | No | How long Meta retries delivery. Utility: 30–43200. Authentication: 30–900. |
| `code_expiration_minutes` | integer | No | Authentication only. Expiry shown with the copy-code button. |

> **Why do header and footer need a button?** WhatsApp sends a message with no buttons as plain text, which has no header or footer. Requests with a header or footer but no buttons are rejected with `400`.

### Buttons

Each button: `{"id": 1, "type": "...", "title": "...", "value": "..."}`. All four keys are required. `title` is the button label (1–20 characters). **All buttons in one message must be the same type.**

| `type` | Category | Max | `value` | Shows as |
| --- | --- | --- | --- | --- |
| `url` | utility | 1 | Link to open (`https://` added if missing). May end with one variable, e.g. `https://shop.com/orders/{{order_id}}`. | Call-to-action URL button |
| `sequence` | utility | 3 | ID of a MyAlice sequence on this channel. Tapping starts that sequence. | Quick reply buttons |
| `OTP` | authentication | 1 | Send `""`. The code comes from the first variable in the body. | Copy-code button |

### Variables

Write variables as `{{key}}` in the body, text header or URL button. Each is filled from the first available source:

1. `attributes.key` in the request
2. The customer's saved attribute with the same key
3. An inline fallback: `{{first_name|there}}` becomes `there`
| Where | Example | Attribute key used |
| --- | --- | --- |
| Body | `Hi {{first_name}}` | `first_name` |
| Text header | `Order {{order_id}}` | `order_id` |
| Media header | Default URL in `header.value` | `image` / `video` / `document` to override the file for this send |
| URL button | `https://shop.com/o/{{order_id}}` | `button_{id}`, then `button_attribute`, then `order_id` |
| OTP code | `{{1}} is your code` | `1`. This value becomes the copy code. |

> ⚠️ **Every variable must resolve to a value.** If any variable is empty, the message is **not sent**, but the API still returns `200` because sending happens in the background. The generated template is marked **rejected** with the reason `Missing values for: ...`. Use fallbacks (`{{name|there}}`) wherever data may be missing.

### Limits

| Part | Limit |
| --- | --- |
| Body | 1024 characters |
| Text header | 60 characters |
| Footer | 60 characters |
| Button text | 20 characters |
| URL buttons | 1 per message |
| Quick reply (sequence) buttons | 3 per message |
| OTP buttons | 1 per message |
| Header / footer | Only with ≥ 1 button |

**Not supported:** marketing messages, carousels, WhatsApp Flows, voice-call buttons, phone-number buttons, and mixing button types.

**OTP tip:** keep codes to 4–10 letters or digits. Meta's copy-code button currently supports English only.

---

## Examples

**Utility: document header, footer and tracking link**

```bash
curl -X POST "https://api.myalice.ai/stable/open/whatsapp/1234/direct-send-template" \
  -H "X-Myalice-Api-Key: {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_phone": "+8801712345678",
  "name": "order_shipped",
  "category": "utility",
  "language": "en",
  "header": {"type": "document", "value": "https://cdn.shop.com/invoices/A1029.pdf"},
  "body": "Hi {{first_name}}, your order {{order_id}} has shipped and will arrive in 2-3 days.",
  "footer": "Reply STOP to opt out",
  "buttons": [
    {"id": 1, "type": "url", "title": "Track order", "value": "https://shop.com/track/{{order_id}}"}
  ],
  "attributes": {"first_name": "Nadia", "order_id": "A1029"},
  "message_send_ttl_seconds": 3600
}'
```

**Utility: quick replies that trigger sequences**

```json
{
  "customer_phone": "+8801712345678",
  "name": "delivery_slot",
  "category": "utility",
  "language": "en",
  "header": {"type": "text", "value": "Delivery tomorrow"},
  "body": "Hi {{first_name|there}}, is 10am-1pm a good time for your delivery?",
  "buttons": [
    {"id": 1, "type": "sequence", "title": "Yes, that works", "value": "5501"},
    {"id": 2, "type": "sequence", "title": "Pick another time", "value": "5502"}
  ],
  "attributes": {"first_name": "Nadia"}
}
```

**Authentication: OTP with copy-code button**

```json
{
  "customer_phone": "+8801712345678",
  "name": "login_code",
  "category": "authentication",
  "language": "en",
  "body": "{{1}} is your verification code. Do not share it.",
  "buttons": [
    {"id": 1, "type": "OTP", "title": "Copy code", "value": ""}
  ],
  "attributes": {"1": "482193"},
  "code_expiration_minutes": 10,
  "message_send_ttl_seconds": 300
}
```

**Utility: plain text (no buttons, so body only)**

```json
{
  "customer_phone": "+8801712345678",
  "name": "payment_received",
  "category": "utility",
  "language": "en",
  "body": "We received your payment of BDT {{amount}} for order {{order_id}}. Thank you!",
  "attributes": {"amount": "2,450", "order_id": "A1029"}
}
```

---

## Responses

### 200 Queued

```json
{
  "success": true,
  "message": "Direct send message is queued for sending."
}
```

The response does not wait for WhatsApp and has no `conversation_id`. Sent, delivered and read statuses are tracked in MyAlice like any other template message. If WhatsApp refuses the message, or a variable is missing, the generated template is marked **rejected** with the reason.

### Errors

All errors are returned **before** anything is sent and share one shape:

```json
{"error": "...", "code": "invalid", "success": false}
```

| Status | When | Example `error` |
| --- | --- | --- |
| 400 | Field missing, too long or not allowed | `Error on Field body. Detail: Ensure this field has no more than 1024 characters.` |
| 400 | Wrong category, button type or count | `Button type OTP is not supported for utility direct send.` |
| 400 | Header/footer without buttons | `Header and footer need at least one button in direct send.` |
| 400 | Button missing a title | `Each button must have a title.` |
| 400 | OTP button but no body variable | `Body must contain a variable for the OTP code, e.g. {{code}} is your code.` |
| 400 | Unknown channel for this project | `Please provide a valid channel id.` |
| 401 | Missing or wrong API key | `Invalid api key provided.` |
| 401 | Call from a non-allowed IP | `Access from this IP address 203.0.113.7 is not allowed.` |
| 402 | Trial project or no broadcast credit | `Need to enable billing to send template!` |
| 403 | Messaging limit below 100K | `This number is not permitted to use direct send.` |
| 503 | Couldn't verify messaging limit with Meta (safe to retry) | `Could not verify the messaging limit of this number. Please try again.` |

---

## FAQ

**Do I need to create templates in MyAlice or WhatsApp Manager first?**
No. Templates are generated automatically and named after the `name` you send.

**Why did I get `200` but the customer got nothing?**
Usually a variable had no value, or WhatsApp refused the content. Check the generated template's status in MyAlice for the rejection reason.

**How is it billed?**
Each message is charged at the WhatsApp rate for its category (utility or authentication), the same as a regular template message.

**Can I send marketing through Direct Send?**
No. Use an approved marketing template via broadcasts instead.

---

## Need help?

For eligibility checks, setup or any other help with Direct Send, contact your Customer Success Manager.

---
HTML: https://userevora.com/docs/developers/whatsapp-direct-send
