Skip to main content
Use /send when you only need to send a 1:1 text message to a phone number. 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",
  "lead_created": true,
  "convo_id": "8c1a9d2e-3b4f-4a5e-b6c7-d8e9fa0b1c2d",
  "phone_line_id": "2a4b6c8d-0e1f-4a3b-8c5d-7e9f1a2b3c4d"
}

​
Fields

FieldRequiredNotes
phoneYesRecipient in E.164 format, for example +14155551234.
bodyYesText to send. Blank lines split into separate iMessage bubbles.
idempotency_keyNoSafe retry key. Reusing the same key and body returns the original response.
nameNoOptional lead display name.
external_idNoYour CRM or application record id.
phone_line_idNoSend 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.
attachmentsNoArray of attachment references (see below).
effectNoApple send-effect name (see Effects).

​
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
  ]
}
RuleDetail
Mixing url + attachment_id in one entryRejected with 1011; the response includes attachment_index so you know which entry to fix.
URL refs on /sendNot accepted — /send rejects { "url": "..." } references with 1011. Use POST /api/v1/chats for URL-fetch flows.
live_photo: truePairs an uploaded HEIC with its companion MOV so the recipient gets a real Live Photo.
Malformed attachments arrayReturns 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

CaseWhat happens
First send to a recipientChert creates a lead and pins a sender line.
Follow-up to the same recipientChert reuses the pinned line by default. Passing phone_line_id can switch to another assigned sender line.
Duplicate body within the dedup windowChert 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

CodeWhen
1002Malformed attachments array.
1011Attachment reference mixes url and attachment_id, or url ref on /send. Includes attachment_index.
4002Phone lines saturated for this recipient.
4098Unknown effect; response carries allowed_effects.
4099Feature not supported in this context.
See the full error code reference.

​
See also