Usage examples

These examples use bearer auth for readability. Use HMAC signing when a request should be signed instead of carrying the secret directly.

Send a first message

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?"}'

Send a native voice note

Stage an ordinary uncompressed WAV file, then send the returned voice_note_id through the exact phone_line_id returned by staging:

STAGED=$(curl --fail-with-body --silent --show-error \
  https://console.trychert.com/api/v1/voice-notes \
  -H "Authorization: Bearer $CHERT_SIGNING_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://cdn.example.com/audio/intro.wav",
    "mime_type": "audio/wav",
    "phone_line_id": "2a4b6c8d-0e1f-4a3b-8c5d-7e9f1a2b3c4d"
  }') || exit 1

VOICE_NOTE_ID=$(jq -er '.voice_note_id' <<<"$STAGED") || exit 1
PHONE_LINE_ID=$(jq -er '.phone_line_id' <<<"$STAGED") || exit 1

curl --fail-with-body --silent --show-error \
  https://console.trychert.com/api/v1/send \
  -H "Authorization: Bearer $CHERT_SIGNING_SECRET" \
  -H "Content-Type: application/json" \
  -d "$(jq -n \
    --arg phone '+14155551234' \
    --arg phone_line_id "$PHONE_LINE_ID" \
    --arg voice_note_id "$VOICE_NOTE_ID" \
    '{
      phone: $phone,
      phone_line_id: $phone_line_id,
      voice_note: {voice_note_id: $voice_note_id},
      idempotency_key: "voice-note-customer-127-001"
    }')"

Voice notes are not attachments[]. See Voice notes for server-side WAV-to-Opus-CAF conversion, inline base64, JavaScript, Python, expiry, and retry guidance. Callers do not need Apple audio tools.

Create a chat, then follow up

CHAT_ID=$(
  curl -s https://console.trychert.com/api/v1/chats \
    -H "Authorization: Bearer $CHERT_SIGNING_SECRET" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "+15555550100",
      "to": ["+14155551234"],
      "message": {
        "parts": [{ "type": "text", "value": "Hi Sam - got a minute?" }]
      }
    }' | jq -r '.chat.id'
)

curl -X POST "https://console.trychert.com/api/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer $CHERT_SIGNING_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "parts": [{ "type": "text", "value": "Following up here." }]
    }
  }'

Send a rich link

The rich_link part shape is the same on every Chert sender line.

curl -X POST "https://console.trychert.com/api/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer $CHERT_SIGNING_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "parts": [
        { "type": "text", "value": "Here is the review link." },
        { "type": "rich_link", "url": "https://example.com/review" }
      ]
    }
  }'

Send image, text, and a rich link

Use this follow-up endpoint for existing DMs and groups. For a new group, create the group with text first, then send this message after you have the chat.id.

curl -X POST "https://console.trychert.com/api/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer $CHERT_SIGNING_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "parts": [
        { "type": "media", "attachment_id": "att_review_image" },
        { "type": "text", "value": "Hi Marcus, this is Todd from Texas Prime Plumbing. I would really appreciate a Google review." },
        { "type": "rich_link", "url": "https://search.google.com/local/writereview?placeid=..." }
      ]
    }
  }'

Upload and send a file

UPLOAD=$(
  curl -s https://console.trychert.com/api/v1/attachments \
    -H "Authorization: Bearer $CHERT_SIGNING_SECRET" \
    -H "Content-Type: application/json" \
    -d '{"filename":"invoice.pdf","content_type":"application/pdf","size_bytes":204800}'
)

UPLOAD_URL=$(echo "$UPLOAD" | jq -r '.upload_url')
ATTACHMENT_ID=$(echo "$UPLOAD" | jq -r '.attachment_id')

curl -X PUT "$UPLOAD_URL" \
  -H "Authorization: Bearer $CHERT_SIGNING_SECRET" \
  -H "Content-Type: application/pdf" \
  --data-binary @invoice.pdf

curl -X POST "https://console.trychert.com/api/v1/chats/CHAT_ID/messages" \
  -H "Authorization: Bearer YOUR_SIGNING_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "parts": [
        { "type": "text",  "value": "See attached." },
        { "type": "media", "attachment_id": "att_abc..." }
      ]
    }
  }'

Send multiple images

Upload multiple images, then request grouped delivery from an existing chat.

curl -X POST "https://console.trychert.com/api/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer $CHERT_SIGNING_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "parallel_attachments": true,
    "message": {
      "parts": [
        { "type": "media", "attachment_id": "att_photo_1" },
        { "type": "media", "attachment_id": "att_photo_2" },
        { "type": "media", "attachment_id": "att_photo_3" },
        { "type": "media", "attachment_id": "att_photo_4" }
      ]
    }
  }'

Stream replies while developing

curl -N https://console.trychert.com/api/v1/events/stream \
  -H "Authorization: Bearer $CHERT_SIGNING_SECRET"

For production, create a webhook subscription and listen for message.received.

curl -X POST https://console.trychert.com/api/v1/webhook-subscriptions \
  -H "Authorization: Bearer $CHERT_SIGNING_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example/webhooks/chert",
    "events": ["message.received"]
  }'

Download an inbound voice memo

Read attachment_id from the attachment part in message.received, then use the authenticated content route. --remote-header-name preserves a useful filename from Content-Disposition when Chert has one:

: "${CHERT_ATTACHMENT_ID:?Set CHERT_ATTACHMENT_ID}"

curl --fail-with-body --silent --show-error \
  --remote-header-name --remote-name \
  "https://console.trychert.com/api/v1/attachments/$CHERT_ATTACHMENT_ID/content" \
  -H "Authorization: Bearer $CHERT_SIGNING_SECRET" \
  -H "x-chert-tenant: $CHERT_TENANT_SLUG"

file Audio_Message.caf
ffprobe -v error -show_streams -show_format Audio_Message.caf
ffmpeg -i Audio_Message.caf -ac 1 -ar 16000 voice-note.wav

The event may report application/octet-stream or omit a filename even when the downloaded bytes are valid audio. See Receiving inbound voice memos for TypeScript, Python, inspection, format variability, and transcription guidance.

React to a message

Use a message id from chat history or a message.received webhook.

curl -X POST "https://console.trychert.com/api/v1/messages/$MESSAGE_ID/react" \
  -H "Authorization: Bearer $CHERT_SIGNING_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"reaction":"like"}'

Get started

Messages

Chats

Group chats

Contact sharing

Webhooks and events

Reference

Usage examples

Send a first message

Send a native voice note

Create a chat, then follow up

Send a rich link

Send image, text, and a rich link

Upload and send a file

Send multiple images

Stream replies while developing

Download an inbound voice memo

React to a message

​Send a first message

​Send a native voice note

​Create a chat, then follow up

​Send a rich link

​Send image, text, and a rich link

​Upload and send a file

​Send multiple images

​Stream replies while developing

​Download an inbound voice memo

​React to a message

Send a first message

Send a native voice note

Create a chat, then follow up

Send a rich link

Send image, text, and a rich link

Upload and send a file

Send multiple images

Stream replies while developing

Download an inbound voice memo

React to a message