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

# Send SMS

> Send standalone text messages via the API

Beyond mid-call and post-call SMS, you can send standalone messages via the API. Useful for appointment reminders, status updates, follow-ups — anything that doesn't need a phone call.

## Send one message

```bash theme={null}
curl -X POST https://api.nixflex.com/v1/sms \
  -H "Authorization: Bearer KEY_ID:KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_125207e452f8714a",
    "to": "+447386172392",
    "from_number": "+447446466847",
    "message": "Reminder: your appointment is tomorrow at 2pm. Reply YES to confirm or NO to reschedule."
  }'
```

| Field         | Required | Notes                                                                                                                                                                                                     |
| ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent_id`    | Yes      | The agent this SMS belongs to (determines reply behaviour)                                                                                                                                                |
| `to`          | Yes      | Recipient in E.164 format                                                                                                                                                                                 |
| `from_number` | Yes      | One of your imported Twilio numbers                                                                                                                                                                       |
| `message`     | Yes      | The message text. **600 chars recommended** for reliable delivery. Twilio's hard cap is 1600, but UK carriers often reject longer messages. See [SMS length guide](#sms-length-and-deliverability) below. |

Response:

```json theme={null}
{
  "message_id": "SM1234567890",
  "status": "queued",
  "to": "+447386172392",
  "from_number": "+447446466847"
}
```

Status updates flow through Twilio's status callbacks. The final status (`delivered`, `failed`, etc.) reflects in the message record within \~30 seconds.

## SMS length and deliverability

Even though Twilio's API accepts messages up to 1600 characters, real-world delivery is more nuanced. Carriers — especially UK mobile carriers — silently reject long messages without giving an error code.

**Recommended ceiling: 600 characters.** This stays within reliable delivery limits while leaving room for variable expansion in templates.

| Length      | Segments | Cost     | Reliability                   |
| ----------- | -------- | -------- | ----------------------------- |
| 160 chars   | 1        | Cheapest | 99%+ delivery                 |
| 320 chars   | 2        | 2×       | 99%+ delivery                 |
| 480 chars   | 3        | 3×       | 95-99% delivery               |
| 600 chars   | 4        | 4×       | \~95% delivery                |
| 1000+ chars | 7+       | High     | Often rejected by UK carriers |

**Each segment costs \~£0.04 to send.** A 600-char message costs \~£0.16 per send, versus £0.04 for 160 chars.

If you need longer content, consider:

* Splitting into multiple SMS
* Including a link to a webpage
* Switching to email for that customer

For Post-Call SMS templates configured in the dashboard, the textarea is hard-capped at 600 chars to enforce the safe zone.

## How replies are handled

When someone replies to your SMS, Twilio routes the inbound message to the agent that owns the `from_number`. The agent answers using its `system_prompt` — the same prompt that drives phone calls.

**This means:** if you expect customers might reply with questions about what you sent, mention the context in the agent's `system_prompt` *before* you send the SMS.

For example, if you're sending appointment reminders, add this to the agent system\_prompt:

> You are the receptionist at Acme Dental. If a customer replies to an appointment reminder with YES, confirm the booking. If they reply NO or want to reschedule, offer alternative slots. If they ask any question about their appointment, answer warmly using the information you have.

Now whether the customer replies to the SMS, sends a fresh text later, or calls in — the agent is ready.

## Tracking

Every SMS gets a `message_id` you can use to fetch status:

```bash theme={null}
curl https://api.nixflex.com/v1/sms/SM1234567890 \
  -H "Authorization: Bearer KEY_ID:KEY_SECRET"
```

Response includes `status` (`queued`, `sent`, `delivered`, `failed`, `undelivered`), error code if any, and the conversation thread if replies happened.

<Note>
  **Twilio status meanings:** `delivered` means the carrier confirmed delivery to the handset. `sent` means Twilio handed off to the carrier but never got confirmation — we treat this as a soft failure in the dashboard. `failed` and `undelivered` are hard failures.
</Note>

## Mid-call and post-call SMS

For sending SMS from inside a live call (booking confirmations, links) or automatically after every call (summaries), see [Send SMS action](/actions/send-sms). Those use the `[SEND_SMS:]` tag and `post_call_sms_template` on the agent — no separate API call needed.

## Bulk campaigns

For sending the same message to many recipients in one call, use [SMS campaigns](/sms/sms-campaigns).

## Compliance

<Warning>
  **UK only at launch.** US SMS requires A2P 10DLC registration on your Twilio account. Without it, US messages are rejected by carriers.

  You're responsible for:

  * Opt-in records (you have permission to text these numbers)
  * Handling STOP / UNSUBSCRIBE keywords (Twilio handles this automatically by default)
  * Respecting time-of-day rules (no messages 9pm-9am in the recipient's timezone)

  Nixflex provides infrastructure; compliance stays with you.
</Warning>

## Pricing

SMS uses your Twilio account directly. Twilio charges per message at standard rates:

* UK domestic: \~£0.04 per message
* US (after A2P): \~\$0.0075 per segment
* International: varies by country

Nixflex doesn't mark up SMS pricing.