RESOURCE · CALLBACKS Callbacks.
A Callback is a single scheduled outbound attempt — a phone dial-back for voice agents, or an
outbound SMS for SMS agents. Callbacks belong to Chains: a chain is the sequence of
attempts for one caller's request, attempt 1 through N.
Voice and SMS share this resource. The endpoints and object shape below are
identical for both channels — what an attempt does is determined by the agent's
agentKind (voice dials,
sms_chat sends a message). So REDIAL NOW
re-sends for an SMS agent, and the voice-only outcome values
(voicemail, no_answer,
busy) never appear on SMS chains.
GET /v1/callbacks List callbacks with filters. Query parameters
- agent_id · scope to a single agent
- state · one of scheduled, claimed, calling, placed, failed, cancelled
- outcome · chain-wide; one of connected, voicemail, no_answer, busy, technical_error, conversation_silent
- from · ISO 8601; created_at ≥ from
- to · ISO 8601; created_at < to
- limit · integer 1-100, default 50
- cursor · opaque, from prior next_cursor
RESPONSE 200
{
"items": [
{
"id": "cb_a4f9c20a",
"workspace_id": "ws_a1b2c3",
"agent_id": "agent_30095cadfc4e3c87a310167c24",
"to_number": null,
"state": "scheduled",
"run_at": "2026-05-24T17:00:00Z",
"created_at": "2026-05-23T14:02:11Z",
"chain": {
"id": "chain_xyz9",
"attempt": 2,
"max_attempts": 3,
"is_final_attempt": false
},
"last_outcome": "voicemail",
"attempt_outcomes": ["voicemail"]
}
],
"next_cursor": "cb_b71eaa"
} Phone numbers are redacted on this endpoint — to_number
is always null in the list so a leaked callbacks:read
key can't bulk-harvest numbers. Fetch the number for a single callback via
/v1/callbacks/{id}/payload, which requires the
callbacks:read_pii scope and is rate-limited + audited.
GET /v1/callbacks/{id}/payload Get the decrypted provider trigger payload for a callback. Returns the payload that was (or will be) sent to the provider on the outbound redial. PII fields (to_number, from_number, dynamic_variables, metadata) are decrypted via the tenant DEK; when the callback is terminal those fields are zeroed at markTerminal time and the response sets pii_redacted: true with those fields null. Cross-tenant rows return 404 (not 403) to avoid leaking existence.
Requires the callbacks:read_pii scope — callbacks:read alone is rejected with 403. Each call writes an audit-log entry (action: callback.payload_accessed) capturing the api_key id, and per-key requests are capped at 60 / minute; bursts beyond that return 429 with a Retry-After header.
GET /v1/callbacks/{id} Get one callback by id, minimal non-PII shape. Returns the full callback row minus the encrypted PII columns (numbers, dynamic vars, metadata). Use /v1/callbacks/{id}/payload for those — that endpoint unwraps the tenant DEK. Cross-tenant ids return 404, not 403, to avoid leaking existence.
GET /v1/callbacks/{id}/chain Get the full chain this callback belongs to. Returns a chain summary (root id, chain_attempt sum, length, latest_state, max_attempts) plus an items array — every row that shares the same chain root, ordered by scheduled_at. The chain root is the first attempt; chain_root_id is null on that row and equals the root id on every subsequent attempt.
POST /v1/callbacks/{id}/redial REDIAL NOW. Fire this callback immediately, even if scheduled for later or inside quiet hours.
Returns 422 invalid_state if the callback is already in a terminal state (succeeded, failed_terminal, cancelled, expired) or already calling. The action is recorded in the audit log with the API key's creator as the actor.
POST /v1/callbacks/{id}/cancel Cancel a scheduled callback before it dials. Request body (required)
- reason · free-text, 3–500 chars; stored on the callback row and in the audit log
Returns 422 invalid_state if the callback has already dialed or is otherwise non-cancellable.