---
title: "Create a scheduled event"
method: POST
path: "/ai/assistants/{assistant_id}/scheduled_events"
tags: ["Assistants"]
---

# Create a scheduled event

`POST /ai/assistants/{assistant_id}/scheduled_events`

Create a scheduled event for an assistant

## Path parameters

- `assistant_id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- CreateScheduledEventRequest
  - `telnyx_conversation_channel` 'phone_call' | 'sms_chat', required
  - `telnyx_end_user_target` string, required — The phone number, SIP URI, to schedule the call or text to.
  - `telnyx_agent_target` string, required — The phone number, SIP URI, to schedule the call or text from.
  - `scheduled_at_fixed_datetime` string, date-time, required — The datetime at which the event should be scheduled. Formatted as ISO 8601.
  - `text` string — Required for sms scheduled events. The text to be sent to the end user.
  - `conversation_metadata` object — Metadata associated with the conversation. Telnyx provides several pieces of metadata, but customers can also add their own.
  - `dynamic_variables` object — A map of dynamic variable names to values. These variables can be referenced in the assistant's instructions and messages using {{variable_name}} syntax.
  - `max_retries_client_errors` integer — Configure number of retries on client errors: busy, no-answer, failed, canceled (caller hung up before the callee answered)
  - `retry_interval_secs` integer
  - `call_settings` ScheduledCallSettings — Per-call telephony overrides applied when a scheduled phone-call event dispatches. Phone-call events only. New per-call dispatch options should be added here rather than as top-level event fields.
    - `sip_region` 'US' | 'Europe' | 'Canada' | 'Australia' | 'Middle East' — SIP region passed to Telnyx when initiating an outbound call. Values match the Telnyx TeXML `SipRegion` parameter exactly. Telnyx defaults to `US` when omitted.

## Response `201`

Successful Response

- union — Union type for different scheduled event response types
  - ScheduledPhoneCallEventResponse
    - `telnyx_conversation_channel` 'phone_call' | 'sms_chat', required
    - `telnyx_end_user_target` string, required
    - `telnyx_agent_target` string, required
    - `scheduled_at_fixed_datetime` string, date-time, required
    - `assistant_id` string, required
    - `retry_count` integer
    - `retry_attempts` integer
    - `scheduled_event_id` string
    - `conversation_id` string
    - `created_at` string, date-time
    - `status` 'pending' | 'in_progress' | 'completed' | 'failed'
    - `conversation_metadata` object
    - `dynamic_variables` object — A map of dynamic variable names to values. These variables can be referenced in the assistant's instructions and messages using {{variable_name}} syntax.
    - `errors` string[]
    - `call_status` string — Values: busy, canceled, no-answer, ringing, completed, failed, in-progress
    - `call_duration` integer — Duration of the call in seconds
    - `max_retries_client_errors` integer — Configure number of retries on client errors: busy, no-answer, failed, canceled (caller hung up before the callee answered)
    - `retry_interval_secs` integer
    - `call_attempts` AssistantScheduledCallAttempt[]
      - `attempt_number` integer, required
      - `attempted_at` string, date-time, required
      - `call_status` string, required — Values: busy, canceled, no-answer, ringing, completed, failed, in-progress
      - `call_duration` integer — Duration of the call in seconds
      - `telnyx_call_control_id` string
    - `dispatched_at` string, date-time — Date time at which call was sent
    - `call_settings` ScheduledCallSettings — Per-call telephony overrides applied when a scheduled phone-call event dispatches. Phone-call events only. New per-call dispatch options should be added here rather than as top-level event fields.
      - `sip_region` 'US' | 'Europe' | 'Canada' | 'Australia' | 'Middle East' — SIP region passed to Telnyx when initiating an outbound call. Values match the Telnyx TeXML `SipRegion` parameter exactly. Telnyx defaults to `US` when omitted.
  - ScheduledSmsEventResponse
    - `telnyx_conversation_channel` 'phone_call' | 'sms_chat', required
    - `telnyx_end_user_target` string, required
    - `telnyx_agent_target` string, required
    - `scheduled_at_fixed_datetime` string, date-time, required
    - `assistant_id` string, required
    - `retry_count` integer
    - `text` string, required
    - `scheduled_event_id` string
    - `conversation_id` string
    - `created_at` string, date-time
    - `status` 'pending' | 'in_progress' | 'completed' | 'failed'
    - `conversation_metadata` object
    - `dynamic_variables` object — A map of dynamic variable names to values. These variables can be referenced in the assistant's instructions and messages using {{variable_name}} syntax.
    - `errors` string[]

## Other responses

- `400` — Bad Request / Validation Failed (10015). Invalid, duplicate, empty, malformed, or overlong Idempotency-Key headers are rejected by Edge with HTTP 400 and error code 10015.
- `409` — A request with the same Idempotency-Key is still being processed (10036). Retry later with the same key and request.
- `413` — Payload Too Large. A request sent with an Idempotency-Key whose body exceeds the endpoint's Edge replay-protection limit (256 KB) is rejected before it reaches the service. Requests sent without the header are not subject to this limit.
- `422` — Validation Error. Reusing an Idempotency-Key with a different request body also returns 422 with error code 10027.
- `503` — Service unavailable (10016), including unavailable Edge idempotency protection for a keyed request.

## Changes

> 73 revisions in range; 1 not diffed.

- **2026-09-16** `a6a61a29ecdd` — 1 breaking, 1 warning, 6 info
  - the response's body type changed from `object` to no type for status `422`
  - removed the optional property `detail` from the response with the `422` status
  - added the new optional `header` request parameter `Idempotency-Key`
  - added `#/components/schemas/HTTPValidationError, #/components/schemas/inference-embedding_ErrorResponse` to the response body `anyOf` list for the response status `422`
  - …4 more

[Change history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/ai/assistants/:assistant_id/scheduled_events/post.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/revisions/673109139443?raw)