Voice Alarms

A Voice Alarm is a scheduled outbound voice campaign — a list of destinations, a from caller ID, an answer_url, and a schedule. TryVox dials each destination at the scheduled time, fetches VoxML from your answer_url to control the call, and tracks per-recipient outcomes.

Use cases: appointment reminders, dispatch alerts, daily check-ins, morning announcements to a fixed call list.

This is a higher-level surface than Make a Call. Use Make a Call for one-off, ad-hoc placements; use Voice Alarms when you have a recurring schedule and a fixed audience.

Endpoints

All endpoints are mounted under /v1/voice/account/{auth_id}/voice-alarms/... and authenticate with HTTP Basic.

Lifecycle

CREATE
  │
  ▼
pending  ─── scheduled_at reached ───►  active ───►  completed (one-shot)
  │                                       │
  │                                       └──────►  active again (next interval)
  ▼
cancelled (DELETE)        paused (POST /pause)

Create an alarm

POST /v1/voice/account/{auth_id}/voice-alarms

Request body

Example

curl -X POST https://api.tryvox.io/v1/voice/account/$TRYVOX_AUTH_ID/voice-alarms \
  -u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily on-call wakeup",
    "from": "+919876543210",
    "to": ["+14155551234", "+14155556789", "+14155559999"],
    "answer_url": "https://your-app.com/voice-alarm/answer",
    "scheduled_at": "2026-04-10T05:30:00Z",
    "repeat_interval": "daily",
    "max_retries": 2,
    "retry_interval": 120,
    "timeout_seconds": 25,
    "notify_emails": ["oncall-leads@example.com"]
  }'

Response

201 Created:

{
  "id": "8f7a4b2e-91c2-4f3d-9a1e-2c4b6d8f0a1c",
  "account_id": "TJab12cd34",
  "name": "Daily on-call wakeup",
  "from": "+919876543210",
  "to": ["+14155551234", "+14155556789", "+14155559999"],
  "answer_url": "https://your-app.com/voice-alarm/answer",
  "answer_method": "POST",
  "scheduled_at": "2026-04-10T05:30:00Z",
  "repeat_interval": "daily",
  "max_retries": 2,
  "retry_interval": 120,
  "timeout_seconds": 25,
  "status": "pending",
  "total_calls": 0,
  "completed_calls": 0,
  "failed_calls": 0,
  "next_run_at": "2026-04-10T05:30:00Z",
  "notify_emails": ["oncall-leads@example.com"],
  "created_at": "2026-04-09T10:30:00Z"
}

List alarms

GET /v1/voice/account/{auth_id}/voice-alarms

curl -u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKEN \
  https://api.tryvox.io/v1/voice/account/$TRYVOX_AUTH_ID/voice-alarms

Returns 200 OK with an array of alarms scoped to this account.

Update an alarm

PUT /v1/voice/account/{auth_id}/voice-alarms/{id}

PATCH-style: only fields you submit are applied. Most useful: changing to, rescheduling via scheduled_at, or flipping status to paused / active.

curl -X PUT https://api.tryvox.io/v1/voice/account/$TRYVOX_AUTH_ID/voice-alarms/$ALARM_ID \
  -u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"to": ["+14155551234", "+14155556789"]}'

Returns 200 OK with the updated alarm.

Pause / Resume

POST /v1/voice/account/{auth_id}/voice-alarms/{id}/pause
POST /v1/voice/account/{auth_id}/voice-alarms/{id}/resume

Pause sets status: "paused" and skips upcoming scheduled_at triggers. Resume reverts to pending (or active if a run is overdue and starts immediately).

curl -X POST \
  -u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKEN \
  https://api.tryvox.io/v1/voice/account/$TRYVOX_AUTH_ID/voice-alarms/$ALARM_ID/pause

204 No Content.

Delete

DELETE /v1/voice/account/{auth_id}/voice-alarms/{id}

204 No Content. The alarm flips to cancelled immediately. In-flight legs from the current run continue; no future runs.

Per-run behaviour

When scheduled_at is reached:

1. Status flips from pending to active.
2. TryVox places one outbound call per entry in to, in parallel up to a per-tenant concurrency cap.
3. Each leg fetches VoxML from answer_url when answered. The from number must be a verified caller ID — the alarm fails its run if it isn't (you'll see a validation_failed entry on the email summary).
4. Per-leg failures are retried up to max_retries with retry_interval between attempts.
5. After all legs complete (or exhaust retries), counters update:
   • total_calls += len(to)
   • completed_calls += successful legs
   • failed_calls += legs that exhausted retries
6. For recurring alarms, next_run_at is set to the next interval boundary. For once, status flips to completed.

Errors

Notes

• The from requirement is real. A single rejected leg won't pause the alarm, but if every leg has the same from and it's not verified, the whole run fails. Verify before scheduling.
• scheduled_at is UTC. Don't pass a local time without offset — it's parsed strictly.
• Per-tenant concurrency caps the parallelism within a run. Large to lists fan out in batches; the run isn't atomic.
• No partial-list retries. If a single leg fails after max_retries, you can't retry just that one — re-run the alarm by updating scheduled_at to a near-future time, or fall back to Make a Call for the missed numbers.
• Email summaries are best-effort, sent through the Notifications email service.