Sending

Use /send when you only need to send a 1:1 text message to a phone number or Apple ID email handle. Use Create a chat when you need a durable chat.id, attachments by URL, or chat history. Use Create a group for group chats.

Request

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

{
  "status": "sent",
  "message_id": "46eb1003c8b54b7ea8f1c2b03e9a7d12",
  "lead_id": "0f2d3c1a-8b4e-4f6a-90d2-1a3b4c5d6e7f",
  "chat_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 phone or Apple ID email handle. E.164 is preferred for phones; common US formatting is normalized. Email handles such as `user@icloud.com` are lowercased. The field remains named `phone` for compatibility.
`body`	Yes	Text to send. Blank lines split into separate iMessage bubbles — see Message text & line breaks.
`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).

Message text & line breaks

Input	Result
Single newline (`\n`)	Stays inside one iMessage bubble.
Blank line (two consecutive newlines)	Splits the text into separate iMessage bubbles.
Windows-style `\r\n` or bare `\r`	Always normalized to `\n` before splitting.
Literal escaped `\n` tokens	Converted to real line breaks only when the text contains no real newlines and includes an escaped blank-line pair (`\n\n`) — the signature of double-encoded JSON. Otherwise backslash sequences (file paths, regexes) pass through untouched.

Responses and message history echo the normalized text, not the raw bytes you sent. The same rules apply to body here and to text parts[].value on the chat routes.

Attachments

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

{
  "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` 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.

{
  "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.
Apple ID email recipient	Uses the same healthy assigned or pinned sender line selection as a phone recipient.
Follow-up through chat routes	Use `chat_id` from this response as `{id}` in `/api/v1/chats/{id}/messages`. `lead_id` is the same id; `convo_id` is lower-level conversation storage.
Duplicate body within the dedup window	Chert can return `duplicate` without sending again.
URL in `body`	Chert attempts a rich preview bubble where the sender line supports it. If a rich preview cannot be generated, the URL may be delivered as plain text.
Delivery failure	`/send` uses a legacy flat error shape — see Delivery failures. Branch on `retryable`.

Delivery failures

/send does not use the enveloped { success, error, trace_id } shape documented in Errors. Failures return a flat object:

{
  "status": "failed",
  "error": "send_failed",
  "code": 4001,
  "reason": "recipient is not reachable on iMessage",
  "retryable": true,
  "lead_id": "0f2d3c1a-8b4e-4f6a-90d2-1a3b4c5d6e7f",
  "chat_id": "0f2d3c1a-8b4e-4f6a-90d2-1a3b4c5d6e7f",
  "convo_id": "8c1a9d2e-3b4f-4a5e-b6c7-d8e9fa0b1c2d"
}

Field	Notes
`status`	Always `"failed"` on a failure.
`error`	Always the string `"send_failed"` — a stable legacy anchor.
`code`	Numeric Chert error code from the error code registry.
`reason`	`4xx` failures only. Human-readable failure detail.
`message`	`5xx` failures only. A generic description replaces `reason` (and the ids below); the full detail is logged server-side.
`retryable`	Authoritative retry signal — branch on this.
`lead_id` / `chat_id` / `convo_id`	`4xx` delivery failures include the ids of the lead/chat the send targeted, so you can follow up through chat routes.

/send failure responses do not carry a trace_id. The enveloped { success: false, error: {...}, trace_id } shape belongs to the other /api/v1 routes.

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.

Get started

Messages

Chats

Group chats

Contact sharing

Webhooks and events

Reference

Request

Response

Fields

Message text & line breaks

Attachments

Effects

Behavior

Delivery failures

Common errors

See also

​Request

​Response

​Fields

​Message text & line breaks

​Attachments

​Effects

​Behavior

​Delivery failures

​Common errors

​See also

Request

Response

Fields

Message text & line breaks

Attachments

Effects

Behavior

Delivery failures

Common errors

See also