Skip to main content
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);
{
  "from": "+13120001234",
  "to": "+13121230000",
  "status": "queued",
  "call_sid": "v3:example-call-sid"
}

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.

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"

​
To
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.

​
AIAssistantVersion
string

The version of the AI assistant to use.

​
AIAssistantDynamicVariables
object

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

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.

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

​
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"

​
to
string
Example:

"+13120000000"

​
status
string
Example:

"queued"

​
call_sid
string
Example:

"v3:example-call-sid"