Create a scheduled event

POST

assistants

{assistant_id}

scheduled_events

JavaScript

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const scheduledEventResponse = await client.ai.assistants.scheduledEvents.create('assistant_id', {
  scheduled_at_fixed_datetime: '2025-04-15T13:07:28.764Z',
  telnyx_agent_target: 'telnyx_agent_target',
  telnyx_conversation_channel: 'phone_call',
  telnyx_end_user_target: 'telnyx_end_user_target',
});

console.log(scheduledEventResponse);

import os
from datetime import datetime
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
scheduled_event_response = client.ai.assistants.scheduled_events.create(
    assistant_id="assistant_id",
    scheduled_at_fixed_datetime=datetime.fromisoformat("2025-04-15T13:07:28.764"),
    telnyx_agent_target="telnyx_agent_target",
    telnyx_conversation_channel="phone_call",
    telnyx_end_user_target="telnyx_end_user_target",
)
print(scheduled_event_response)

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	scheduledEventResponse, err := client.AI.Assistants.ScheduledEvents.New(
		context.TODO(),
		"assistant_id",
		telnyx.AIAssistantScheduledEventNewParams{
			ScheduledAtFixedDatetime:  time.Now(),
			TelnyxAgentTarget:         "telnyx_agent_target",
			TelnyxConversationChannel: telnyx.ConversationChannelTypePhoneCall,
			TelnyxEndUserTarget:       "telnyx_end_user_target",
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", scheduledEventResponse)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.ai.assistants.scheduledevents.ConversationChannelType;
import com.telnyx.sdk.models.ai.assistants.scheduledevents.ScheduledEventCreateParams;
import com.telnyx.sdk.models.ai.assistants.scheduledevents.ScheduledEventResponse;
import java.time.OffsetDateTime;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        ScheduledEventCreateParams params = ScheduledEventCreateParams.builder()
            .assistantId("assistant_id")
            .scheduledAtFixedDatetime(OffsetDateTime.parse("2025-04-15T13:07:28.764Z"))
            .telnyxAgentTarget("telnyx_agent_target")
            .telnyxConversationChannel(ConversationChannelType.PHONE_CALL)
            .telnyxEndUserTarget("telnyx_end_user_target")
            .build();
        ScheduledEventResponse scheduledEventResponse = client.ai().assistants().scheduledEvents().create(params);
    }
}

require "telnyx"

telnyx = Telnyx::Client.new(api_key: "My API Key")

scheduled_event_response = telnyx.ai.assistants.scheduled_events.create(
  "assistant_id",
  scheduled_at_fixed_datetime: "2025-04-15T13:07:28.764Z",
  telnyx_agent_target: "telnyx_agent_target",
  telnyx_conversation_channel: :phone_call,
  telnyx_end_user_target: "telnyx_end_user_target"
)

puts(scheduled_event_response)

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\AI\Assistants\ScheduledEvents\ConversationChannelType;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $scheduledEventResponse = $client->ai->assistants->scheduledEvents->create(
    'assistant_id',
    scheduledAtFixedDatetime: new \DateTimeImmutable(
      '2025-04-15T13:07:28.764Z'
    ),
    telnyxAgentTarget: 'telnyx_agent_target',
    telnyxConversationChannel: ConversationChannelType::PHONE_CALL,
    telnyxEndUserTarget: 'telnyx_end_user_target',
    callSettings: ['sipRegion' => 'US'],
    conversationMetadata: ['foo' => 'string'],
    dynamicVariables: ['foo' => 'string'],
    maxRetriesClientErrors: 0,
    retryIntervalSecs: 60,
    text: 'text',
  );

  var_dump($scheduledEventResponse);
} catch (APIException $e) {
  echo $e->getMessage();
}

telnyx ai:assistants:scheduled-events create \
  --api-key 'My API Key' \
  --assistant-id assistant_id \
  --scheduled-at-fixed-datetime "'2025-04-15T13:07:28.764Z'" \
  --telnyx-agent-target telnyx_agent_target \
  --telnyx-conversation-channel phone_call \
  --telnyx-end-user-target telnyx_end_user_target

curl --request POST \
  --url https://api.telnyx.com/v2/ai/assistants/{assistant_id}/scheduled_events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "telnyx_end_user_target": "<string>",
  "telnyx_agent_target": "<string>",
  "scheduled_at_fixed_datetime": "2025-04-15T13:07:28.764Z",
  "text": "<string>",
  "conversation_metadata": {},
  "dynamic_variables": {},
  "max_retries_client_errors": 0,
  "retry_interval_secs": 43230,
  "call_settings": {}
}
'

{
  "telnyx_conversation_channel": "phone_call",
  "telnyx_end_user_target": "Telnyx End User Target",
  "telnyx_agent_target": "Telnyx Agent Target",
  "scheduled_at_fixed_datetime": "2024-01-23T18:10:02.574Z",
  "assistant_id": "Assistant Id",
  "retry_count": 0,
  "retry_attempts": 0,
  "scheduled_event_id": "Scheduled Event Id",
  "conversation_id": "Conversation Id",
  "created_at": "2024-01-23T18:10:02.574Z",
  "status": "pending",
  "errors": [
    "string"
  ],
  "call_status": "Call Status",
  "call_duration": 0,
  "max_retries_client_errors": 0,
  "retry_interval_secs": 0,
  "call_attempts": [
    {
      "attempt_number": 0,
      "attempted_at": "2024-01-23T18:10:02.574Z",
      "call_status": "Call Status",
      "call_duration": 0,
      "telnyx_call_control_id": "Telnyx Call Control Id"
    }
  ],
  "dispatched_at": "2024-01-23T18:10:02.574Z",
  "call_settings": {
    "sip_region": "US"
  }
}

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10036",
      "title": "Resource is being processed",
      "detail": "A request with this Idempotency-Key is already being processed.",
      "source": {
        "pointer": "/header/Idempotency-Key"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "body",
        "name"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key

string

Optional opaque, unquoted key for safely retrying the same logical request. Keys must contain 1 to 255 letters, numbers, hyphens, or underscores. Generate a unique UUID v4 for each operation and reuse it only when retrying that operation with the same request. Invalid headers—including duplicate, empty, malformed, or overlong values—return 400 with error code 10015. A request already in progress with the same key returns 409; reusing the key with a different request returns 422. Only successful responses are replayed, for up to 24 hours. Do not include sensitive data in the key.

Required string length: 1 - 255

Pattern: ^[A-Za-z0-9_-]{1,255}$

Path Parameters

assistant_id

string

required

Unique identifier of the assistant.

Body

application/json

telnyx_conversation_channel

enum<string>

required

Available options:

phone_call,

sms_chat

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.

Example:

"2025-04-15T13:07:28.764Z"

text

string

Required for sms scheduled events. The text to be sent to the end user.

conversation_metadata

Conversation Metadata · object

Metadata associated with the conversation. Telnyx provides several pieces of metadata, but customers can also add their own.

Show child attributes

dynamic_variables

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.

Show child attributes

max_retries_client_errors

integer

default:0

Configure number of retries on client errors: busy, no-answer, failed, canceled (caller hung up before the callee answered)

Required range: 0 <= x <= 10

retry_interval_secs

integer

Required range: 60 <= x <= 86400

call_settings

ScheduledCallSettings · object

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.

Show child attributes

Response

Successful Response

ScheduledPhoneCallEventResponse
ScheduledSmsEventResponse

Union type for different scheduled event response types

telnyx_conversation_channel

enum<string>

required

Available options:

phone_call,

sms_chat

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

default:0

retry_attempts

integer

scheduled_event_id

string

conversation_id

string

created_at

string<date-time>

status

enum<string>

default:pending

Available options:

pending,

in_progress,

completed,

failed

conversation_metadata

Conversation Metadata · object

Show child attributes

dynamic_variables

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.

Show child attributes

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

default:0

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 · object[]

Show child attributes

dispatched_at

string<date-time>

Date time at which call was sent

call_settings

ScheduledCallSettings · object

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.

Show child attributes

JavaScript

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const scheduledEventResponse = await client.ai.assistants.scheduledEvents.create('assistant_id', {
  scheduled_at_fixed_datetime: '2025-04-15T13:07:28.764Z',
  telnyx_agent_target: 'telnyx_agent_target',
  telnyx_conversation_channel: 'phone_call',
  telnyx_end_user_target: 'telnyx_end_user_target',
});

console.log(scheduledEventResponse);

import os
from datetime import datetime
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
scheduled_event_response = client.ai.assistants.scheduled_events.create(
    assistant_id="assistant_id",
    scheduled_at_fixed_datetime=datetime.fromisoformat("2025-04-15T13:07:28.764"),
    telnyx_agent_target="telnyx_agent_target",
    telnyx_conversation_channel="phone_call",
    telnyx_end_user_target="telnyx_end_user_target",
)
print(scheduled_event_response)

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	scheduledEventResponse, err := client.AI.Assistants.ScheduledEvents.New(
		context.TODO(),
		"assistant_id",
		telnyx.AIAssistantScheduledEventNewParams{
			ScheduledAtFixedDatetime:  time.Now(),
			TelnyxAgentTarget:         "telnyx_agent_target",
			TelnyxConversationChannel: telnyx.ConversationChannelTypePhoneCall,
			TelnyxEndUserTarget:       "telnyx_end_user_target",
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", scheduledEventResponse)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.ai.assistants.scheduledevents.ConversationChannelType;
import com.telnyx.sdk.models.ai.assistants.scheduledevents.ScheduledEventCreateParams;
import com.telnyx.sdk.models.ai.assistants.scheduledevents.ScheduledEventResponse;
import java.time.OffsetDateTime;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        ScheduledEventCreateParams params = ScheduledEventCreateParams.builder()
            .assistantId("assistant_id")
            .scheduledAtFixedDatetime(OffsetDateTime.parse("2025-04-15T13:07:28.764Z"))
            .telnyxAgentTarget("telnyx_agent_target")
            .telnyxConversationChannel(ConversationChannelType.PHONE_CALL)
            .telnyxEndUserTarget("telnyx_end_user_target")
            .build();
        ScheduledEventResponse scheduledEventResponse = client.ai().assistants().scheduledEvents().create(params);
    }
}

require "telnyx"

telnyx = Telnyx::Client.new(api_key: "My API Key")

scheduled_event_response = telnyx.ai.assistants.scheduled_events.create(
  "assistant_id",
  scheduled_at_fixed_datetime: "2025-04-15T13:07:28.764Z",
  telnyx_agent_target: "telnyx_agent_target",
  telnyx_conversation_channel: :phone_call,
  telnyx_end_user_target: "telnyx_end_user_target"
)

puts(scheduled_event_response)

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\AI\Assistants\ScheduledEvents\ConversationChannelType;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $scheduledEventResponse = $client->ai->assistants->scheduledEvents->create(
    'assistant_id',
    scheduledAtFixedDatetime: new \DateTimeImmutable(
      '2025-04-15T13:07:28.764Z'
    ),
    telnyxAgentTarget: 'telnyx_agent_target',
    telnyxConversationChannel: ConversationChannelType::PHONE_CALL,
    telnyxEndUserTarget: 'telnyx_end_user_target',
    callSettings: ['sipRegion' => 'US'],
    conversationMetadata: ['foo' => 'string'],
    dynamicVariables: ['foo' => 'string'],
    maxRetriesClientErrors: 0,
    retryIntervalSecs: 60,
    text: 'text',
  );

  var_dump($scheduledEventResponse);
} catch (APIException $e) {
  echo $e->getMessage();
}

telnyx ai:assistants:scheduled-events create \
  --api-key 'My API Key' \
  --assistant-id assistant_id \
  --scheduled-at-fixed-datetime "'2025-04-15T13:07:28.764Z'" \
  --telnyx-agent-target telnyx_agent_target \
  --telnyx-conversation-channel phone_call \
  --telnyx-end-user-target telnyx_end_user_target

curl --request POST \
  --url https://api.telnyx.com/v2/ai/assistants/{assistant_id}/scheduled_events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "telnyx_end_user_target": "<string>",
  "telnyx_agent_target": "<string>",
  "scheduled_at_fixed_datetime": "2025-04-15T13:07:28.764Z",
  "text": "<string>",
  "conversation_metadata": {},
  "dynamic_variables": {},
  "max_retries_client_errors": 0,
  "retry_interval_secs": 43230,
  "call_settings": {}
}
'

{
  "telnyx_conversation_channel": "phone_call",
  "telnyx_end_user_target": "Telnyx End User Target",
  "telnyx_agent_target": "Telnyx Agent Target",
  "scheduled_at_fixed_datetime": "2024-01-23T18:10:02.574Z",
  "assistant_id": "Assistant Id",
  "retry_count": 0,
  "retry_attempts": 0,
  "scheduled_event_id": "Scheduled Event Id",
  "conversation_id": "Conversation Id",
  "created_at": "2024-01-23T18:10:02.574Z",
  "status": "pending",
  "errors": [
    "string"
  ],
  "call_status": "Call Status",
  "call_duration": 0,
  "max_retries_client_errors": 0,
  "retry_interval_secs": 0,
  "call_attempts": [
    {
      "attempt_number": 0,
      "attempted_at": "2024-01-23T18:10:02.574Z",
      "call_status": "Call Status",
      "call_duration": 0,
      "telnyx_call_control_id": "Telnyx Call Control Id"
    }
  ],
  "dispatched_at": "2024-01-23T18:10:02.574Z",
  "call_settings": {
    "sip_region": "US"
  }
}

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10036",
      "title": "Resource is being processed",
      "detail": "A request with this Idempotency-Key is already being processed.",
      "source": {
        "pointer": "/header/Idempotency-Key"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "body",
        "name"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      }
    }
  ]
}

Guides

Missions

AI Insights

Assistants API

Missions API

AI Tests API

Conversations API

For AI Agents

Create a scheduled event

Authorizations

Headers

Path Parameters

Body

Response