Messages

Send and receive SMS on a cell. MMS is not available yet (media_urls returns MMS_NOT_SUPPORTED).

Organization

Parent

Pod

Parent

Cell

This guide

Send

Use a stable Idempotency-Key (or client_id) whenever a request could be retried. AgentCell returns the original message instead of sending a duplicate.

await client.messages.send({
  cellId: cell.id,
  to: "+14155550144",
  body: "Hello from my agent",
  idempotencyKey: "send-hello-1",
});

SMS only

This release accepts SMS bodies only. Non-empty media_urls returns 400 MMS_NOT_SUPPORTED. GET …/media/{index} is not available. Voice, iMessage, and WhatsApp are later, like MMS. Send requires a numbered cell on the workspace (and on the pod when pod_id is set). No connected handset on the device WebSocket (and not sim) returns 503 CARRIER_UNAVAILABLE — simulation is e2e-only.

Required: to (E.164) and body
MMS, voice, iMessage, WhatsApp: later
CELL_NOT_READY / PHONE_NOT_ASSOCIATED if no number is assigned
CARRIER_UNAVAILABLE if no handset is on the device WebSocket

Inbound and reply

Subscribe to cell.message.received. Reply with POST /cells/{id}/messages/{message_id}/reply so the thread stays intact.

Idempotency

Pods, drafts, and cycle jobs use client_id. Cell create does not. Sends use the Idempotency-Key header (24h scope).

Idempotency reference

Common errors

IGNORED_RECIPIENT
Number is on the effective ignore list.
TCPA_QUIET_HOURS
Pod quiet hours blocked or deferred the send.
CELL_NOT_READY
Cell has no E.164 yet.
PHONE_NOT_ASSOCIATED
No phone on this workspace or pod.
CARRIER_UNAVAILABLE
Production fail-closed without a carrier.
CARRIER_REJECTED
The carrier refused the message.
RATE_LIMITED
Honor Retry-After and back off.

Copy for Cursor / Claude

Send with an idempotency key, then listen for cell.message.received.

curl -X POST https://api.agentcell.store/v1/cells/$CELL_ID/messages/send \
  -H "Authorization: Bearer $AGENTCELL_API_KEY" \
  -H "Idempotency-Key: send-hello-1" \
  -d '{"to":"+14155550144","body":"Hello from my agent"}'