Receiving replies

When a lead replies from either a phone number or Apple ID email handle, Chert creates or matches the tenant-scoped chat and delivers a real-time message.received event to your webhook subscriptions. Events are durable, signed, and replayable.

Event type	When it fires	Latency	Use when
`message.received`	Real-time on every inbound iMessage	Seconds	Building a live agent or chat UI. Recommended default.

Subscribe by passing events: ["message.received"] on POST /api/v1/webhook-subscriptions.

Configuring a webhook

Two options:

Console — your Chert administrator configures a webhook endpoint for your tenant.
API — create a subscription programmatically with POST /api/v1/webhook-subscriptions. See Webhook subscriptions.

The webhook subscription secret is independent from your API signing_secret — rotate either without touching the other. If you cannot expose a public URL during development, use the SSE stream or dev inbox instead.

`message.received` envelope

Real-time, fires immediately when an inbound iMessage lands.

message.received

{
  "event_id": "chert:msg:7b7f4a1cc9d54809a1e4f1b2",
  "created_at": "2026-05-24T01:35:34.000Z",
  "api_version": "v1",
  "webhook_version": "2026-05-04",
  "event_type": "message.received",
  "trace_id": "...",
  "partner_id": "<your-tenant-slug>",
  "data": {
    "chat": {
      "id": "17f6e9ed-...",
      "is_group": false,
      "handles": [
        { "handle": "+14152165723", "service": "imessage", "is_me": true },
        { "handle": "+14155551234", "service": "imessage", "is_me": false }
      ],
      "owner_handle": { "handle": "+14152165723", "service": "imessage", "is_me": true }
    },
    "message": {
      "id": "0D36042D-C551-4CB4-9BE7-853832D6F2FE",
      "direction": "inbound",
      "sender_handle": { "handle": "+14155551234", "service": "imessage", "is_me": false },
      "parts": [
        { "type": "text", "value": "Sure, what time?" },
        {
          "type": "media",
          "attachment_id": "in_536f2fe3cafef93946d0bf9b4ac2e3ef",
          "filename": "photo.jpg",
          "mime_type": "image/jpeg",
          "size_bytes": 790394
        }
      ],
      "sent_at": "2026-05-24T01:35:34.000Z",
      "delivered_at": null,
      "read_at": null,
      "service": "imessage"
    },
    "crm_deep_link": "https://console.trychert.com/?lead=17f6e9ed-..."
  }
}

Field map

You want	Path
Event type	`event_type` (also in the `X-Webhook-Event` header)
Event identity and idempotency key	`event_id` (also in `X-Webhook-Event-Id`)
Chat id (use with `/chats/{id}/...` endpoints)	`data.chat.id`
Tenant slug	`partner_id`
Sender phone or Apple ID email	`data.message.sender_handle.handle`
Your line phone	`data.chat.owner_handle.handle`
Chat handles / participants	`data.chat.handles`
Inbound text	`data.message.parts.find(p => p.type === "text").value`
Inbound attachment metadata	`data.message.parts.filter(p => p.type === "media")`
Inbound attachment bytes	`GET /api/v1/attachments/{attachment_id}/content`
Inbound message id — valid input to `/messages/{id}/react`	`data.message.id`
Sender line	`data.chat.owner_handle.handle`
Group flag	`data.chat.is_group`

Compat note. Some legacy deliveries also include top-level from, to, text, message_guid, and line_id aliases. New integrations should prefer the data.* paths because they are richer and consistent across Chert-managed lines.

Receiving images and attachments

Inbound media is handled by the Chert API layer automatically. When a lead sends an image, recording, or file, data.message.parts[] carries an attachment part. A fetchable part includes attachment_id; filename, mime_type, and size_bytes are metadata hints and may be absent or generic. Fetch the bytes with the same tenant auth you use for other API calls:

ATTACHMENT_ID="in_536f2fe3cafef93946d0bf9b4ac2e3ef"

curl "https://console.trychert.com/api/v1/attachments/$ATTACHMENT_ID/content" \
  -H "Authorization: Bearer $SECRET" \
  -H "x-chert-tenant: $SLUG" \
  --output photo.jpg

The attachment id is tenant-scoped. If an inbound contains both text and media, keep the array order from data.message.parts[] when reconstructing the message.

Receiving inbound voice memos

There is no separate inbound voice-note endpoint. An Apple voice memo arrives through the normal message.received workflow and is retrieved through the same authenticated attachment-content route as other inbound media. The following representative event reflects a verified case where the event contained a generic MIME type and no filename:

message.received voice memo

{
  "api_version": "v1",
  "webhook_version": "2026-05-04",
  "event_type": "message.received",
  "event_id": "EVENT_ID",
  "created_at": "2026-08-25T14:30:00.000Z",
  "trace_id": "TRACE_ID",
  "partner_id": "TENANT_SLUG",
  "data": {
    "chat": {
      "id": "CHAT_ID",
      "is_group": false,
      "handles": [
        { "handle": "PHONE_LINE_HANDLE", "service": "imessage", "is_me": true },
        { "handle": "SENDER_HANDLE", "service": "imessage", "is_me": false }
      ],
      "owner_handle": {
        "handle": "PHONE_LINE_HANDLE",
        "service": "imessage",
        "is_me": true
      }
    },
    "message": {
      "id": "MESSAGE_ID",
      "direction": "inbound",
      "sender_handle": {
        "handle": "SENDER_HANDLE",
        "service": "imessage",
        "is_me": false
      },
      "parts": [
        {
          "type": "media",
          "attachment_id": "ATTACHMENT_ID",
          "mime_type": "application/octet-stream"
        }
      ],
      "sent_at": "2026-08-25T14:29:58.000Z",
      "delivered_at": null,
      "read_at": null,
      "service": "imessage"
    },
    "crm_deep_link": null
  }
}

The event may describe an inbound recording as media or another attachment-like part. Chert does not currently expose a universal provenance flag that proves an audio attachment originated from Apple’s native voice memo UI. Use attachment_id to retrieve it, then inspect the response and bytes.

Download with cURL

Bearer or HMAC authentication is required. For multi-tenant accounts, include x-chert-tenant; default single-tenant bearer requests may omit it.

: "${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"

--remote-header-name tells cURL to use the filename from Content-Disposition. In the verified case, the response included headers equivalent to:

Content-Type: application/octet-stream
Content-Disposition: attachment; filename="Audio_Message.caf"

The generic Content-Type did not make the audio invalid. The downloaded bytes were a playable CAF container with Opus audio.

Download with TypeScript

import { writeFile } from "node:fs/promises"
import { basename } from "node:path"

const secret = process.env.CHERT_SIGNING_SECRET
const attachmentId = process.env.CHERT_ATTACHMENT_ID
if (!secret || !attachmentId) {
  throw new Error("CHERT_SIGNING_SECRET and CHERT_ATTACHMENT_ID are required")
}

const headers: Record<string, string> = {
  Authorization: `Bearer ${secret}`,
}
if (process.env.CHERT_TENANT_SLUG) {
  headers["x-chert-tenant"] = process.env.CHERT_TENANT_SLUG
}

const response = await fetch(
  `https://console.trychert.com/api/v1/attachments/${encodeURIComponent(attachmentId)}/content`,
  { headers },
)
if (!response.ok) {
  throw new Error(`Attachment download failed with HTTP ${response.status}`)
}

const disposition = response.headers.get("content-disposition") ?? ""
const match = /filename="?([^";]+)"?/i.exec(disposition)
const filename = basename(match?.[1] ?? "inbound-voice-note.bin")
const bytes = Buffer.from(await response.arrayBuffer())
await writeFile(filename, bytes)

console.log({
  filename,
  contentType: response.headers.get("content-type"),
  sizeBytes: bytes.byteLength,
})

Download with Python

import os
import re
from pathlib import Path

import requests

secret = os.environ["CHERT_SIGNING_SECRET"]
attachment_id = os.environ["CHERT_ATTACHMENT_ID"]
headers = {"Authorization": f"Bearer {secret}"}
if os.environ.get("CHERT_TENANT_SLUG"):
    headers["x-chert-tenant"] = os.environ["CHERT_TENANT_SLUG"]

response = requests.get(
    f"https://console.trychert.com/api/v1/attachments/{attachment_id}/content",
    headers=headers,
    timeout=60,
)
response.raise_for_status()

disposition = response.headers.get("Content-Disposition", "")
match = re.search(r'filename="?([^";]+)"?', disposition, re.IGNORECASE)
filename = Path(match.group(1) if match else "inbound-voice-note.bin").name
Path(filename).write_bytes(response.content)

print({
    "filename": filename,
    "content_type": response.headers.get("Content-Type"),
    "size_bytes": len(response.content),
})

Inspect and convert the audio

Inspect the file signature and stream metadata instead of trusting only the webhook MIME type:

file Audio_Message.caf

ffprobe -v error \
  -show_entries format=format_name,duration,bit_rate:stream=codec_name,sample_rate,channels \
  -of default=noprint_wrappers=1 \
  Audio_Message.caf

One verified sample was Apple CAF/Core Audio Format (caff) containing mono Opus audio, approximately four seconds long at about 32 kbps. Apple inspection reported 24 kHz Opus while FFmpeg exposed the decoded stream at 48 kHz. Do not assume every Apple device or OS version produces this exact combination. Convert CAF/Opus to a mono 16 kHz WAV for tools that do not accept the original container or codec:

ffmpeg -i Audio_Message.caf -ac 1 -ar 16000 voice-note.wav

Chert preserves the downloaded recording; it does not automatically convert inbound audio to MP3 or WAV. No transcript field is currently returned, and Chert does not perform automatic speech-to-text or semantic interpretation. Applications that need a transcript must send the downloaded audio to their chosen speech-to-text system.

Replying

Two working paths. Pick by what you need:

# Plain reply — phone-addressed, no chat-id lookup needed
curl -X POST https://console.trychert.com/api/v1/send \
  -H "Authorization: Bearer $SECRET" -H "x-chert-tenant: $SLUG" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+14155551234", "body": "Yes, works for me" }'

# Chat-addressed reply — required for media parts, typing indicators, and contact cards
curl -X POST https://console.trychert.com/api/v1/chats/$CHAT_ID/messages \
  -H "Authorization: Bearer $SECRET" -H "x-chert-tenant: $SLUG" \
  -H "Content-Type: application/json" \
  -d '{ "message": { "parts": [{ "type": "text", "value": "Yes, works for me" }] } }'

$CHAT_ID is data.chat.id from the webhook. $MESSAGE_GUID is message_guid (or data.message.id) and can be used for tapbacks with /messages/{id}/react. Use a normal chat follow-up for replies.

Headers

These headers are sent by Chert to your webhook endpoint during event delivery. Do not send x-chert-tenant in your webhook receiver — that header is only for requests your application makes to Chert APIs.

Recommended webhook delivery headers

Header	Format	Description
`X-Webhook-Event`	string	Event type, e.g. `message.received`.
`X-Webhook-Event-Id`	string	Stable identifier. Use as a dedup key.
`X-Webhook-Timestamp`	unix seconds	Timestamp used in the signature payload.
`X-Webhook-Subscription-Id`	string	Id of the subscription that triggered this delivery.
`X-Webhook-Signature`	`t=<ts>,v1=<hex>`	HMAC signature computed with the subscription secret.
`content-type`	`application/json`	Always `application/json`.

Legacy compatibility headers

Chert also emits these older lowercase headers for existing integrations. New integrations should read the recommended X-Webhook-* headers above.

Header	Format	Description
`x-chert-event`	string	Same event type as `X-Webhook-Event`.
`x-chert-event-id`	string	Same dedup key as `X-Webhook-Event-Id`.
`x-chert-timestamp`	unix seconds	Same timestamp as `X-Webhook-Timestamp`.
`x-chert-signature`	`v1,<ts>,<hex>`	Legacy HMAC signature format.

Both signature formats compute the same HMAC: HMAC-SHA256(subscription_secret, "<ts>.<raw_body>").

Verifying the signature

Compute the HMAC over the raw request body (exact bytes as received) and compare with constant-time equality. Do not parse and re-serialize the JSON before verifying.

import { createHmac, timingSafeEqual } from "node:crypto"

// Handles both x-chert-signature (v1,<ts>,<hex>)
// and X-Webhook-Signature (t=<ts>,v1=<hex>).
export function verify(rawBody, header, secret) {
  let ts, hex
  const legacy = /^v1,(\d+),([a-f0-9]+)$/i.exec(header || "")
  const modern  = /^t=(\d+),v1=([a-f0-9]+)$/i.exec(header || "")
  if (legacy)      { [, ts, hex] = legacy }
  else if (modern) { [, ts, hex] = modern }
  else return false

  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false
  const expected = createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex")
  const a = Buffer.from(hex, "hex")
  const b = Buffer.from(expected, "hex")
  return a.length === b.length && timingSafeEqual(a, b)
}

import hmac, hashlib, re, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    legacy = re.match(r"^v1,(\d+),([a-f0-9]+)$", header or "")
    modern = re.match(r"^t=(\d+),v1=([a-f0-9]+)$", header or "")
    m = legacy or modern
    if not m: return False
    ts, hex_ = m.group(1), m.group(2)
    if abs(time.time() - int(ts)) > 300: return False
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(hex_, expected)

# Extract ts and hex from x-chert-signature: v1,<ts>,<hex>
EXPECTED=$(printf "%s.%s" "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SUBSCRIPTION_SECRET" -hex | awk '{print $2}')
[ "$EXPECTED" = "$HEX_FROM_HEADER" ] && echo "ok" || echo "mismatch"

Reject any request that fails verification with 401.

Retry behavior

Response from your endpoint	Chert action
`2xx`	Marked delivered.
`5xx` or network error	Up to 3 total delivery attempts with short exponential backoff.
`4xx`	Not retried during that delivery. Marked failed if no matching destination succeeds.

Failed events may be retried later by Chert. Pull events through GET /api/v1/events and replay manually after fixing your endpoint.

At-least-once semantics

You may receive the same event more than once during retries, replays, or attachment-metadata repairs. Use event_id (also exposed in the X-Webhook-Event-Id header) to make side effects idempotent, but merge a redelivery when it contains richer attachment or group metadata.

const completedSideEffects = new Set()

function handle(event) {
  upsertMessage(event.data.message) // Merge newly supplied metadata.

  if (!completedSideEffects.has(event.event_id)) {
    runSideEffects(event)
    completedSideEffects.add(event.event_id)
  }
}

Replaying missed events

If your endpoint was down, list events with delivery.status = failed and replay them:

curl https://console.trychert.com/api/v1/events?status=failed \
  -H "x-chert-tenant: $SLUG" -H "authorization: Bearer $SECRET"

curl -X POST https://console.trychert.com/api/v1/events/{id}/replay \
  -H "x-chert-tenant: $SLUG" -H "authorization: Bearer $SECRET"

To replay to one subscription instead of every matching active subscription, add ?subscription_id=<subscription_id>. See Events for the full debugging surface.

Get started

Messages

Chats

Group chats

Contact sharing

Webhooks and events

Reference

Receiving replies

Configuring a webhook

`message.received` envelope

Field map

Receiving images and attachments

Receiving inbound voice memos

Download with cURL

Download with TypeScript

Download with Python

Inspect and convert the audio

Replying

Headers

Recommended webhook delivery headers

Legacy compatibility headers

Verifying the signature

Retry behavior

At-least-once semantics

Replaying missed events

See also

​Configuring a webhook

​message.received envelope

​Field map

​Receiving images and attachments

​Receiving inbound voice memos

​Download with cURL

​Download with TypeScript

​Download with Python

​Inspect and convert the audio

​Replying

​Headers

​Recommended webhook delivery headers

​Legacy compatibility headers

​Verifying the signature

​Retry behavior

​At-least-once semantics

​Replaying missed events

​See also

Configuring a webhook

`message.received` envelope

Field map

Receiving images and attachments

Receiving inbound voice memos

Download with cURL

Download with TypeScript

Download with Python

Inspect and convert the audio

Replying

Headers

Recommended webhook delivery headers

Legacy compatibility headers

Verifying the signature

Retry behavior

At-least-once semantics

Replaying missed events

See also