Scheduled Events

Documentation Index

Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt

Use this file to discover all available pages before exploring further.

• Outbound appointment reminders, follow-ups, and renewal calls.
• After-hours callbacks scheduled by an inbound assistant.
• Automated SMS confirmations queued from a workflow.
• Re-attempting a missed call on a configurable interval until it connects.

​

How it works

1. pending — the event has been created and is waiting for its scheduled time.
2. in_progress — the executor has dispatched the call or SMS to Telnyx.
3. completed — the recipient was reached (call answered and ended normally, or SMS delivered).
4. failed — the event could not be completed and no further attempts will be made.

​

Configuring retries for external failures

​

Validation rules

• retry_interval_secs must be in the range 60–86400 (1 minute to 24 hours).
• max_retries_client_errors must be in the range 0–10.
• If max_retries_client_errors > 0, retry_interval_secs must also be set.
• retry_interval_secs is only meaningful when max_retries_client_errors > 0 — supplying one without the other returns a 400.
• Both fields must be omitted (or 0 / null) for sms_chat events.

​

How retries are scheduled

• A new CallAttempt record is appended to the event’s call_attempts array.
• scheduled_at_fixed_datetime is advanced to now + retry_interval_secs (not the original time + interval — the clock starts when the previous attempt’s terminal status is received).
• status returns to pending and the executor will pick the event up again on its next sweep.

​

Total attempts

• max_retries_client_errors: 0 → 1 total attempt (no retries).
• max_retries_client_errors: 3 → up to 4 total attempts.
• max_retries_client_errors: 10 → up to 11 total attempts.

​

Inspecting attempt history

{
  "scheduled_event_id": "8f3c…",
  "telnyx_conversation_channel": "phone_call",
  "status": "pending",
  "max_retries_client_errors": 3,
  "retry_interval_secs": 300,
  "call_attempts": [
    {
      "attempt_number": 1,
      "attempted_at": "2026-05-07T14:30:02.812Z",
      "call_status": "no-answer",
      "call_duration": null,
      "telnyx_call_control_id": "v3:abc…"
    },
    {
      "attempt_number": 2,
      "attempted_at": "2026-05-07T14:35:08.114Z",
      "call_status": "busy",
      "call_duration": null,
      "telnyx_call_control_id": "v3:def…"
    }
  ]
}

​

API reference

​

Create-event fields

​

Examples

​

Schedule a phone call with retries on busy / no-answer

curl -L 'https://api.telnyx.com/v2/ai/assistants/{assistant_id}/scheduled_events' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <TOKEN>' \
  --data-raw '{
    "telnyx_conversation_channel": "phone_call",
    "telnyx_end_user_target": "+15551234567",
    "telnyx_agent_target": "+15553456789",
    "scheduled_at_fixed_datetime": "2026-05-08T15:00:00Z",
    "max_retries_client_errors": 3,
    "retry_interval_secs": 300,
    "conversation_metadata": {
      "campaign": "renewal-q2",
      "customer_id": "cust_42"
    }
  }'

​

Schedule a phone call without retries

curl -L 'https://api.telnyx.com/v2/ai/assistants/{assistant_id}/scheduled_events' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <TOKEN>' \
  --data-raw '{
    "telnyx_conversation_channel": "phone_call",
    "telnyx_end_user_target": "+15551234567",
    "telnyx_agent_target": "+15553456789",
    "scheduled_at_fixed_datetime": "2026-05-08T15:00:00Z"
  }'

​

Schedule an SMS

curl -L 'https://api.telnyx.com/v2/ai/assistants/{assistant_id}/scheduled_events' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <TOKEN>' \
  --data-raw '{
    "telnyx_conversation_channel": "sms_chat",
    "telnyx_end_user_target": "+15551234567",
    "telnyx_agent_target": "+15553456789",
    "scheduled_at_fixed_datetime": "2026-05-08T15:00:00Z",
    "text": "Hi! This is a reminder about your appointment tomorrow at 10 AM."
  }'

​

Inspect retry history

curl -L 'https://api.telnyx.com/v2/ai/assistants/{assistant_id}/scheduled_events/{event_id}' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <TOKEN>'

​

Cancel a pending event

curl -X DELETE 'https://api.telnyx.com/v2/ai/assistants/{assistant_id}/scheduled_events/{event_id}' \
  -H 'Authorization: Bearer <TOKEN>'

​

Choosing a retry policy

• Short intervals (60–300s) suit time-sensitive flows where the recipient is likely to be near their phone — verification calls, urgent reminders. They burn the retry budget quickly, which is sometimes what you want.
• Medium intervals (5–30 minutes) are a good default for outreach campaigns. Long enough that a busy recipient may finish their previous call; short enough that the event still completes within an hour.
• Long intervals (1–24 hours) match daily-cadence flows: missed bill reminders, callback queues, abandoned-cart nudges.
• Total reach time = max_retries_client_errors × retry_interval_secs. Make sure that span fits inside the time window when calling is acceptable for your use case (and your jurisdiction’s calling-hour rules).
• Higher max_retries_client_errors is not always better — at some point the recipient is unlikely to answer regardless of how many times you try. Three to five retries is usually plenty.

​

Related resources

• Voice AI Assistant API Reference — Full assistant configuration.
• No-Code Voice Assistant — Get started with Voice AI Assistants in the Portal.
• Dynamic Variables — Pass per-event context into the assistant prompt.
• Voicemail Detection on Transfer — Handle voicemail on transferred calls (a separate but related feature for live calls).