Initiate an outbound AI call

Initiate an outbound AI call with warm-up support: Telnyx attempts to warm up the assistant identified by AIAssistantId before placing the call and starts it automatically when the called party answers. Validates parameters, builds an internal TeXML with an AI Assistant configuration, encodes instructions into client state, and calls the dial API. The Twiml, Texml, and Url parameters are not allowed and will result in a 422 error.

Expected callback events:

Status callbacks: initiated, ringing, answered, one terminal status (completed, no-answer, busy, canceled, or failed), then analyzed after post-call processing completes.

Conversation callbacks: conversation_created and conversation_ended.

Recording, AMD, transcription, and deepfake detection callbacks are only sent when those features are enabled.

POST

texml

ai_calls

{connection_id}

JavaScript

import Telnyx from 'telnyx';

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

const response = await client.texml.initiateAICall('connection_id', {
  AIAssistantId: 'ai-assistant-id-123',
  From: '+13120001234',
  To: '+13121230000',
});

console.log(response.call_sid);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
response = client.texml.initiate_ai_call(
    connection_id="connection_id",
    ai_assistant_id="ai-assistant-id-123",
    from_="+13120001234",
    to="+13121230000",
)
print(response.call_sid)

package main

import (
	"context"
	"fmt"

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

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	response, err := client.Texml.InitiateAICall(
		context.TODO(),
		"connection_id",
		telnyx.TexmlInitiateAICallParams{
			AIAssistantID: "ai-assistant-id-123",
			From:          "+13120001234",
			To:            "+13121230000",
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.CallSid)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.texml.TexmlInitiateAiCallParams;
import com.telnyx.sdk.models.texml.TexmlInitiateAiCallResponse;

public final class Main {
    private Main() {}

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

        TexmlInitiateAiCallParams params = TexmlInitiateAiCallParams.builder()
            .connectionId("connection_id")
            .aiAssistantId("ai-assistant-id-123")
            .from("+13120001234")
            .to("+13121230000")
            .build();
        TexmlInitiateAiCallResponse response = client.texml().initiateAiCall(params);
    }
}

require "telnyx"

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

response = telnyx.texml.initiate_ai_call(
  "connection_id",
  ai_assistant_id: "ai-assistant-id-123",
  from: "+13120001234",
  to: "+13121230000"
)

puts(response)

<?php

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

use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;

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

try {
  $response = $client->texml->initiateAICall(
    'connection_id',
    aiAssistantID: 'ai-assistant-id-123',
    from: '+13120001234',
    to: '+13121230000',
    aiAssistantDynamicVariables: [
      'customer_name' => 'John Doe', 'account_id' => '12345'
    ],
    aiAssistantVersion: 'AIAssistantVersion',
    asyncAmd: true,
    asyncAmdStatusCallback: 'https://www.example.com/callback',
    asyncAmdStatusCallbackMethod: 'GET',
    callerID: 'Info',
    conversationCallback: 'https://www.example.com/conversation-callback',
    conversationCallbackMethod: 'GET',
    conversationCallbacks: [
      'https://www.example.com/conversation-callback1',
      'https://www.example.com/conversation-callback2',
    ],
    customHeaders: [['name' => 'X-Custom-Header', 'value' => 'custom-value']],
    detectionMode: 'Premium',
    machineDetection: 'Enable',
    machineDetectionPromptEndTimeout: 5000,
    machineDetectionSilenceTimeout: 2000,
    machineDetectionSpeechEndThreshold: 2000,
    machineDetectionSpeechThreshold: 2000,
    machineDetectionTimeout: 5000,
    passports: 'Passports',
    preferredCodecs: 'PCMA,PCMU',
    record: false,
    recordingChannels: 'dual',
    recordingStatusCallback: 'https://example.com/recording_status_callback',
    recordingStatusCallbackEvent: 'in-progress completed absent',
    recordingStatusCallbackMethod: 'GET',
    recordingTimeout: 5,
    recordingTrack: 'inbound',
    sendRecordingURL: false,
    sipAuthPassword: '1234',
    sipAuthUsername: 'user',
    sipRegion: 'Canada',
    statusCallback: 'https://www.example.com/callback',
    statusCallbackEvent: 'initiated answered',
    statusCallbackMethod: 'GET',
    statusCallbacks: [
      'https://www.example.com/callback1', 'https://www.example.com/callback2'
    ],
    timeLimit: 3600,
    timeoutSeconds: 60,
    trim: 'trim-silence',
  );

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

curl --request POST \
  --url https://api.telnyx.com/v2/texml/ai_calls/{connection_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "From": "+13120001234",
  "To": "+13121230000",
  "AIAssistantId": "ai-assistant-id-123"
}
'

{
  "from": "+13120001234",
  "to": "+13121230000",
  "status": "queued",
  "call_sid": "v3:example-call-sid"
}

Authorizations

Authorization

string

header

required

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

Path Parameters

connection_id

string

required

The ID of the TeXML connection to use for the call.

Body

application/json

Initiate AI Call request object

From

string

required

The phone number of the party initiating the call. Phone numbers are formatted with a + and country code.

Example:

"+16175551212"

string

required

The phone number of the called party. Phone numbers are formatted with a + and country code.

Example:

"+16175551212"

AIAssistantId

string

required

The ID of the AI assistant to use for the call. Telnyx attempts to warm up this assistant before the call is placed and starts it automatically when the called party answers.

AIAssistantVersion

string

The version of the AI assistant to use.

AIAssistantDynamicVariables

object

Key-value map of dynamic variables to pass to the AI assistant.

Show child attributes

Example:

{
  "customer_name": "John Doe",
  "account_id": "12345"
}

CallerId

string

To be used as the caller id name (SIP From Display Name) presented to the destination (To number). The string should have a maximum of 128 characters, containing only letters, numbers, spaces, and -_~!.+ special characters. If omitted, the display name will be the same as the number in the From field.

Example:

"Info"

StatusCallback

string

URL destination for Telnyx to send status callback events for this AI call. When provided, this per-call value overrides the status callback URL configured on the TeXML application/connection.

Example:

"https://www.example.com/callback"

StatusCallbackEvent

string

default:completed

The status callback events for which Telnyx should send a webhook for this AI call. Multiple events can be defined when separated by a space. Valid values: initiated, ringing, answered, completed, no-answer, busy, canceled, failed, analyzed. When provided, this per-call value overrides the status callback events configured on the TeXML application/connection.

Example:

"initiated answered"

StatusCallbackMethod

enum<string>

default:POST

HTTP request type used for StatusCallback and StatusCallbacks for this AI call. When provided, this per-call value overrides the status callback method configured on the TeXML application/connection.

Available options:

GET,

POST

Example:

"GET"

StatusCallbacks

string[]

Array of URL destinations for Telnyx to send status callback events for this AI call. When provided, these per-call values override the status callback URL configured on the TeXML application/connection.

Example:

[
  "https://www.example.com/callback1",
  "https://www.example.com/callback2"
]

CustomHeaders

object[]

Custom HTTP headers to be sent with the call. Each header should be an object with 'name' and 'value' properties.

Show child attributes

Example:

[
  {
    "name": "X-Custom-Header",
    "value": "custom-value"
  }
]

ConversationCallback

string

URL destination for Telnyx to send AI conversation callback events for this call. Events include conversation_created and conversation_ended.

Example:

"https://www.example.com/conversation-callback"

ConversationCallbackMethod

enum<string>

default:POST

HTTP request type used for ConversationCallback and ConversationCallbacks.

Available options:

GET,

POST

Example:

"GET"

ConversationCallbacks

string[]

Array of URL destinations for AI conversation callback events for this call. Events include conversation_created and conversation_ended.

Example:

[
  "https://www.example.com/conversation-callback1",
  "https://www.example.com/conversation-callback2"
]

MachineDetection

enum<string>

default:Disable

Enables Answering Machine Detection.

Available options:

Enable,

Disable,

DetectMessageEnd

Example:

"Enable"

DetectionMode

enum<string>

default:Regular

Allows you to choose between Regular, Premium, and PremiumCallScreening detections. See https://developers.telnyx.com/docs/voice/programmable-voice/answering-machine-detection

Available options:

Premium,

Regular,

PremiumCallScreening

Example:

"Premium"

AsyncAmd

boolean

default:false

Select whether to perform answering machine detection in the background. By default execution is blocked until Answering Machine Detection is completed.

Example:

true

AsyncAmdStatusCallback

string

URL destination for Telnyx to send AMD callback events to for the call.

Example:

"https://www.example.com/callback"

AsyncAmdStatusCallbackMethod

enum<string>

default:POST

HTTP request type used for AsyncAmdStatusCallback.

Available options:

GET,

POST

Example:

"GET"

MachineDetectionTimeout

integer

default:30000

Maximum timeout threshold in milliseconds for overall detection.

Required range: 500 <= x <= 60000

Example:

5000

MachineDetectionPromptEndTimeout

integer

Silence duration threshold after a call screening prompt before ending prompt detection, in milliseconds. Used when DetectionMode is PremiumCallScreening.

Required range: 1000 <= x <= 120000

Example:

5000

MachineDetectionSpeechThreshold

integer

default:3500

Maximum threshold of a human greeting. If greeting longer than this value, considered machine. Ignored when premium detection is used.

Example:

2000

MachineDetectionSpeechEndThreshold

integer

default:800

Silence duration threshold after a greeting message or voice for it be considered human. Ignored when premium detection is used.

Example:

2000

MachineDetectionSilenceTimeout

integer

default:3500

If initial silence duration is greater than this value, consider it a machine. Ignored when premium detection is used.

Example:

2000

MachineDetectionBeepProfile

enum<string>

default:both

Selects which detectors must validate a beep. both requires the amplitude and frequency detectors to agree. freq_only uses the frequency detector alone, for beeps whose volume is too unsteady for the default profile. Only used when MachineDetection is enabled.

Available options:

both,

freq_only

Example:

"freq_only"

MachineDetectionBeepMinFrequency

integer<int32>

Lowest frequency, in Hz, that a tone must reach to be treated as a beep. Raising it above 480 excludes North American ringback (440 + 480 Hz), which can otherwise be reported as a beep when the freq_only profile is in use. Only used when MachineDetection is enabled.

Required range: 200 <= x <= 4000

Example:

550

MachineDetectionBeepMaxFrequency

integer<int32>

Highest frequency, in Hz, that a tone can reach and still be treated as a beep. Only used when MachineDetection is enabled.

Required range: 200 <= x <= 4000

Example:

2000

MachineDetectionBeepMinToneDuration

integer<int32>

Shortest tone, in milliseconds, that can be treated as a beep. Raising it rejects brief tones such as call-progress blips. Only used when MachineDetection is enabled.

Required range: 50 <= x <= 5000

Example:

300

MachineDetectionBeepSpectralConfirmation

boolean

When enabled, a candidate beep must pass an additional spectral check before it is reported. Only used when MachineDetection is enabled.

Example:

true

MachineDetectionBeepSpectralWindow

integer<int32>

Length of the spectral confirmation window, in milliseconds. Only used when MachineDetection is enabled.

Required range: 20 <= x <= 1000

Example:

100

MachineDetectionBeepSpectralMinPurity

number

Minimum spectral purity, from 0 to 1, for a tone to be treated as a beep. Raising it rejects mixed tones such as ringback, which combines two frequencies. Only used when MachineDetection is enabled.

Required range: 0 <= x <= 1

Example:

0.8

MachineDetectionBeepSpectralRejectFaxCng

boolean

When enabled, the fax CNG tone is rejected rather than reported as a beep. Only used when MachineDetection is enabled.

Example:

true

Passports

string

A string of passport identifiers to associate with the call.

TimeLimit

integer

default:14400

The maximum duration of the call in seconds. The minimum value is 30 and the maximum value is 14400 (4 hours). Default is 14400 seconds.

Required range: 30 <= x <= 14400

Example:

3600

Timeout

integer

default:30

The number of seconds to wait for the called party to answer the call before the call is canceled. The minimum value is 5 and the maximum value is 120. Default is 30 seconds.

Required range: 5 <= x <= 120

Example:

60

Record

boolean

Whether to record the entire participant's call leg. Defaults to false.

Example:

false

RecordingChannels

enum<string>

The number of channels in the final recording. Defaults to mono.

Available options:

mono,

dual

Example:

"dual"

RecordingStatusCallback

string

The URL the recording callbacks will be sent to.

Example:

"https://example.com/recording_status_callback"

RecordingStatusCallbackMethod

enum<string>

HTTP request type used for RecordingStatusCallback. Defaults to POST.

Available options:

GET,

POST

Example:

"GET"

RecordingStatusCallbackEvent

string

The changes to the recording's state that should generate a call to RecordingStatusCallback. Can be: in-progress, completed and absent. Separate multiple values with a space. Defaults to completed.

Example:

"in-progress completed absent"

RecordingTimeout

integer

default:0

The number of seconds that Telnyx will wait for the recording to be stopped if silence is detected. The timer only starts when the speech is detected. The minimum value is 0. The default value is 0 (infinite).

Example:

5

RecordingTrack

enum<string>

The audio track to record for the call. The default is both.

Available options:

inbound,

outbound,

both

Example:

"inbound"

Trim

enum<string>

Whether to trim any leading and trailing silence from the recording. Defaults to trim-silence.

Available options:

trim-silence,

do-not-trim

Example:

"trim-silence"

SendRecordingUrl

boolean

default:true

Whether to send RecordingUrl in webhooks.

Example:

false

PreferredCodecs

string

The list of comma-separated codecs to be offered on a call.

Example:

"PCMA,PCMU"

SipAuthUsername

string

The username to use for SIP authentication.

Example:

"user"

SipAuthPassword

string

The password to use for SIP authentication.

Example:

"1234"

SipRegion

enum<string>

default:US

Defines the SIP region to be used for the call.

Available options:

US,

Europe,

Canada,

Australia,

Middle East

Example:

"Canada"

Response

Successful response upon initiating an AI call.

from

string

Example:

"+13120001234"

string

Example:

"+13120000000"

status

string

Example:

"queued"

call_sid

string

Example:

"v3:example-call-sid"

JavaScript

import Telnyx from 'telnyx';

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

const response = await client.texml.initiateAICall('connection_id', {
  AIAssistantId: 'ai-assistant-id-123',
  From: '+13120001234',
  To: '+13121230000',
});

console.log(response.call_sid);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
response = client.texml.initiate_ai_call(
    connection_id="connection_id",
    ai_assistant_id="ai-assistant-id-123",
    from_="+13120001234",
    to="+13121230000",
)
print(response.call_sid)

package main

import (
	"context"
	"fmt"

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

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	response, err := client.Texml.InitiateAICall(
		context.TODO(),
		"connection_id",
		telnyx.TexmlInitiateAICallParams{
			AIAssistantID: "ai-assistant-id-123",
			From:          "+13120001234",
			To:            "+13121230000",
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.CallSid)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.texml.TexmlInitiateAiCallParams;
import com.telnyx.sdk.models.texml.TexmlInitiateAiCallResponse;

public final class Main {
    private Main() {}

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

        TexmlInitiateAiCallParams params = TexmlInitiateAiCallParams.builder()
            .connectionId("connection_id")
            .aiAssistantId("ai-assistant-id-123")
            .from("+13120001234")
            .to("+13121230000")
            .build();
        TexmlInitiateAiCallResponse response = client.texml().initiateAiCall(params);
    }
}

require "telnyx"

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

response = telnyx.texml.initiate_ai_call(
  "connection_id",
  ai_assistant_id: "ai-assistant-id-123",
  from: "+13120001234",
  to: "+13121230000"
)

puts(response)

<?php

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

use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;

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

try {
  $response = $client->texml->initiateAICall(
    'connection_id',
    aiAssistantID: 'ai-assistant-id-123',
    from: '+13120001234',
    to: '+13121230000',
    aiAssistantDynamicVariables: [
      'customer_name' => 'John Doe', 'account_id' => '12345'
    ],
    aiAssistantVersion: 'AIAssistantVersion',
    asyncAmd: true,
    asyncAmdStatusCallback: 'https://www.example.com/callback',
    asyncAmdStatusCallbackMethod: 'GET',
    callerID: 'Info',
    conversationCallback: 'https://www.example.com/conversation-callback',
    conversationCallbackMethod: 'GET',
    conversationCallbacks: [
      'https://www.example.com/conversation-callback1',
      'https://www.example.com/conversation-callback2',
    ],
    customHeaders: [['name' => 'X-Custom-Header', 'value' => 'custom-value']],
    detectionMode: 'Premium',
    machineDetection: 'Enable',
    machineDetectionPromptEndTimeout: 5000,
    machineDetectionSilenceTimeout: 2000,
    machineDetectionSpeechEndThreshold: 2000,
    machineDetectionSpeechThreshold: 2000,
    machineDetectionTimeout: 5000,
    passports: 'Passports',
    preferredCodecs: 'PCMA,PCMU',
    record: false,
    recordingChannels: 'dual',
    recordingStatusCallback: 'https://example.com/recording_status_callback',
    recordingStatusCallbackEvent: 'in-progress completed absent',
    recordingStatusCallbackMethod: 'GET',
    recordingTimeout: 5,
    recordingTrack: 'inbound',
    sendRecordingURL: false,
    sipAuthPassword: '1234',
    sipAuthUsername: 'user',
    sipRegion: 'Canada',
    statusCallback: 'https://www.example.com/callback',
    statusCallbackEvent: 'initiated answered',
    statusCallbackMethod: 'GET',
    statusCallbacks: [
      'https://www.example.com/callback1', 'https://www.example.com/callback2'
    ],
    timeLimit: 3600,
    timeoutSeconds: 60,
    trim: 'trim-silence',
  );

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

curl --request POST \
  --url https://api.telnyx.com/v2/texml/ai_calls/{connection_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "From": "+13120001234",
  "To": "+13121230000",
  "AIAssistantId": "ai-assistant-id-123"
}
'

{
  "from": "+13120001234",
  "to": "+13121230000",
  "status": "queued",
  "call_sid": "v3:example-call-sid"
}

Guides

Markup Language

API Reference

For AI Agents

Initiate an outbound AI call

Authorizations

Path Parameters

Body

Response