> ## 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. # 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. ## OpenAPI ````yaml https://telnyx-openapi-ng.s3.us-east-1.amazonaws.com/texml/calls.yml post /texml/ai_calls/{connection_id} openapi: 3.1.0 info: title: Telnyx TeXML Calls API version: 2.0.0 description: API for managing TeXML Calls. contact: email: support@telnyx.com servers: - url: https://api.telnyx.com/v2 security: - bearerAuth: [] tags: - name: Command description: TeXML command operations - name: Callbacks description: Webhook callbacks for call events paths: /texml/ai_calls/{connection_id}: post: tags: - TeXML REST Commands summary: Initiate an outbound AI call description: > 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. operationId: InitiateTexmlAICall parameters: - name: connection_id in: path description: The ID of the TeXML connection to use for the call. required: true schema: type: string requestBody: description: Initiate AI Call request object required: true content: application/json: schema: $ref: '#/components/schemas/InitiateAICallRequest' responses: '200': $ref: '#/components/responses/InitiateAICallResponse' '401': $ref: '#/components/responses/UnauthenticatedResponse' '422': $ref: '#/components/responses/call-scripting_UnprocessableEntityResponse' x-codeSamples: - lang: JavaScript source: >- 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); - lang: Python source: |- 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) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/team-telnyx/telnyx-go\"\n\t\"github.com/team-telnyx/telnyx-go/option\"\n)\n\nfunc main() {\n\tclient := telnyx.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.Texml.InitiateAICall(\n\t\tcontext.TODO(),\n\t\t\"connection_id\",\n\t\ttelnyx.TexmlInitiateAICallParams{\n\t\t\tAIAssistantID: \"ai-assistant-id-123\",\n\t\t\tFrom: \"+13120001234\",\n\t\t\tTo: \"+13121230000\",\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.CallSid)\n}\n" - lang: Java source: |- 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); } } - lang: Ruby source: |- 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) - lang: PHP source: >- 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(); } - lang: CLI source: |- telnyx texml initiate-ai-call \ --api-key 'My API Key' \ --connection-id connection_id \ --ai-assistant-id ai-assistant-id-123 \ --from +13120001234 \ --to +13121230000 components: schemas: InitiateAICallRequest: type: object title: Initiate AI Call Request required: - From - To - AIAssistantId properties: From: description: >- The phone number of the party initiating the call. Phone numbers are formatted with a `+` and country code. example: '+16175551212' type: string To: description: >- The phone number of the called party. Phone numbers are formatted with a `+` and country code. example: '+16175551212' type: string AIAssistantId: description: The ID of the AI assistant to use for the call. type: string AIAssistantVersion: description: The version of the AI assistant to use. type: string AIAssistantDynamicVariables: description: Key-value map of dynamic variables to pass to the AI assistant. type: object additionalProperties: type: string example: customer_name: John Doe account_id: '12345' CallerId: description: >- 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 type: string StatusCallback: description: >- 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 type: string StatusCallbackEvent: description: >- 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 default: completed type: string StatusCallbackMethod: description: >- 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. example: GET default: POST type: string enum: - GET - POST StatusCallbacks: description: >- 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. type: array items: type: string example: - https://www.example.com/callback1 - https://www.example.com/callback2 CustomHeaders: description: >- Custom HTTP headers to be sent with the call. Each header should be an object with 'name' and 'value' properties. type: array items: type: object properties: name: type: string description: The name of the custom header value: type: string description: The value of the custom header required: - name - value example: - name: X-Custom-Header value: custom-value ConversationCallback: description: >- 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 type: string ConversationCallbackMethod: description: >- HTTP request type used for `ConversationCallback` and `ConversationCallbacks`. example: GET default: POST type: string enum: - GET - POST ConversationCallbacks: description: >- Array of URL destinations for AI conversation callback events for this call. Events include `conversation_created` and `conversation_ended`. type: array items: type: string example: - https://www.example.com/conversation-callback1 - https://www.example.com/conversation-callback2 MachineDetection: description: Enables Answering Machine Detection. example: Enable default: Disable type: string enum: - Enable - Disable - DetectMessageEnd DetectionMode: description: >- Allows you to choose between Regular, Premium, and PremiumCallScreening detections. See https://developers.telnyx.com/docs/voice/programmable-voice/answering-machine-detection example: Premium default: Regular type: string enum: - Premium - Regular - PremiumCallScreening AsyncAmd: description: >- Select whether to perform answering machine detection in the background. By default execution is blocked until Answering Machine Detection is completed. example: true default: false type: boolean AsyncAmdStatusCallback: description: >- URL destination for Telnyx to send AMD callback events to for the call. example: https://www.example.com/callback type: string AsyncAmdStatusCallbackMethod: description: HTTP request type used for `AsyncAmdStatusCallback`. example: GET default: POST type: string enum: - GET - POST MachineDetectionTimeout: description: Maximum timeout threshold in milliseconds for overall detection. example: 5000 default: 30000 maximum: 60000 minimum: 500 type: integer MachineDetectionPromptEndTimeout: description: >- Silence duration threshold after a call screening prompt before ending prompt detection, in milliseconds. Used when `DetectionMode` is `PremiumCallScreening`. example: 5000 minimum: 1000 maximum: 120000 type: integer MachineDetectionSpeechThreshold: description: >- Maximum threshold of a human greeting. If greeting longer than this value, considered machine. Ignored when `premium` detection is used. example: 2000 default: 3500 type: integer MachineDetectionSpeechEndThreshold: description: >- Silence duration threshold after a greeting message or voice for it be considered human. Ignored when `premium` detection is used. example: 2000 default: 800 type: integer MachineDetectionSilenceTimeout: description: >- If initial silence duration is greater than this value, consider it a machine. Ignored when `premium` detection is used. example: 2000 default: 3500 type: integer Passports: description: A string of passport identifiers to associate with the call. type: string TimeLimit: description: >- 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. example: 3600 type: integer minimum: 30 maximum: 14400 default: 14400 Timeout: description: >- 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. example: 60 type: integer minimum: 5 maximum: 120 default: 30 x-stainless-param: timeout_seconds Record: description: >- Whether to record the entire participant's call leg. Defaults to `false`. example: false type: boolean RecordingChannels: description: The number of channels in the final recording. Defaults to `mono`. example: dual type: string enum: - mono - dual RecordingStatusCallback: description: The URL the recording callbacks will be sent to. example: https://example.com/recording_status_callback type: string RecordingStatusCallbackMethod: description: >- HTTP request type used for `RecordingStatusCallback`. Defaults to `POST`. example: GET type: string enum: - GET - POST RecordingStatusCallbackEvent: description: >- 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 type: string RecordingTimeout: description: >- 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 type: integer default: 0 RecordingTrack: description: The audio track to record for the call. The default is `both`. example: inbound type: string enum: - inbound - outbound - both Trim: description: >- Whether to trim any leading and trailing silence from the recording. Defaults to `trim-silence`. example: trim-silence type: string enum: - trim-silence - do-not-trim SendRecordingUrl: $ref: '#/components/schemas/SendRecordingUrl' PreferredCodecs: description: The list of comma-separated codecs to be offered on a call. example: PCMA,PCMU type: string SipAuthUsername: description: The username to use for SIP authentication. example: user type: string SipAuthPassword: description: The password to use for SIP authentication. example: '1234' type: string SipRegion: description: Defines the SIP region to be used for the call. type: string default: US enum: - US - Europe - Canada - Australia - Middle East example: Canada example: From: '+13120001234' To: '+13121230000' AIAssistantId: ai-assistant-id-123 SendRecordingUrl: type: boolean description: Whether to send RecordingUrl in webhooks. example: false default: true InitiateAICallResult: type: object title: Initiate AI Call Result example: from: '+13120001234' to: '+13121230000' status: queued call_sid: v3:example-call-sid properties: from: type: string example: '+13120001234' to: type: string example: '+13120000000' status: type: string example: queued call_sid: type: string example: v3:example-call-sid ErrorResponse: type: object properties: errors: type: array items: type: object properties: code: type: string detail: type: string meta: type: object properties: url: type: string format: uri title: type: string source: type: object properties: pointer: type: string responses: InitiateAICallResponse: description: Successful response upon initiating an AI call. content: application/json: schema: $ref: '#/components/schemas/InitiateAICallResult' UnauthenticatedResponse: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Authentication Failed: value: errors: - code: '10009' title: Authentication failed detail: Could not understand the provided credentials. meta: url: https://developers.telnyx.com/docs/overview/errors/10009 call-scripting_UnprocessableEntityResponse: description: >- Unprocessable entity. The request was well-formed but contains semantic errors. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_required_parameter: summary: Missing required parameter value: errors: - code: '10004' title: Missing required parameter detail: 'Can''t be blank: ApplicationId' source: pointer: /ApplicationId invalid_parameter_type: summary: Invalid parameter type value: errors: - code: '10026' title: Invalid parameter type detail: The 'To' parameter must be of type 'string' source: pointer: /To invalid_enumerated_value: summary: Invalid enumerated value value: errors: - code: '10032' title: Invalid enumerated value detail: Status must be one of completed source: pointer: /Status invalid_send_digits: summary: Invalid SendDigits format value: errors: - code: '90014' title: Invalid value for SendDigits detail: >- The 'SendDigits' parameter must be a 'string' made of a combination of either 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, w, W, * or # source: pointer: /SendDigits securitySchemes: bearerAuth: scheme: bearer type: http ````