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

# Sending

> POST /api/v1/send - shortest path to a 1:1 iMessage.

Use `/send` when you only need to send a 1:1 text message to a phone number. Use [Create a chat](/api/chats/create) when you need a durable `chat.id`, attachments by URL, or chat history. Use [Create a group](/api/group-chats/create) for group chats.

## Request

```bash theme={null}
curl https://console.trychert.com/api/v1/send \
  -H "Authorization: Bearer $CHERT_SIGNING_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+14155551234",
    "body": "Hi Sam - got a minute?",
    "idempotency_key": "send-2026-05-01-001"
  }'
```

## Response

```json theme={null}
{
  "status": "sent",
  "message_id": "46eb1003c8b54b7ea8f1c2b03e9a7d12",
  "lead_id": "0f2d3c1a-8b4e-4f6a-90d2-1a3b4c5d6e7f",
  "lead_created": true,
  "convo_id": "8c1a9d2e-3b4f-4a5e-b6c7-d8e9fa0b1c2d",
  "phone_line_id": "2a4b6c8d-0e1f-4a3b-8c5d-7e9f1a2b3c4d"
}
```

## Fields

| Field             | Required | Notes                                                                                                                                       |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `phone`           | Yes      | Recipient in E.164 format, for example `+14155551234`.                                                                                      |
| `body`            | Yes      | Text to send. Blank lines split into separate iMessage bubbles.                                                                             |
| `idempotency_key` | No       | Safe retry key. Reusing the same key and body returns the original response.                                                                |
| `name`            | No       | Optional lead display name.                                                                                                                 |
| `external_id`     | No       | Your CRM or application record id.                                                                                                          |
| `phone_line_id`   | No       | Send from a specific assigned sender line. If it differs from the current pin, Chert allows the send and re-pins future sends to that line. |
| `attachments`     | No       | Array of attachment references (see below).                                                                                                 |
| `effect`          | No       | Apple send-effect name (see [Effects](#effects)).                                                                                           |

## Attachments

`/send` accepts three reference shapes interchangeably. Upload first via [`POST /api/v1/attachments`](/api/attachments), then reference the returned `attachment_id`:

```jsonc theme={null}
{
  "phone": "+14155551234",
  "body": "See attached.",
  "attachments": [
    "att_abc123",                                     // bare id (primary form)
    { "id": "att_def456" },                           // alias
    { "attachment_id": "att_ghi789" },                // explicit
    { "attachment_id": "att_live_photo", "live_photo": true }  // HEIC + companion MOV pair
  ]
}
```

| Rule                                        | Detail                                                                                                                                       |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Mixing `url` + `attachment_id` in one entry | Rejected with `1011`; the response includes `attachment_index` so you know which entry to fix.                                               |
| URL refs on `/send`                         | Not accepted — `/send` rejects `{ "url": "..." }` references with `1011`. Use [`POST /api/v1/chats`](/api/chats/create) for URL-fetch flows. |
| `live_photo: true`                          | Pairs an uploaded HEIC with its companion MOV so the recipient gets a real Live Photo.                                                       |
| Malformed `attachments` array               | Returns `1002 INVALID_FIELD`.                                                                                                                |

## Effects

Set `"effect": "<name>"` to attach an Apple send-effect (the same fullscreen / bubble effects you get from Messages on iOS). Effects are whitelist-validated upstream — an unknown value returns `4098 UNKNOWN_EFFECT` with the full `allowed_effects` array in the error body, so callers can self-discover the current set.

```json theme={null}
{
  "phone": "+14155551234",
  "body": "Congrats on the round!",
  "effect": "celebration"
}
```

## Behavior

| Case                                   | What happens                                                                                                                    |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| First send to a recipient              | Chert creates a lead and pins a sender line.                                                                                    |
| Follow-up to the same recipient        | Chert reuses the pinned line by default. Passing `phone_line_id` can switch to another assigned sender line.                    |
| Duplicate body within the dedup window | Chert can return `duplicate` without sending again.                                                                             |
| Delivery failure                       | `/send` uses a legacy flat error shape (top-level `status`, `code`, `message`, `retryable`, `trace_id`). Branch on `retryable`. |

## Common errors

| Code   | When                                                                                                        |
| ------ | ----------------------------------------------------------------------------------------------------------- |
| `1002` | Malformed `attachments` array.                                                                              |
| `1011` | Attachment reference mixes `url` and `attachment_id`, or `url` ref on `/send`. Includes `attachment_index`. |
| `4002` | Phone lines saturated for this recipient.                                                                   |
| `4098` | Unknown effect; response carries `allowed_effects`.                                                         |
| `4099` | Feature not supported in this context.                                                                      |

See the full [error code reference](/api/errors).

## See also

* [Usage examples](/api/usage-examples)
* [Create a chat](/api/chats/create)
* [Create a group](/api/group-chats/create)
* [Attachments](/api/attachments)
* [Errors](/api/errors)