> ## 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. # Start AI Assistant > Start an AI assistant on the call. **Expected Webhooks:** - `call.conversation.ended` - `call.conversation_insights.generated` ## OpenAPI ````yaml https://telnyx-openapi-ng.s3.us-east-1.amazonaws.com/call-control-commands/ai-assistant-start.yml post /calls/{call_control_id}/actions/ai_assistant_start openapi: 3.1.0 info: title: Telnyx Call Control - AI Assistant Start version: 2.0.0 description: API for starting AI Assistant on a call. contact: email: support@telnyx.com servers: - url: https://api.telnyx.com/v2 security: - bearerAuth: [] tags: - name: Command description: Call control command operations paths: /calls/{call_control_id}/actions/ai_assistant_start: post: tags: - Call Commands summary: Start AI Assistant description: | Start an AI assistant on the call. **Expected Webhooks:** - `call.conversation.ended` - `call.conversation_insights.generated` operationId: CallStartAIAssistant parameters: - $ref: '#/components/parameters/CallControlId' requestBody: description: AI Assistant request required: true content: application/json: schema: $ref: '#/components/schemas/AIAssistantStartRequest' responses: '200': $ref: '#/components/responses/CallControlCommandResponseWithConversationId' '422': $ref: '#/components/responses/UnprocessableEntityResponse' default: $ref: '#/components/responses/call-control_GenericErrorResponse' 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.calls.actions.startAIAssistant('call_control_id'); console.log(response.data); - 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.calls.actions.start_ai_assistant( call_control_id="call_control_id", ) print(response.data) - 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.Calls.Actions.StartAIAssistant(\n\t\tcontext.TODO(),\n\t\t\"call_control_id\",\n\t\ttelnyx.CallActionStartAIAssistantParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\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.calls.actions.ActionStartAiAssistantParams; import com.telnyx.sdk.models.calls.actions.ActionStartAiAssistantResponse; public final class Main { private Main() {} public static void main(String[] args) { TelnyxClient client = TelnyxOkHttpClient.fromEnv(); ActionStartAiAssistantResponse response = client.calls().actions().startAiAssistant("call_control_id"); } } - lang: Ruby source: >- require "telnyx" telnyx = Telnyx::Client.new(api_key: "My API Key") response = telnyx.calls.actions.start_ai_assistant("call_control_id") puts(response) - lang: PHP source: >- calls->actions->startAIAssistant( 'call_control_id', assistant: [ 'id' => 'id', 'dynamicVariables' => [ 'customer_name' => 'John', 'account_id' => 'ACC-12345' ], 'externalLlm' => [ 'authenticationMethod' => 'token', 'baseURL' => 'base_url', 'certificateRef' => 'certificate_ref', 'forwardMetadata' => true, 'llmAPIKeyRef' => 'llm_api_key_ref', 'model' => 'model', 'tokenRetrievalURL' => 'token_retrieval_url', ], 'fallbackConfig' => [ 'externalLlm' => [ 'authenticationMethod' => 'token', 'baseURL' => 'base_url', 'certificateRef' => 'certificate_ref', 'forwardMetadata' => true, 'llmAPIKeyRef' => 'llm_api_key_ref', 'model' => 'model', 'tokenRetrievalURL' => 'token_retrieval_url', ], 'llmAPIKeyRef' => 'llm_api_key_ref', 'model' => 'model', ], 'greeting' => 'greeting', 'instructions' => 'You are a friendly voice assistant.', 'llmAPIKeyRef' => 'my_llm_api_key', 'mcpServers' => [['foo' => 'bar']], 'model' => 'gpt-4o', 'name' => 'name', 'observabilitySettings' => ['foo' => 'bar'], 'openaiAPIKeyRef' => 'my_openai_api_key', 'tools' => [ [ 'bookAppointment' => [ 'apiKeyRef' => 'my_calcom_api_key', 'eventTypeID' => 0, 'attendeeName' => 'attendee_name', 'attendeeTimezone' => 'attendee_timezone', ], 'type' => 'book_appointment', ], ], ], clientState: 'aGF2ZSBhIG5pY2UgZGF5ID1d', commandID: '891510ac-f3e4-11e8-af5b-de00688a4901', greeting: 'Hello, can you tell me your age and where you live?', interruptionSettings: ['enable' => true], messageHistory: [ [ 'content' => 'Hello, I would like some help.', 'role' => 'user', 'metadata' => ['foo' => 'bar'], ], ], participants: [ [ 'id' => 'v3:abc123def456', 'role' => 'user', 'name' => 'John Doe', 'onHangup' => 'continue_conversation', ], ], sendMessageHistoryUpdates: true, transcription: [ 'language' => 'auto', 'model' => 'distil-whisper/distil-large-v2' ], voice: 'Telnyx.KokoroTTS.af', voiceSettings: [ 'type' => 'elevenlabs', 'apiKeyRef' => 'my_elevenlabs_api_key' ], ); var_dump($response); } catch (APIException $e) { echo $e->getMessage(); } - lang: CLI source: |- telnyx calls:actions start-ai-assistant \ --api-key 'My API Key' \ --call-control-id call_control_id components: parameters: CallControlId: name: call_control_id description: Unique identifier and token for controlling the call in: path required: true schema: type: string schemas: AIAssistantStartRequest: type: object properties: assistant: $ref: '#/components/schemas/CallAssistantRequest' voice: $ref: '#/components/schemas/VoiceConfig' voice_settings: description: The settings associated with the voice selected oneOf: - $ref: '#/components/schemas/ElevenLabsVoiceSettings' - $ref: '#/components/schemas/TelnyxVoiceSettings' - $ref: '#/components/schemas/AWSVoiceSettings' - $ref: '#/components/schemas/AzureVoiceSettings' - $ref: '#/components/schemas/RimeVoiceSettings' - $ref: '#/components/schemas/ResembleVoiceSettings' - $ref: '#/components/schemas/XAIVoiceSettings' discriminator: propertyName: type mapping: elevenlabs: $ref: '#/components/schemas/ElevenLabsVoiceSettings' telnyx: $ref: '#/components/schemas/TelnyxVoiceSettings' aws: $ref: '#/components/schemas/AWSVoiceSettings' azure: $ref: '#/components/schemas/AzureVoiceSettings' rime: $ref: '#/components/schemas/RimeVoiceSettings' resemble: $ref: '#/components/schemas/ResembleVoiceSettings' xai: $ref: '#/components/schemas/XAIVoiceSettings' greeting: description: >- Text that will be played when the assistant starts, if none then nothing will be played when the assistant starts. The greeting can be text for any voice or SSML for `AWS.Polly.` voices. There is a 3,000 character limit. type: string example: Hello, can you tell me your age and where you live? interruption_settings: $ref: '#/components/schemas/InterruptionSettings' transcription: $ref: '#/components/schemas/TranscriptionConfig' message_history: type: array description: >- A list of messages to seed the conversation history before the assistant starts. Follows the same message format as the `ai_assistant_add_messages` command. items: oneOf: - $ref: '#/components/schemas/UserMessage' - $ref: '#/components/schemas/AssistantMessage' - $ref: '#/components/schemas/ToolMessage' - $ref: '#/components/schemas/SystemMessage' - $ref: '#/components/schemas/DeveloperMessage' discriminator: propertyName: role mapping: user: $ref: '#/components/schemas/UserMessage' assistant: $ref: '#/components/schemas/AssistantMessage' tool: $ref: '#/components/schemas/ToolMessage' system: $ref: '#/components/schemas/SystemMessage' developer: $ref: '#/components/schemas/DeveloperMessage' default: [] send_message_history_updates: type: boolean description: >- When `true`, a webhook is sent each time the conversation message history is updated. default: false participants: type: array description: A list of participants to add to the conversation when it starts. items: $ref: '#/components/schemas/AIAssistantJoinParticipant' default: [] client_state: type: string description: >- Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string. example: aGF2ZSBhIG5pY2UgZGF5ID1d command_id: description: >- Use this field to avoid duplicate commands. Telnyx will ignore any command with the same `command_id` for the same `call_control_id`. type: string example: 891510ac-f3e4-11e8-af5b-de00688a4901 CallAssistantRequest: type: object description: >- AI Assistant configuration. All fields except `id` are optional — the assistant's stored configuration will be used as fallback for any omitted fields. required: - id properties: id: type: string description: The identifier of the AI assistant to use. model: type: string description: >- LLM model override for this call. If omitted, the assistant's configured model is used. example: gpt-4o name: type: string description: Assistant name override for this call. instructions: type: string description: >- System instructions for the voice assistant. Can be templated with [dynamic variables](https://developers.telnyx.com/docs/inference/ai-assistants/dynamic-variables). This will overwrite the instructions set in the assistant configuration. example: You are a friendly voice assistant. greeting: type: string maxLength: 3000 description: >- Initial greeting text spoken when the assistant starts. Can be plain text for any voice or SSML for `AWS.Polly.` voices. There is a 3,000 character limit. tools: type: array description: >- Inline tool definitions available to the assistant (webhook, retrieval, transfer, hangup, etc.). Overrides the assistant's stored tools if provided. items: oneOf: - $ref: '#/components/schemas/BookAppointmentTool' - $ref: '#/components/schemas/CheckAvailabilityTool' - $ref: '#/components/schemas/WebhookTool' - $ref: '#/components/schemas/HangupTool' - $ref: '#/components/schemas/TransferTool' - $ref: '#/components/schemas/CallControlRetrievalTool' discriminator: propertyName: type mapping: book_appointment: $ref: '#/components/schemas/BookAppointmentTool' check_availability: $ref: '#/components/schemas/CheckAvailabilityTool' webhook: $ref: '#/components/schemas/WebhookTool' hangup: $ref: '#/components/schemas/HangupTool' transfer: $ref: '#/components/schemas/TransferTool' retrieval: $ref: '#/components/schemas/CallControlRetrievalTool' llm_api_key_ref: type: string description: >- Integration secret identifier for the LLM provider API key. Use this field to reference an [integration secret](https://developers.telnyx.com/api/secrets-manager/integration-secrets/create-integration-secret) containing your LLM provider API key. Supports any LLM provider (OpenAI, Anthropic, etc.). example: my_llm_api_key openai_api_key_ref: type: string description: >- Deprecated — use `llm_api_key_ref` instead. Integration secret identifier for the OpenAI API key. This field is maintained for backward compatibility; `llm_api_key_ref` is the canonical field name and supports all LLM providers. deprecated: true x-sdk-deprecation-message: Use llm_api_key_ref instead example: my_openai_api_key dynamic_variables: type: object description: >- Map of dynamic variables and their default values. Dynamic variables can be referenced in instructions, greeting, and tool definitions using the `{{variable_name}}` syntax. Call-control-agent automatically merges in `telnyx_call_*` variables (telnyx_call_to, telnyx_call_from, telnyx_conversation_channel, telnyx_agent_target, telnyx_end_user_target, telnyx_call_caller_id_name) and custom header variables. additionalProperties: oneOf: - type: string - type: number - type: boolean example: customer_name: John account_id: ACC-12345 fallback_config: type: object description: >- Fallback LLM configuration used when the primary LLM provider is unavailable. properties: model: type: string description: >- Fallback Telnyx-hosted model to use when the primary LLM provider is unavailable. llm_api_key_ref: type: string description: Integration secret identifier for the fallback model API key. external_llm: type: object description: External LLM fallback configuration. properties: model: type: string description: Model identifier to use with the external LLM endpoint. base_url: type: string description: Base URL for the external LLM endpoint. llm_api_key_ref: type: string description: Integration secret identifier for the external LLM API key. authentication_method: type: string enum: - token - certificate default: token description: >- Authentication method used when connecting to the external LLM endpoint. certificate_ref: type: string description: >- Integration secret identifier for the client certificate used with certificate authentication. token_retrieval_url: type: string description: >- URL used to retrieve an access token when certificate authentication is enabled. forward_metadata: type: boolean default: false description: >- When enabled, Telnyx forwards the assistant's dynamic variables to the external LLM endpoint. Defaults to false. The chat completion request includes a top-level `extra_metadata` object when dynamic variables are available. For example: `{"extra_metadata":{"customer_name":"Jane","account_id":"acct_789","telnyx_agent_target":"+13125550100","telnyx_end_user_target":"+13125550123"}}`. external_llm: type: object description: External LLM configuration for bringing your own LLM endpoint. properties: model: type: string description: Model identifier to use with the external LLM endpoint. base_url: type: string description: Base URL for the external LLM endpoint. llm_api_key_ref: type: string description: Integration secret identifier for the external LLM API key. authentication_method: type: string enum: - token - certificate default: token description: >- Authentication method used when connecting to the external LLM endpoint. certificate_ref: type: string description: >- Integration secret identifier for the client certificate used with certificate authentication. token_retrieval_url: type: string description: >- URL used to retrieve an access token when certificate authentication is enabled. forward_metadata: type: boolean default: false description: >- When enabled, Telnyx forwards the assistant's dynamic variables to the external LLM endpoint. Defaults to false. The chat completion request includes a top-level `extra_metadata` object when dynamic variables are available. For example: `{"extra_metadata":{"customer_name":"Jane","account_id":"acct_789","telnyx_agent_target":"+13125550100","telnyx_end_user_target":"+13125550123"}}`. mcp_servers: type: array description: >- MCP (Model Context Protocol) server configurations for extending the assistant's capabilities with external tools and data sources. items: type: object properties: {} observability_settings: type: object description: >- Observability configuration for the assistant session, including Langfuse integration for tracing and monitoring. properties: {} VoiceConfig: description: >- The voice to be used by the voice assistant. Currently we support ElevenLabs, Telnyx and AWS voices. **Supported Providers:** - **AWS:** Use `AWS.Polly.` (e.g., `AWS.Polly.Joanna`). For neural voices, which provide more realistic, human-like speech, append `-Neural` to the `VoiceId` (e.g., `AWS.Polly.Joanna-Neural`). Check the [available voices](https://docs.aws.amazon.com/polly/latest/dg/available-voices.html) for compatibility. - **Azure:** Use `Azure.. (e.g. Azure.en-CA-ClaraNeural, Azure.en-CA-LiamNeural, Azure.en-US-BrianMultilingualNeural, Azure.en-US-Ava:DragonHDLatestNeural. For a complete list of voices, go to [Azure Voice Gallery](https://speech.microsoft.com/portal/voicegallery).) - **ElevenLabs:** Use `ElevenLabs..` (e.g., `ElevenLabs.BaseModel.John`). The `ModelId` part is optional. To use ElevenLabs, you must provide your ElevenLabs API key as an integration secret under `"voice_settings": {"api_key_ref": ""}`. See [integration secrets documentation](https://developers.telnyx.com/api/secrets-manager/integration-secrets/create-integration-secret) for details. Check [available voices](https://elevenlabs.io/docs/api-reference/get-voices). - **Telnyx:** Use `Telnyx..` - **Inworld:** Use `Inworld..` (e.g., `Inworld.Mini.Loretta`, `Inworld.Max.Oliver`). Supported models: `Mini`, `Max`. - **xAI:** Use `xAI.` (e.g., `xAI.eve`). Available voices: `eve`, `ara`, `rex`, `sal`, `leo`. type: string default: Telnyx.KokoroTTS.af example: Telnyx.KokoroTTS.af ElevenLabsVoiceSettings: type: object title: ElevenLabs Voice Settings properties: type: type: string enum: - elevenlabs description: Voice settings provider type api_key_ref: description: >- The `identifier` for an integration secret [/v2/integration_secrets](https://developers.telnyx.com/api/secrets-manager/integration-secrets/create-integration-secret) that refers to your ElevenLabs API key. Warning: Free plans are unlikely to work with this integration. type: string example: my_elevenlabs_api_key required: - type TelnyxVoiceSettings: type: object title: Telnyx Voice Settings properties: type: type: string enum: - telnyx description: Voice settings provider type voice_speed: description: >- The voice speed to be used for the voice. The voice speed must be between 0.1 and 2.0. Default value is 1.0. type: number default: 1 format: float example: 1 minimum: 0.1 maximum: 2 required: - type AWSVoiceSettings: type: object title: AWS Voice Settings properties: type: type: string enum: - aws description: Voice settings provider type required: - type AzureVoiceSettings: type: object title: Azure Voice Settings properties: type: type: string enum: - azure description: Voice settings provider type api_key_ref: description: >- The `identifier` for an integration secret that refers to your Azure Speech API key. type: string example: my_azure_api_key region: description: >- The Azure region for the Speech service (e.g., `eastus`, `westeurope`). Required when using a custom API key. type: string example: eastus deployment_id: description: The deployment ID for a custom Azure neural voice. type: string example: my-custom-voice-deployment effect: description: Audio effect to apply. type: string enum: - eq_car - eq_telecomhp8k gender: description: Voice gender filter. type: string enum: - Male - Female required: - type RimeVoiceSettings: type: object title: Rime Voice Settings properties: type: type: string enum: - rime description: Voice settings provider type voice_speed: description: Speech speed multiplier. Default is 1.0. type: number format: float default: 1 example: 1 required: - type ResembleVoiceSettings: type: object title: Resemble Voice Settings properties: type: type: string enum: - resemble description: Voice settings provider type precision: description: Audio precision format. type: string enum: - PCM_16 - PCM_24 - PCM_32 - MULAW default: PCM_32 sample_rate: $ref: '#/components/schemas/ResembleSampleRate' format: description: Output audio format. type: string enum: - wav - mp3 default: mp3 required: - type XAIVoiceSettings: type: object title: xAI Voice Settings properties: type: type: string enum: - xai description: Voice settings provider type language: description: Language code, or `auto` to detect automatically. type: string default: auto required: - type InterruptionSettings: type: object description: Settings for handling user interruptions during assistant speech properties: enable: type: boolean description: When true, allows users to interrupt the assistant while speaking default: true TranscriptionConfig: type: object description: >- The settings associated with speech to text for the voice assistant. This is only relevant if the assistant uses a text-to-text language model. Any assistant using a model with native audio support (e.g. `fixie-ai/ultravox-v0_4`) will ignore this field. properties: model: description: >- The speech to text model to be used by the voice assistant. Supported models include: - `deepgram/flux` (or `flux`) for live streaming turn-taking. - `deepgram/nova-3` and `deepgram/nova-2` for live streaming transcription. - `speechmatics/standard` and `speechmatics/enhanced` for live streaming transcription. - `assemblyai/universal-streaming` for live streaming transcription. - `xai/grok-stt` for live streaming transcription. - `azure/fast` and `azure/realtime`; Azure models require `region`, and unsupported regions require `api_key_ref`. - `google/latest_long` for non-streaming multilingual transcription. - `distil-whisper/distil-large-v2` for lower-latency English-only non-streaming transcription. - `openai/whisper-large-v3-turbo` for multilingual non-streaming transcription with automatic language detection. type: string enum: - deepgram/flux - flux - deepgram/nova-3 - deepgram/nova-2 - speechmatics/standard - speechmatics/enhanced - assemblyai/universal-streaming - xai/grok-stt - azure/fast - azure/realtime - google/latest_long - distil-whisper/distil-large-v2 - openai/whisper-large-v3-turbo default: distil-whisper/distil-large-v2 example: distil-whisper/distil-large-v2 language: type: string description: >- The language of the audio to be transcribed. If not set, or if set to `auto`, supported models will automatically detect the language. Supported and meaningful values depend on the selected transcription `model`. For `deepgram/flux`, supported values are: `auto` (Telnyx language detection controls the language hint), `multi` (no language hint), and language-specific hints `en`, `es`, `fr`, `de`, `hi`, `ru`, `pt`, `ja`, `it`, and `nl`. default: auto example: auto UserMessage: type: object title: User message. description: Messages sent by an end user properties: role: description: The role of the messages author, in this case `user`. type: string enum: - user content: description: The contents of the user message. type: string metadata: $ref: '#/components/schemas/MessageMetadata' required: - role - content example: role: user content: Hello, I would like some help. AssistantMessage: type: object title: Assistant Message description: Messages sent by the model in response to user messages. properties: role: description: The role of the messages author, in this case `assistant`. type: string enum: - assistant content: description: The contents of the assistant message. Required unless `tool_calls` type: string tool_calls: type: array description: The tool calls generated by the model, such as function calls. items: $ref: '#/components/schemas/ToolCall' metadata: $ref: '#/components/schemas/MessageMetadata' required: - role example: role: assistant content: Hello, I'm John. ToolMessage: type: object title: Tool Message properties: role: description: The role of the messages author, in this case `tool`. type: string enum: - tool content: description: The contents of the tool message. type: string tool_call_id: description: Tool call that this message is responding to. type: string metadata: $ref: '#/components/schemas/MessageMetadata' required: - role - content - tool_call_id example: role: tool content: Hello, I'm John. tool_call_id: call_123 SystemMessage: type: object title: System Message description: >- Developer-provided instructions that the model should follow, regardless of messages sent by the user. properties: role: description: The role of the messages author, in this case `system`. type: string enum: - system content: description: The contents of the system message. type: string metadata: $ref: '#/components/schemas/MessageMetadata' required: - role - content example: role: system content: Get the user's favorite color DeveloperMessage: type: object title: Developer Message description: >- Developer-provided instructions that the model should follow, regardless of messages sent by the user. properties: role: description: The role of the messages author, in this case developer. type: string enum: - developer content: description: The contents of the developer message. type: string metadata: $ref: '#/components/schemas/MessageMetadata' required: - role - content example: role: developer content: Get the user's favorite color AIAssistantJoinParticipant: type: object required: - id - role properties: id: type: string description: The call_control_id of the participant to add to the conversation. example: v3:abc123def456 role: type: string description: The role of the participant in the conversation. enum: - user example: user name: type: string description: Display name for the participant. example: John Doe on_hangup: type: string description: >- Determines what happens to the conversation when this participant hangs up. enum: - continue_conversation - end_conversation default: continue_conversation example: continue_conversation CallControlCommandResultWithConversationId: type: object title: Call Control Command Result With Conversation ID example: result: ok conversation_id: d7e9c1d4-8b2a-4b8f-b3a7-9a671c9e9b0a properties: result: type: string example: ok conversation_id: type: string format: uuid example: d7e9c1d4-8b2a-4b8f-b3a7-9a671c9e9b0a description: The ID of the conversation created by the command. call-control_Errors: properties: errors: type: array items: $ref: '#/components/schemas/call-control_Error' BookAppointmentTool: properties: type: type: string enum: - book_appointment book_appointment: $ref: '#/components/schemas/BookAppointmentToolParams' type: object required: - type - book_appointment title: BookAppointmentTool CheckAvailabilityTool: properties: type: type: string enum: - check_availability check_availability: $ref: '#/components/schemas/CheckAvailabilityToolParams' type: object required: - type - check_availability title: CheckAvailabilityTool WebhookTool: properties: type: type: string enum: - webhook webhook: $ref: '#/components/schemas/CallControlWebhookToolParams' type: object required: - type - webhook title: WebhookTool HangupTool: properties: type: type: string enum: - hangup hangup: $ref: '#/components/schemas/HangupToolParams' type: object required: - type - hangup title: HangupTool TransferTool: properties: type: type: string enum: - transfer transfer: $ref: '#/components/schemas/CallControlTransferToolParams' type: object required: - type - transfer title: TransferTool CallControlRetrievalTool: properties: type: type: string enum: - retrieval retrieval: $ref: '#/components/schemas/CallControlBucketIds' type: object required: - type - retrieval title: RetrievalTool ResembleSampleRate: type: string title: Resemble Sample Rate description: Audio sample rate in Hz. enum: - '8000' - '16000' - '22050' - '32000' - '44100' - '48000' default: '48000' MessageMetadata: description: Metadata to add to the message type: object ToolCall: title: Tool Call type: object description: A call to a function tool created by the model. properties: id: description: The ID of the tool call. type: string type: description: The type of the tool. Currently, only `function` is supported. type: string enum: - function function: description: The function that the model called. type: object properties: name: type: string description: The name of the function to call. required: - name required: - id - type - function example: id: call_123 type: function function: name: get_weather call-control_Error: required: - code - title properties: code: type: string format: integer title: type: string detail: type: string source: type: object properties: pointer: description: JSON pointer (RFC6901) to the offending entity. type: string format: json-pointer parameter: description: Indicates which query parameter caused the error. type: string meta: type: object BookAppointmentToolParams: properties: event_type_id: type: integer description: >- Event Type ID for which slots are being fetched. [cal.com](https://cal.com/docs/api-reference/v2/bookings/create-a-booking#body-event-type-id) api_key_ref: type: string description: >- Reference to an integration secret that contains your Cal.com API key. You would pass the `identifier` for an integration secret [/v2/integration_secrets](https://developers.telnyx.com/api/secrets-manager/integration-secrets/create-integration-secret) that refers to your Cal.com API key. example: my_calcom_api_key attendee_name: type: string description: >- The name of the attendee [cal.com](https://cal.com/docs/api-reference/v2/bookings/create-a-booking#body-attendee-name). If not provided, the assistant will ask for the attendee's name. attendee_timezone: type: string description: >- The timezone of the attendee [cal.com](https://cal.com/docs/api-reference/v2/bookings/create-a-booking#body-attendee-timezone). If not provided, the assistant will ask for the attendee's timezone. type: object required: - event_type_id - api_key_ref title: BookAppointmentToolParams CheckAvailabilityToolParams: properties: event_type_id: type: integer description: >- Event Type ID for which slots are being fetched. [cal.com](https://cal.com/docs/api-reference/v2/slots/get-available-slots#parameter-event-type-id) api_key_ref: type: string description: >- Reference to an integration secret that contains your Cal.com API key. You would pass the `identifier` for an integration secret [/v2/integration_secrets](https://developers.telnyx.com/api/secrets-manager/integration-secrets/create-integration-secret) that refers to your Cal.com API key. example: my_calcom_api_key type: object required: - event_type_id - api_key_ref title: CheckAvailabilityToolParams CallControlWebhookToolParams: properties: name: type: string description: The name of the tool. description: type: string description: The description of the tool. url: description: >- The URL of the external tool to be called. This URL is going to be used by the assistant. The URL can be templated like: `https://example.com/api/v1/{id}`, where `{id}` is a placeholder for a value that will be provided by the assistant if `path_parameters` are provided with the `id` attribute. type: string example: https://example.com/api/v1/function method: description: The HTTP method to be used when calling the external tool. type: string enum: - GET - POST - PUT - DELETE - PATCH default: POST headers: description: The headers to be sent to the external tool. type: array items: type: object properties: name: type: string value: description: >- The value of the header. Note that we support mustache templating for the value. For example you can use `Bearer {{#integration_secret}}test-secret{{/integration_secret}}` to pass the value of the integration secret as the bearer token. type: string body_parameters: description: >- The body parameters the webhook tool accepts, described as a JSON Schema object. These parameters will be passed to the webhook as the body of the request. See the [JSON Schema reference](https://json-schema.org/understanding-json-schema) for documentation about the format type: object properties: properties: description: The properties of the body parameters. type: object required: description: The required properties of the body parameters. type: array items: type: string type: type: string enum: - object example: properties: age: description: The age of the customer. type: integer location: description: The location of the customer. type: string required: - age - location type: object path_parameters: description: >- The path parameters the webhook tool accepts, described as a JSON Schema object. These parameters will be passed to the webhook as the path of the request if the URL contains a placeholder for a value. See the [JSON Schema reference](https://json-schema.org/understanding-json-schema) for documentation about the format type: object properties: properties: description: The properties of the path parameters. type: object required: description: The required properties of the path parameters. type: array items: type: string type: type: string enum: - object example: properties: id: description: The id of the customer. type: string required: - id type: object query_parameters: description: >- The query parameters the webhook tool accepts, described as a JSON Schema object. These parameters will be passed to the webhook as the query of the request. See the [JSON Schema reference](https://json-schema.org/understanding-json-schema) for documentation about the format type: object properties: properties: description: The properties of the query parameters. type: object required: description: The required properties of the query parameters. type: array items: type: string type: type: string enum: - object example: properties: page: description: The page number. type: integer required: - page type: object type: object required: - url - name - description title: WebhookToolParams HangupToolParams: properties: description: type: string default: This tool is used to hang up the call. description: >- The description of the function that will be passed to the assistant. type: object title: HangupToolParams CallControlTransferToolParams: properties: targets: oneOf: - type: array items: type: object properties: name: type: string description: The name of the target. example: Support to: type: string description: The destination number or SIP URI of the call. example: '+13129457420' required: - to - type: string description: >- A dynamic variable string like `{{ targets }}` where `targets` is returned by the dynamic variables webhook and resolves to an array of target objects at runtime. example: '{{ targets }}' description: >- The different possible targets of the transfer. The assistant will be able to choose one of the targets to transfer the call to. This can also be a dynamic variable string like `{{ targets }}` where `targets` is returned by the dynamic variables webhook and resolves to an array of target objects at runtime. from: type: string example: '+35319605860' description: Number or SIP URI placing the call. type: object required: - targets - from title: TransferToolParams CallControlBucketIds: properties: bucket_ids: items: type: string type: array title: Bucket Ids max_num_results: description: >- The maximum number of results to retrieve as context for the language model. type: integer type: object required: - bucket_ids title: BucketIds responses: CallControlCommandResponseWithConversationId: description: >- Successful response upon making a call control command that includes conversation_id. content: application/json: schema: type: object title: Call Control Command Response With Conversation ID properties: data: $ref: >- #/components/schemas/CallControlCommandResultWithConversationId UnprocessableEntityResponse: description: >- Unprocessable entity. The request was well-formed but could not be processed due to semantic errors. This includes validation errors, invalid parameter values, call state errors, conference errors, queue errors, recording/transcription errors, and business logic violations. content: application/json: schema: $ref: '#/components/schemas/call-control_Errors' examples: missing_required_parameter: summary: Missing required parameter value: errors: - code: '10004' title: Missing required parameter detail: The 'to' parameter is required and cannot be blank. source: pointer: /to invalid_call_control_id: summary: Invalid call control ID value: errors: - code: '90015' title: Invalid Call Control ID detail: The call_control_id provided was not valid. source: pointer: /call_control_id call_already_ended: summary: Call has already ended value: errors: - code: '90018' title: Call has already ended detail: This call is no longer active and can't receive commands. call_not_answered: summary: Call not answered yet value: errors: - code: '90034' title: Call not answered yet detail: >- This call can't receive this command because it has not been answered yet. cannot_record_before_audio_started: summary: Cannot record before audio started value: errors: - code: '90020' title: Call recording triggered before audio started detail: >- Call recording cannot be started until audio has commenced on the call. transcription_already_active: summary: Transcription already active value: errors: - code: '90054' title: Call transcription is already in progress detail: Call transcription can not be started more than once. ai_assistant_already_active: summary: AI Assistant already active value: errors: - code: '90061' title: AI Assistant is already in progress detail: AI Assistant cannot be started more than once. conference_already_ended: summary: Conference has already ended value: errors: - code: '90019' title: Conference has already ended detail: >- This conference is no longer active and can't receive commands. conference_name_conflict: summary: Conference name conflict value: errors: - code: '90033' title: Unable to execute command detail: Conference with given name already exists and it's active. max_participants_reached: summary: Maximum participants reached value: errors: - code: '90032' title: Maximum number of participants reached detail: >- The maximum allowed value of `max_participants` has been reached at 100. queue_full: summary: Queue is full value: errors: - code: '90036' title: Queue full detail: The 'support' queue is full and can't accept more calls. call_already_in_queue: summary: Call already in queue value: errors: - code: '90038' title: Call already in queue detail: Call can't be added to a queue it's already in. invalid_connection_id: summary: Invalid connection ID value: errors: - code: '10015' title: Invalid value for connection_id (Call Control App ID) detail: >- The requested connection_id (Call Control App ID) is either invalid or does not exist. Only Call Control Apps with valid webhook URL are accepted. source: pointer: /connection_id invalid_phone_number_format: summary: Invalid phone number format value: errors: - code: '10016' title: Phone number must be in +E164 format detail: The 'to' parameter must be in E164 format. source: pointer: /to srtp_not_supported_for_pstn: summary: SRTP not supported for PSTN calls value: errors: - source: pointer: /media_encryption title: Media encryption not supported for PSTN calls detail: SRTP media encryption is not supported for PSTN calls. code: '10011' fork_not_found: summary: Call is not forked value: errors: - code: '90031' title: Call is not currently forked detail: >- Can't stop forking, because the call isn't currently forked. media_streaming_used: summary: Media streaming in use value: errors: - code: '90045' title: Media Streaming is used detail: This command can't be issued when media streaming is used. invalid_enumerated_value: summary: Invalid enumerated value value: errors: - code: '10032' title: Invalid enumerated value detail: 'The value must be one of: dual, single.' source: pointer: /record_channels value_outside_range: summary: Value outside of range value: errors: - code: '10033' title: Value outside of range detail: The value is outside of allowed range 1 to 5000 source: pointer: /max_participants call-control_GenericErrorResponse: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/call-control_Errors' securitySchemes: bearerAuth: scheme: bearer type: http ````