diff --git a/openapi/spec3.json b/openapi/spec3.json index 1924f0a..12a46db 100644 --- a/openapi/spec3.json +++ b/openapi/spec3.json @@ -44149,6 +44149,51 @@ } } }, + "/texml/ai_calls/{connection_id}": { + "post": { + "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.", + "x-latency-category": "responsive", + "x-group-parameters": "true", + "operationId": "InitiateTexmlAICall", + "tags": [ + "TeXML REST Commands" + ], + "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" + } + } + } + }, "/texml/secrets": { "post": { "summary": "Create a TeXML secret", @@ -56958,6 +57003,16 @@ } } }, + "InitiateAICallResponse": { + "description": "Successful response upon initiating an AI call.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InitiateAICallResult" + } + } + } + }, "InitiateCallResponse": { "description": "Successful response upon initiating a TeXML call.", "content": { @@ -91066,6 +91121,347 @@ ], "title": "TransferToolParams" }, + "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 to for the call.", + "example": "https://www.example.com/callback", + "type": "string" + }, + "StatusCallbackEvent": { + "description": "The call events for which Telnyx should send a webhook. Multiple events can be defined when separated by a space. Valid values: initiated, ringing, answered, completed.", + "example": "initiated answered", + "default": "completed", + "type": "string" + }, + "StatusCallbackMethod": { + "description": "HTTP request type used for `StatusCallback`.", + "example": "GET", + "default": "POST", + "type": "string", + "enum": [ + "GET", + "POST" + ] + }, + "StatusCallbacks": { + "description": "An array of URL destinations for Telnyx to send status callback events to for the call.", + "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 conversation callback events to.", + "example": "https://www.example.com/conversation-callback", + "type": "string" + }, + "ConversationCallbackMethod": { + "description": "HTTP request type used for `ConversationCallback`.", + "example": "GET", + "default": "POST", + "type": "string", + "enum": [ + "GET", + "POST" + ] + }, + "ConversationCallbacks": { + "description": "An array of URL destinations for conversation callback events.", + "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 Premium and Standard detections.", + "example": "Premium", + "default": "Regular", + "type": "string", + "enum": [ + "Premium", + "Regular" + ] + }, + "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" + }, + "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" + } + }, + "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" + } + } + }, "InitiateCallRequest": { "type": "object", "title": "Initiate Call Request", diff --git a/openapi/spec3.yml b/openapi/spec3.yml index 3747b4f..d974529 100644 --- a/openapi/spec3.yml +++ b/openapi/spec3.yml @@ -5219,6 +5219,12 @@ components: title: List Inexplicit Number Orders Response type: object description: Successful response with a list of inexplicit number orders. + InitiateAICallResponse: + content: + application/json: + schema: + $ref: '#/components/schemas/InitiateAICallResult' + description: Successful response upon initiating an AI call. InitiateCallResponse: content: application/json: @@ -32123,6 +32129,302 @@ components: - from title: TransferToolParams type: object + InitiateAICallRequest: + example: + AIAssistantId: ai-assistant-id-123 + From: '+13120001234' + To: '+13121230000' + properties: + AIAssistantDynamicVariables: + additionalProperties: + type: string + description: Key-value map of dynamic variables to pass to the AI assistant. + example: + account_id: '12345' + customer_name: John Doe + type: object + 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 + AsyncAmd: + default: false + description: Select whether to perform answering machine detection in the + background. By default execution is blocked until Answering Machine Detection + is completed. + example: true + 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: + default: POST + description: HTTP request type used for `AsyncAmdStatusCallback`. + enum: + - GET + - POST + example: GET + type: string + 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 + ConversationCallback: + description: URL destination for Telnyx to send conversation callback events + to. + example: https://www.example.com/conversation-callback + type: string + ConversationCallbackMethod: + default: POST + description: HTTP request type used for `ConversationCallback`. + enum: + - GET + - POST + example: GET + type: string + ConversationCallbacks: + description: An array of URL destinations for conversation callback events. + example: + - https://www.example.com/conversation-callback1 + - https://www.example.com/conversation-callback2 + items: + type: string + type: array + CustomHeaders: + description: 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 + items: + properties: + name: + description: The name of the custom header + type: string + value: + description: The value of the custom header + type: string + required: + - name + - value + type: object + type: array + DetectionMode: + default: Regular + description: Allows you to choose between Premium and Standard detections. + enum: + - Premium + - Regular + example: Premium + type: string + From: + description: The phone number of the party initiating the call. Phone numbers + are formatted with a `+` and country code. + example: '+16175551212' + type: string + MachineDetection: + default: Disable + description: Enables Answering Machine Detection. + enum: + - Enable + - Disable + - DetectMessageEnd + example: Enable + type: string + MachineDetectionSilenceTimeout: + default: 3500 + description: If initial silence duration is greater than this value, consider + it a machine. Ignored when `premium` detection is used. + example: 2000 + type: integer + MachineDetectionSpeechEndThreshold: + default: 800 + description: Silence duration threshold after a greeting message or voice + for it be considered human. Ignored when `premium` detection is used. + example: 2000 + type: integer + MachineDetectionSpeechThreshold: + default: 3500 + description: Maximum threshold of a human greeting. If greeting longer than + this value, considered machine. Ignored when `premium` detection is used. + example: 2000 + type: integer + MachineDetectionTimeout: + default: 30000 + description: Maximum timeout threshold in milliseconds for overall detection. + example: 5000 + maximum: 60000 + minimum: 500 + type: integer + Passports: + description: A string of passport identifiers to associate with the call. + type: string + PreferredCodecs: + description: The list of comma-separated codecs to be offered on a call. + example: PCMA,PCMU + type: string + 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`. + enum: + - mono + - dual + example: dual + type: string + RecordingStatusCallback: + description: The URL the recording callbacks will be sent to. + example: https://example.com/recording_status_callback + type: string + 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 + RecordingStatusCallbackMethod: + description: HTTP request type used for `RecordingStatusCallback`. Defaults + to `POST`. + enum: + - GET + - POST + example: GET + type: string + RecordingTimeout: + default: 0 + 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 + RecordingTrack: + description: The audio track to record for the call. The default is `both`. + enum: + - inbound + - outbound + - both + example: inbound + type: string + SendRecordingUrl: + $ref: '#/components/schemas/SendRecordingUrl' + SipAuthPassword: + description: The password to use for SIP authentication. + example: '1234' + type: string + SipAuthUsername: + description: The username to use for SIP authentication. + example: user + type: string + SipRegion: + default: US + description: Defines the SIP region to be used for the call. + enum: + - US + - Europe + - Canada + - Australia + - Middle East + example: Canada + type: string + StatusCallback: + description: URL destination for Telnyx to send status callback events to + for the call. + example: https://www.example.com/callback + type: string + StatusCallbackEvent: + default: completed + description: 'The call events for which Telnyx should send a webhook. Multiple + events can be defined when separated by a space. Valid values: initiated, + ringing, answered, completed.' + example: initiated answered + type: string + StatusCallbackMethod: + default: POST + description: HTTP request type used for `StatusCallback`. + enum: + - GET + - POST + example: GET + type: string + StatusCallbacks: + description: An array of URL destinations for Telnyx to send status callback + events to for the call. + example: + - https://www.example.com/callback1 + - https://www.example.com/callback2 + items: + type: string + type: array + TimeLimit: + default: 14400 + 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 + maximum: 14400 + minimum: 30 + type: integer + Timeout: + default: 30 + 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 + maximum: 120 + minimum: 5 + type: integer + x-stainless-param: timeout_seconds + To: + description: The phone number of the called party. Phone numbers are formatted + with a `+` and country code. + example: '+16175551212' + type: string + Trim: + description: Whether to trim any leading and trailing silence from the recording. + Defaults to `trim-silence`. + enum: + - trim-silence + - do-not-trim + example: trim-silence + type: string + required: + - From + - To + - AIAssistantId + title: Initiate AI Call Request + type: object + InitiateAICallResult: + example: + call_sid: v3:example-call-sid + from: '+13120001234' + status: queued + to: '+13121230000' + properties: + call_sid: + example: v3:example-call-sid + type: string + from: + example: '+13120001234' + type: string + status: + example: queued + type: string + to: + example: '+13120000000' + type: string + title: Initiate AI Call Result + type: object InitiateCallRequest: example: ApplicationSid: example-app-sid @@ -94661,6 +94963,39 @@ paths: - TeXML REST Commands x-group-parameters: 'true' x-latency-category: responsive + /texml/ai_calls/{connection_id}: + post: + 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. + operationId: InitiateTexmlAICall + parameters: + - description: The ID of the TeXML connection to use for the call. + in: path + name: connection_id + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/InitiateAICallRequest' + description: Initiate AI Call request object + required: true + responses: + '200': + $ref: '#/components/responses/InitiateAICallResponse' + '401': + $ref: '#/components/responses/UnauthenticatedResponse' + '422': + $ref: '#/components/responses/call-scripting_UnprocessableEntityResponse' + summary: Initiate an outbound AI call + tags: + - TeXML REST Commands + x-group-parameters: 'true' + x-latency-category: responsive /texml/secrets: post: description: Create a TeXML secret which can be later used as a Dynamic Parameter