Sign in
TeXML REST Commands

Initiate an outbound AI call

Initiate an outbound AI call with warm-up support. 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}

Path parameters

connection_idstring required

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

Request body

Fromstring required

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

Tostring required

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

AIAssistantIdstring required

The ID of the AI assistant to use for the call.

AIAssistantVersionstring

The version of the AI assistant to use.

AIAssistantDynamicVariablesobject

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

CallerIdstring

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.

StatusCallbackstring

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.

StatusCallbackEventstring

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.

StatusCallbackMethod'GET' | '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.

StatusCallbacksstring[]

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.

ConversationCallbackstring

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

ConversationCallbackMethod'GET' | 'POST'

HTTP request type used for ConversationCallback and ConversationCallbacks.

ConversationCallbacksstring[]

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

MachineDetection'Enable' | 'Disable' | 'DetectMessageEnd'

Enables Answering Machine Detection.

DetectionMode'Premium' | 'Regular' | 'PremiumCallScreening'

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

AsyncAmdboolean

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

AsyncAmdStatusCallbackstring

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

AsyncAmdStatusCallbackMethod'GET' | 'POST'

HTTP request type used for AsyncAmdStatusCallback.

MachineDetectionTimeoutinteger

Maximum timeout threshold in milliseconds for overall detection.

MachineDetectionPromptEndTimeoutinteger

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

MachineDetectionSpeechThresholdinteger

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

MachineDetectionSpeechEndThresholdinteger

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

MachineDetectionSilenceTimeoutinteger

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

MachineDetectionBeepProfile'both' | 'freq_only'

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.

MachineDetectionBeepMinFrequencyinteger

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.

MachineDetectionBeepMaxFrequencyinteger

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

MachineDetectionBeepMinToneDurationinteger

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.

MachineDetectionBeepSpectralConfirmationboolean

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

MachineDetectionBeepSpectralWindowinteger

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

MachineDetectionBeepSpectralMinPuritynumber

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.

MachineDetectionBeepSpectralRejectFaxCngboolean

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

Passportsstring

A string of passport identifiers to associate with the call.

TimeLimitinteger

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.

Timeoutinteger

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.

Recordboolean

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

RecordingChannels'mono' | 'dual'

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

RecordingStatusCallbackstring

The URL the recording callbacks will be sent to.

RecordingStatusCallbackMethod'GET' | 'POST'

HTTP request type used for RecordingStatusCallback. Defaults to POST.

RecordingStatusCallbackEventstring

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.

RecordingTimeoutinteger

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).

RecordingTrack'inbound' | 'outbound' | 'both'

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

Trim'trim-silence' | 'do-not-trim'

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

SendRecordingUrlboolean

Whether to send RecordingUrl in webhooks.

PreferredCodecsstring

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

SipAuthUsernamestring

The username to use for SIP authentication.

SipAuthPasswordstring

The password to use for SIP authentication.

SipRegion'US' | 'Europe' | 'Canada' | 'Australia' | 'Middle East'

Defines the SIP region to be used for the call.

Example request

{
  "From": "+13120001234",
  "To": "+13121230000",
  "AIAssistantId": "ai-assistant-id-123"
}

Response

Successful response upon initiating an AI call.

fromstring
tostring
statusstring
call_sidstring

Example response

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

Changes

Changed in 2 of the 99 revisions of this API.8

  • eaf7ad0b98867See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

  • a6a61a29ecdd1See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

    This revision also has 34 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Of the 99 revisions, 1 has no diff computed.