# Send Messages

> Send a single WhatsApp message — text, template, media, interactive buttons, or list — via the WAFlow Public API.

Source: https://edesy.in/docs/waflow/api/messages

Send one WhatsApp message to one recipient. The message is delivered through your workspace's connected provider (Meta Cloud API, Twilio, or Plivo).

```http
POST /api/v1/messages
```

**Required scope:** `messages.send`

Every request body has a `to` (recipient in [E.164](https://en.wikipedia.org/wiki/E.164) format) and a `type`. The remaining fields depend on the `type`.

> **Note:** Free‑form messages (`text`, `media`, `buttons`, `list`) can only be delivered inside an open **24‑hour customer service window** — i.e. the customer messaged you within the last 24 hours. To *start* a conversation, send a `template` message.

## Response

```json
{
  "success": true,
  "messageId": "wamid.HBgMOTE5NTQ3NTMxMzU5FQIAERgS...",
  "to": "+919812345678",
  "type": "text",
  "timestamp": "2026-07-21T09:00:00.000Z"
}
```

If the provider rejects the message you receive `502`:

```json
{
  "success": false,
  "error": "Failed to send message",
  "code": "SEND_FAILED",
  "details": "Message failed to send",
  "providerErrorCode": "131047"
}
```

---

## Text

```json
{
  "to": "+919812345678",
  "type": "text",
  "text": "Your order has shipped!"
}
```

**cURL Example:**
```bash
curl -X POST "https://waflow.edesy.in/api/v1/messages" \
  -H "X-API-Key: wc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+919812345678", "type": "text", "text": "Your order has shipped!" }'
```

---

## Template

Use an approved template to start a conversation. `bodyParameters` fills the `{{1}}`, `{{2}}`, … placeholders in order.

```json
{
  "to": "+919812345678",
  "type": "template",
  "template": {
    "name": "order_update",
    "language": "en_US",
    "bodyParameters": ["Raj", "#1234"]
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `template.name` | string | The approved template's name |
| `template.language` | string | Language code (default `en_US`) |
| `template.bodyParameters` | string[] | Positional values for body variables |
| `template.headerParameters` | array | Optional header component parameters |
| `template.buttonParameters` | array | Optional button component parameters |

**cURL Example:**
```bash
curl -X POST "https://waflow.edesy.in/api/v1/messages" \
  -H "X-API-Key: wc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919812345678",
    "type": "template",
    "template": { "name": "order_update", "language": "en_US", "bodyParameters": ["Raj", "#1234"] }
  }'
```

---

## Media

```json
{
  "to": "+919812345678",
  "type": "media",
  "media": {
    "type": "image",
    "url": "https://example.com/receipt.png",
    "caption": "Your receipt"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `media.type` | string | `image`, `video`, `audio`, or `document` |
| `media.url` | string | Publicly reachable HTTPS URL of the media |
| `media.caption` | string | Optional caption (not for audio) |
| `media.filename` | string | Optional filename (documents) |

---

## Interactive buttons

Up to three reply buttons.

```json
{
  "to": "+919812345678",
  "type": "buttons",
  "interactive": {
    "body": "Confirm your appointment?",
    "buttons": [
      { "id": "confirm", "title": "Confirm" },
      { "id": "reschedule", "title": "Reschedule" }
    ],
    "footer": "Ayush Hospital"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `interactive.body` | string | Message text |
| `interactive.buttons` | array | 1–3 buttons, each `{ id, title }` (title ≤ 20 chars) |
| `interactive.header` | string | Optional header text |
| `interactive.footer` | string | Optional footer text |

---

## Interactive list

```json
{
  "to": "+919812345678",
  "type": "list",
  "list": {
    "body": "Choose a service",
    "buttonText": "View services",
    "sections": [
      {
        "title": "Consultations",
        "rows": [
          { "id": "gen", "title": "General", "description": "₹500" },
          { "id": "spec", "title": "Specialist", "description": "₹1200" }
        ]
      }
    ]
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `list.body` | string | Message text |
| `list.buttonText` | string | The list's button label (≤ 20 chars) |
| `list.sections` | array | Sections, each with a `title` and `rows` |
| `list.sections[].rows` | array | Rows, each `{ id, title, description? }` |

---

## Delivery status

The `messageId` returned is the WhatsApp message id (`wamid…`). To be notified when the message is **sent**, **delivered**, **read**, or **failed**, subscribe to the [messaging webhooks](https://edesy.in/docs/waflow/api/webhooks).