---
title: "Send one text or WhatsApp message as the business (sms:write). Email goes out through POST /v1/email-campaigns."
method: POST
path: "/v1/messages"
---

# Send one text or WhatsApp message as the business (sms:write). Email goes out through POST /v1/email-campaigns.

`POST /v1/messages`

## Request

- Base URL: `https://www.kaicalls.com/api`
- URL: `https://www.kaicalls.com/api/v1/messages`
- Auth: HTTP bearer

One send endpoint for texts and WhatsApp. sms goes out from the agent's own line (from_agent_id required) with the same gates and error codes as POST /v1/sms/send. whatsapp goes out from the business's number connected to WhatsApp (pass from when there is more than one) and only inside the 24-hour window after the customer last messaged that number; WhatsApp consent and Do-Not-Call are checked first. Email is not sent here: channel email is 400 use_email_campaigns. API email goes out as a campaign the business owner reviews and approves, through POST /v1/email-campaigns. Send Idempotency-Key (or idempotency_key) to make a retry return the original send (replayed: true) instead of sending again; the same key with a different message is 409 idempotency_conflict. New keyed WhatsApp sends claim a durable intent before dispatch; concurrent or uncertain replays never dispatch again. A 409 message_outcome_unknown requires reconciliation, not a new key. Pre-existing lost receipts cannot be recovered. 503 idempotency_unavailable means reservation or replay evidence could not be verified. A 200 means the provider accepted the message, not that it was delivered.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `channel` 'sms' | 'whatsapp', required: email is refused with 400 use_email_campaigns.
  - `to` string, required: E.164 phone number.
  - `body` string, required: Alias: message.
  - `business_id` string, uuid: Required when the API key reaches more than one business.
  - `from_agent_id` string, uuid: sms only, required there.
  - `from` string: whatsapp only: the business's connected WhatsApp number.
  - `lead_id` string, uuid
  - `idempotency_key` string

## Response `200`

Accepted by the provider.

- object
  - `id` string, required
  - `channel` 'sms' | 'whatsapp', required
  - `status` 'sent' | 'queued', required
  - `to` string, required
  - `from` string, required
  - `provider` string
  - `replayed` boolean

## Other responses

- `400`: Invalid request or a compliance block: bad_request, use_email_campaigns, business_id_required, from_required, automation_paused, number_opted_out, number_on_dnc, content_blocked, tcpa_violation, rate_limit_exceeded.
- `403`: Missing sms:write scope, or no access to business_id (forbidden).
- `404`: Agent or lead not found (not_found).
- `409`: whatsapp_not_connected, whatsapp_window_closed, idempotency_conflict, message_outcome_unknown.
- `502`: Provider failure: sms_send_failed, whatsapp_send_failed, outcome_unknown.
- `503`: idempotency_unavailable: WhatsApp replay evidence cannot be verified; no new send.

---

[API](https://skmtc.dev/kaicalls/apis/kaicalls-public-api.md) · [All operations](https://skmtc.dev/kaicalls/apis/kaicalls-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kaicalls/apis/kaicalls-public-api/revisions/e607fc6cf36e?raw)