# Scheduled Communications

Queue deferred emails, SMS, and AI voice calls for future dispatch. The communications_scheduler_tick cron (runs every minute) claims pending rows, enforces business-hours windows, retries with exponential backoff, and dispatches via the automation pipeline. Row lifecycle: pending -> dispatching -> dispatched | failed | cancelled | skipped.

**Base URL:** `https://api.trustpager.com/functions/v1/api/v1`

## Endpoints

### GET /scheduled-communications

List all scheduled communications for the company. Supports filtering by status, channel, and linked entity (contact, deal, customer). Paginated via cursor.

**Scopes:** `dispatcher:read` — [full detail](./scheduled-communications/get-scheduled-communications.md)

### POST /scheduled-communications

Schedule a future email, SMS, or AI voice call. Requires dispatcher:write PLUS a channel-specific scope (email:send, sms:send, or calls:initiate). The row is created with status="pending". The scheduler tick picks it up at or after scheduled_for. If respect_business_hours=true, the scheduler holds the row outside of the configured business window and re-schedules to the next window start in the callee's timezone.

**Scopes:** `dispatcher:write`, `email:send | sms:send | calls:initiate` — [full detail](./scheduled-communications/post-scheduled-communications.md)

### GET /scheduled-communications/:id

Retrieve a single scheduled communication by ID with full status, payload, and dispatch result (dispatched_external_id, dispatched_at, attempt_count, last_error).

**Scopes:** `dispatcher:read` — [full detail](./scheduled-communications/get-scheduled-communications-id.md)

### PATCH /scheduled-communications/:id

Update a pending scheduled communication. Only rows with status="pending" can be modified. Editable fields: scheduled_for, timezone, respect_business_hours, payload, cancel_policy. Returns a validation error if the row is not pending.

**Scopes:** `dispatcher:write` — [full detail](./scheduled-communications/patch-scheduled-communications-id.md)

### DELETE /scheduled-communications/:id

Soft-cancel a pending scheduled communication. Sets status to "cancelled". The row is retained for audit. Returns 204 No Content on success. Returns a validation error if the row is not pending.

**Scopes:** `dispatcher:write` — [full detail](./scheduled-communications/delete-scheduled-communications-id.md)

### POST /scheduled-communications/:id/dispatch-now

Flush a pending scheduled communication immediately. Sets scheduled_for to now and disables business-hours enforcement so the next scheduler tick (within 1 minute) picks it up. Only works on "pending" rows.

**Scopes:** `dispatcher:write` — [full detail](./scheduled-communications/post-scheduled-communications-id-dispatch-now.md)