# Send a text message

`POST /v1/messages`

POST /v1/messages with `type: "text"`. Returns **202** (accepted, NOT sent): it is queued and drained at a controlled rate. The `Idempotency-Key` header (UUID) is required — retrying with the same key returns the same record (200) instead of duplicating. Identify the sending number with `connectionId` (conn_…) or `from` (phoneNumberId).

## Examples

### cURL

```bash
curl -X POST https://api.waiaconnect.com/v1/messages \
  -H "Authorization: Bearer wc_live_YOUR_API_KEY" \
  -H "Idempotency-Key: REPLACE-WITH-A-UNIQUE-ID" \
  -H "Content-Type: application/json" \
  -d '{"connectionId":"conn_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX","to":"5493511234567","type":"text","text":{"body":"Hello from WAIA Connect"}}'
```

### Node.js

```javascript
const res = await fetch("https://api.waiaconnect.com/v1/messages", {
  method: "POST",
  headers: {
    "Authorization": "Bearer wc_live_YOUR_API_KEY",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "connectionId": "conn_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "to": "5493511234567",
  "type": "text",
  "text": {
    "body": "Hello from WAIA Connect"
  }
})
});
console.log(await res.json()); // { id: "msg_…", status: "queued" }
```

### PHP

```php
<?php
$ch = curl_init("https://api.waiaconnect.com/v1/messages");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer wc_live_YOUR_API_KEY",
    "Idempotency-Key: " . bin2hex(random_bytes(16)),
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode(["connectionId" => "conn_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX","to" => "5493511234567","type" => "text","text" => ["body" => "Hello from WAIA Connect"]]),
]);
echo curl_exec($ch);
```

### Python

```python
import requests, uuid
res = requests.post("https://api.waiaconnect.com/v1/messages",
  headers={
    "Authorization": "Bearer wc_live_YOUR_API_KEY",
    "Idempotency-Key": str(uuid.uuid4()),
  },
  json={"connectionId":"conn_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX","to":"5493511234567","type":"text","text":{"body":"Hello from WAIA Connect"}})
print(res.json())  # {"id": "msg_…", "status": "queued"}
```

## Notes

- **Where those two come from:** the `conn_…` is the `id` field of `GET /v1/connections` (and it's copyable on the number's page in the panel); the `phoneNumberId` is the `phoneNumberId` field of that same response. One of the two is required even if you only have one number (send neither and you get `CONNECTION_REQUIRED`).
- `to` is E.164 (digits only, 8–15). The example uses your own number so you can test against yourself.
- **Link preview:** add `preview_url: true` inside `text` and WhatsApp will try to render a preview card for the **first** URL in the body. **Meta** builds it from that page's metadata: if the page has none, the message still goes out without a preview — that is not an error. It is optional; omit it and nothing changes.
- _Response: `{ id: "msg_…", status: "queued" }` (or `held` with a `reason`). Track the status with GET /v1/messages/:id._