> ## Documentation Index > Fetch the complete documentation index at: https://docs.retellai.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Chat Agent > Create a new chat agent ## OpenAPI ````yaml openapi-final post /create-chat-agent openapi: 3.0.3 info: title: Retell SDK version: 3.0.0 x-retell-spec-revision: 2026-10-04-3cbc602 contact: name: Retell Support url: https://www.retellai.com/ email: support@retellai.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://api.retellai.com description: The production server. security: - api_key: [] paths: /create-chat-agent: post: description: Create a new chat agent operationId: createChatAgent requestBody: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/ChatAgentRequest' - required: - response_engine responses: '201': description: Successfully created a new chat agent. content: application/json: schema: $ref: '#/components/schemas/ChatAgentResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '500': $ref: '#/components/responses/InternalServerError' x-codeSamples: - lang: JavaScript source: |- import Retell from 'retell-sdk'; const client = new Retell({ apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted }); const chatAgentResponse = await client.chatAgent.create({ response_engine: { llm_id: 'llm_234sdertfsdsfsdf', type: 'retell-llm' }, }); console.log(chatAgentResponse.agent_id); - lang: Python source: |- import os from retell import Retell client = Retell( api_key=os.environ.get("RETELL_API_KEY"), # This is the default and can be omitted ) chat_agent_response = client.chat_agent.create( response_engine={ "llm_id": "llm_234sdertfsdsfsdf", "type": "retell-llm", }, ) print(chat_agent_response.agent_id) components: schemas: ChatAgentRequest: type: object properties: response_engine: $ref: '#/components/schemas/ResponseEngine' description: >- The Response Engine to attach to the agent. It is used to generate responses for the agent. You need to create a Response Engine first before attaching it to an agent. example: type: retell-llm llm_id: llm_234sdertfsdsfsdf version: 0 agent_name: type: string example: Jarvis description: The name of the chat agent. Only used for your own reference. nullable: true version_title: type: string example: Production hotfix description: >- Optional title of the chat agent version. Used for your own reference. nullable: true auto_close_message: type: string example: Thank you for chatting. The conversation has ended. description: Message to display when the chat is automatically closed. nullable: true end_chat_after_silence_ms: type: integer example: 3600000 description: >- If users stay silent for a period after agent speech, end the chat. The minimum value allowed is 120,000 ms (2 minutes). The maximum value allowed is 259,200,000 ms (72 hours). By default, this is set to 3,600,000 (1 hour). nullable: true language: oneOf: - $ref: '#/components/schemas/Language' - type: array items: $ref: '#/components/schemas/Language' - type: string enum: - multi deprecated: true description: >- Specifies what language(s) the agent will operate in. Accepts either a single locale (e.g. `en-US`) or an array of locales for multilingual agents (e.g. `["en-US","es-ES"]`). The scalar value `multi` is deprecated but still accepted as a scalar, and is stored and returned as the ten locales it used to mean. It must not appear inside the array form. Send an explicit locale array instead. If unset, defaults to `en-US`. webhook_url: type: string example: https://webhook-url-here description: >- The webhook for agent to listen to chat events. See what events it would get at [webhook doc](/features/webhook). If set, will binds webhook events for this agent to the specified url, and will ignore the account level webhook for this agent. Set to `null` to remove webhook url from this agent. nullable: true webhook_events: type: array items: type: string enum: - chat_started - chat_ended - chat_analyzed - transcript_updated description: >- Which webhook events this agent should receive. If not set, defaults to chat_started, chat_ended, chat_analyzed. nullable: true webhook_timeout_ms: type: integer example: 10000 description: >- The timeout for the webhook in milliseconds. If not set, default value of 10000 will apply. contact_memory_config: $ref: '#/components/schemas/ContactMemoryConfig' data_storage_setting: type: string enum: - everything - everything_except_pii - basic_attributes_only example: everything description: >- Controls what data is stored for this agent. "everything" stores all data including transcripts and recordings. "everything_except_pii" stores data but excludes PII when possible based on PII configuration. "basic_attributes_only" stores only basic metadata. If not set, defaults to "everything". nullable: true data_storage_retention_days: type: integer minimum: 1 maximum: 730 example: 30 nullable: true description: >- Number of days to retain call/chat data before automatic deletion. Must be between 1 and 730 days. If not set, data is retained forever (no automatic deletion). opt_in_signed_url: type: boolean example: true description: >- Whether this agent opts in to signed url for public log. If not set, default value of false will apply. signed_url_expiration_ms: type: integer example: 86400000 description: >- The expiration time for the signed url in milliseconds. Only applicable when opt_in_signed_url is true. If not set, default value of 86400000 (24 hours) will apply. nullable: true post_chat_analysis_data: type: array items: $ref: '#/components/schemas/PostChatAnalysisData' description: >- Post chat analysis data to extract from the chat. This data will augment the pre-defined variables extracted in the chat analysis. This will be available after the chat ends. nullable: true post_chat_analysis_model: $ref: '#/components/schemas/NullableLLMModel' example: gpt-4.1-mini description: The model to use for post chat analysis. Default to gpt-5.6-terra. pii_config: $ref: '#/components/schemas/PIIConfig' description: Configuration for PII scrubbing from transcripts and recordings. guardrail_config: $ref: '#/components/schemas/GuardrailConfig' description: >- Configuration for guardrail checks to detect and prevent prohibited topics in agent output and user input. handbook_config: $ref: '#/components/schemas/ChatHandbookConfig' description: >- Toggle behavior presets on/off to influence agent response style and behaviors. Voice-only presets are not available for chat agents. timezone: type: string description: >- IANA timezone for the agent (e.g. America/New_York). Defaults to America/Los_Angeles if not set. example: America/New_York nullable: true pre_session_tools: type: array maxItems: 15 nullable: true items: $ref: '#/components/schemas/PreSessionTool' description: >- Integration (Agent Functions) tools run as a dependency graph before the chat's first message. Outputs are injected as dynamic variables. Set to null to clear. post_session_tools: type: array maxItems: 15 nullable: true items: $ref: '#/components/schemas/PostSessionTool' description: >- Integration (Agent Functions) tools run as a dependency graph at chat end, after post-chat analysis. Each tool can be gated by a condition. Set to null to clear. ChatAgentResponse: allOf: - type: object required: - agent_id properties: agent_id: type: string example: oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD description: Unique id of chat agent. version: type: integer example: 0 description: The version of the chat agent. base_version: type: integer nullable: true example: 12 description: Version that this draft was based on. Null for initial versions. assigned_tags: type: array items: type: string description: >- Tags assigned to this chat agent version. Preferred tag is listed first. is_published: type: boolean example: false description: Whether the chat agent is published. - $ref: '#/components/schemas/ChatAgentRequest' required: - response_engine - type: object required: - last_modification_timestamp properties: last_modification_timestamp: type: integer example: 1703413636133 description: >- Last modification timestamp (milliseconds since epoch). Either the time of last update or creation if no updates available. ResponseEngine: oneOf: - $ref: '#/components/schemas/ResponseEngineRetellLm' - $ref: '#/components/schemas/ResponseEngineCustomLm' - $ref: '#/components/schemas/ResponseEngineConversationFlow' Language: type: string example: en-US enum: - en-US - en-IN - en-GB - en-AU - en-NZ - de-DE - es-ES - es-419 - hi-IN - fr-FR - fr-CA - ja-JP - pt-PT - pt-BR - zh-CN - ru-RU - it-IT - ko-KR - nl-NL - nl-BE - pl-PL - tr-TR - vi-VN - ro-RO - bg-BG - ca-ES - th-TH - da-DK - fi-FI - el-GR - hu-HU - id-ID - no-NO - sk-SK - sv-SE - lt-LT - lv-LV - cs-CZ - ms-MY - af-ZA - ar-SA - az-AZ - bs-BA - cy-GB - fa-IR - fil-PH - gl-ES - he-IL - hr-HR - hy-AM - is-IS - kk-KZ - kn-IN - mk-MK - mr-IN - ne-NP - sl-SI - sr-RS - sw-KE - ta-IN - ur-IN - yue-CN - uk-UA description: >- Specifies what language (and dialect) the agent will operate in. For instance, selecting `en-GB` optimizes speech recognition for British English and indexes knowledge bases with English. If unset, will use default value `en-US`. ContactMemoryConfig: type: object additionalProperties: false description: >- Contact memory settings for phone calls and SMS chats. Creating an agent defaults enable_update to false and enable_read to true. Updates only change the supplied flags; omitted flags stay unchanged and an empty object has no effect. Set a flag to false to disable it. The configuration cannot be cleared. Existing agents without this configuration have both disabled. properties: enable_update: type: boolean description: >- Rewrite the contact memory after each conversation. Requires storing conversation data. Chat agents must also have end_chat_after_silence_ms set. enable_read: type: boolean description: >- Automatically add saved contact memory to the agent prompt. Skippable nodes can use answers from the current conversation even when this setting is disabled. Contact dynamic variables, including contact_memory, remain available regardless of this setting. PostChatAnalysisData: oneOf: - $ref: '#/components/schemas/AnalysisData' - $ref: '#/components/schemas/ChatPresetAnalysisData' description: >- Post-chat analysis item (custom data or chat preset). Use for chat agent post_chat_analysis_data; validates only chat presets (chat_summary, chat_successful, user_sentiment). NullableLLMModel: type: string enum: - gpt-4.1 - gpt-4.1-mini - gpt-4.1-nano - gpt-5 - gpt-5-mini - gpt-5-nano - gpt-5.1 - gpt-5.2 - gpt-5.4 - gpt-5.4-mini - gpt-5.4-nano - gpt-5.5 - gpt-5.6-terra - gpt-5.6-luna - gpt-6-astra - gpt-6-sol - gpt-6.1-sol - gpt-6-luna - claude-4.5-sonnet - claude-4.6-sonnet - claude-5-opus - claude-5.5-opus - claude-5-sonnet - claude-5.5-sonnet - claude-4.5-haiku - gemini-3.0-flash - gemini-3.1-flash-lite - gemini-3.5-flash - gemini-3.5-flash-lite - gemini-3.6-flash - gemini-3.7-flash - gemini-3.8-flash - null nullable: true description: Available LLM models for agents. PIIConfig: type: object required: - mode - categories properties: mode: type: string enum: - post_call default: post_call description: >- The processing mode for PII scrubbing. Currently only post-call is supported. categories: type: array items: type: string enum: - person_name - address - email - phone_number - ssn - passport - driver_license - credit_card - bank_account - password - pin - medical_id - date_of_birth - customer_account_number uniqueItems: true default: [] description: >- List of PII categories to scrub from transcripts and recordings. PII redaction is only active when this list is non-empty; an empty array means no PII scrubbing is performed. GuardrailConfig: type: object properties: output_topics: type: array items: type: string enum: - harassment - self_harm - sexual_exploitation - violence - defense_and_national_security - illicit_and_harmful_activity - gambling - regulated_professional_advice - child_safety_and_exploitation uniqueItems: true description: >- Selected prohibited agent topic categories to check. When agent messages contain these topics, they will be replaced with a placeholder message. nullable: true input_topics: type: array items: type: string enum: - platform_integrity_jailbreaking uniqueItems: true description: >- Selected prohibited user topic categories to check. When user messages contain these topics, the agent will respond with a placeholder message instead of processing the request. nullable: true ChatHandbookConfig: type: object description: Behavior presets for chat agents. Voice-only presets are excluded. properties: default_personality: type: boolean description: Professional call center rep baseline. high_empathy: type: boolean description: Warm acknowledgment of caller concerns. ai_disclosure: type: boolean description: When asked, acknowledge being a virtual assistant. scope_boundaries: type: boolean description: Stay within prompt/context scope, don't invent details. PreSessionTool: allOf: - oneOf: - $ref: '#/components/schemas/AppTool' - $ref: '#/components/schemas/CustomTool' - $ref: '#/components/schemas/CodeTool' - type: object properties: depends_on: type: array items: type: string description: Names of tools that must run before this one. description: >- A pre-session tool (app / custom / code, discriminated by type) plus its dependency edges. The tool's name is the depends_on handle and must be unique across the agent's session tools. Parameters may set a constant value or a description for the LLM to infer the value. Pre-session inference uses the agent prompt and dynamic variables. PostSessionTool: allOf: - oneOf: - $ref: '#/components/schemas/AppTool' - $ref: '#/components/schemas/CustomTool' - $ref: '#/components/schemas/CodeTool' - $ref: '#/components/schemas/SendSMSTool' - type: object properties: depends_on: type: array items: type: string description: Names of tools that must run before this one. condition: allOf: - $ref: '#/components/schemas/EquationCondition' description: >- Optional gate; the step only runs when the condition holds. Defaults to always running. description: >- A post-session tool with an optional condition. Parameter inference uses the agent prompt, dynamic variables, and conversation. Same tools as PreSessionTool plus send_sms, which is only supported on phone calls — the session is over, so the speak settings are ignored and an inferred sms_content is written by the LLM from the transcript at teardown. ResponseEngineRetellLm: type: object required: - type - llm_id properties: type: type: string enum: - retell-llm description: type of the Response Engine. llm_id: type: string description: id of the Retell LLM Response Engine. version: type: number example: 0 description: Version of the Retell LLM Response Engine. nullable: true ResponseEngineCustomLm: type: object required: - type - llm_websocket_url properties: type: type: string enum: - custom-llm description: type of the Response Engine. llm_websocket_url: type: string description: LLM websocket url of the custom LLM. ResponseEngineConversationFlow: type: object required: - type - conversation_flow_id properties: type: type: string enum: - conversation-flow description: type of the Response Engine. conversation_flow_id: type: string description: ID of the Conversation Flow Response Engine. version: type: number example: 0 description: Version of the Conversation Flow Response Engine. nullable: true AnalysisData: oneOf: - $ref: '#/components/schemas/StringAnalysisData' - $ref: '#/components/schemas/EnumAnalysisData' - $ref: '#/components/schemas/BooleanAnalysisData' - $ref: '#/components/schemas/NumberAnalysisData' ChatPresetAnalysisData: type: object required: - type - name description: >- System preset for post-chat analysis (chat agents). Use in post_chat_analysis_data to override prompts or mark fields optional. properties: type: type: string enum: - system-presets description: Identifies this item as a system preset. name: type: string enum: - chat_summary - chat_successful - user_sentiment description: Preset identifier for chat agent analysis. example: chat_summary description: type: string minLength: 1 description: Prompt or description for this preset. required: type: boolean description: >- If false, this field is optional in the analysis. If true or unset, the field is required. conditional_prompt: type: string description: >- Optional instruction to help decide whether this field needs to be populated. If not set, the field is always included. AppTool: type: object required: - type - name - app_id - provider - app_tool_template_name properties: type: type: string enum: - integration_app name: type: string description: >- Name of the tool. Must be unique within the phase's tools; referenced by depends_on. app_id: type: string description: >- The connection (App) this tool runs against. Must be a connection in the organization whose provider matches this tool's provider. provider: type: string description: >- Provider of the connection. Must match the connection's provider; supported providers are listed by list-app-templates. app_tool_template_name: type: string description: >- Name of the catalog template within the provider, as listed by list-app-templates. parameters: type: array maxItems: 5 items: $ref: '#/components/schemas/ToolParameter' description: >- The resolved input parameters, in order. Properties may pin a value with const (including {{variable}} references) or provide a description for LLM inference. Each property may also record selected_input_mode, the editor mode the user selected ("const_enum", "const_boolean", "const_value", "description_custom", or "description_preset"); it is stored and returned as-is, used only by the tool config UI. Omit the key when no mode is recorded; when set, const_* modes require a non-empty const, and description_* modes must omit const entirely. Each parameter's required list must match the schema returned by the corresponding step of the get-app-tool-schema loop. response_variables: type: object additionalProperties: type: string example: contact_first_name: data.first_name description: >- Mapping of a dynamic-variable name to the response field (dot-path) it is populated from. Missing paths are ignored. output_selection: $ref: '#/components/schemas/OutputSelection' description: type: string description: >- Only applies to during conversation functions; ignored by the pre/post conversation. Overrides the catalog template's LLM-facing description. speak_during_execution: type: boolean description: >- Only applies to during conversation functions; ignored by the pre/post conversation. If true, will speak during execution. speak_after_execution: type: boolean default: true description: >- Only applies to during conversation functions; ignored by the pre/post conversation. Determines whether the agent would call LLM another time and speak when the result of the tool is obtained. execution_message_description: type: string description: >- Only applies to during conversation functions; ignored by the pre/post conversation. The message for the agent to speak when executing the tool. Only applicable when speak_during_execution is true. execution_message_type: type: string enum: - prompt - static_text description: >- Only applies to during conversation functions; ignored by the pre/post conversation. Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt". enable_typing_sound: type: boolean description: >- Only applies to during conversation functions; ignored by the pre/post conversation. If true, play a typing sound on the agent audio track while this tool is executing. Useful when the tool takes a noticeable amount of time to prevent silence on the call. CustomTool: type: object properties: type: type: string enum: - custom name: type: string description: >- Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed). url: type: string description: >- Describes what the tool does, sometimes can also include information about when to call the tool. description: type: string description: Describes what this tool does and when to call this tool. method: type: string enum: - GET - POST - PUT - PATCH - DELETE description: Method to use for the request, default to POST. headers: type: object additionalProperties: type: string example: Authorization: Bearer 1234567890 description: Headers to add to the request. query_params: type: object additionalProperties: type: string example: page: '1' sort: asc description: Query parameters to append to the request URL. parameters: $ref: '#/components/schemas/ToolParameter' response_variables: type: object additionalProperties: type: string example: user_name: data.user.name description: >- A mapping of variable names to JSON paths in the response body. These values will be extracted from the response and made available as dynamic variables for use. speak_during_execution: type: boolean description: >- Determines whether the agent would say sentence like "One moment, let me check that." when executing the function. Recommend to turn on if your function call takes over 1s (including network) to complete, so that your agent remains responsive. speak_after_execution: type: boolean description: >- Determines whether the agent would call LLM another time and speak when the result of function is obtained. Usually this needs to get turned on so user can get update for the function call. execution_message_description: type: string description: >- The description for the sentence agent say during execution. Only applicable when speak_during_execution is true. Can write what to say or even provide examples. The default is "The message you will say to callee when calling this tool. Make sure it fits into the conversation smoothly.". execution_message_type: type: string enum: - prompt - static_text description: >- Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt". timeout_ms: type: integer minimum: 1000 maximum: 600000 description: >- The maximum time in milliseconds the tool can run before it's considered timeout. If the tool times out, the agent would have that info. The minimum value allowed is 1000 ms (1 s), and maximum value allowed is 600,000 ms (10 min). By default, this is set to 120,000 ms (2 min). max_retry: type: integer minimum: 0 maximum: 5 description: >- Maximum number of times to retry the request after a failed attempt, from 0 (no retry) to 5. Retries happen on any failure, with exponential backoff between attempts; the backoff delay is not configurable. `timeout_ms` applies per attempt rather than as a budget across all attempts, so an attempt that times out is still retried and the worst-case total duration is `timeout_ms` multiplied by (`max_retry` + 1) as well as any latency incurred by the exponential backoff + jitter between each retry. Only the final attempt's result is reported to the agent. Because retries repeat the request, only set this above 0 if your endpoint is idempotent — a retried request may be processed more than once. Defaults to 0 (no retry). args_at_root: type: boolean description: >- If set to true, the parameters will be passed as root level JSON object instead of nested under "args". parameter_type: type: string enum: - json - form description: >- How the tool's `parameters` are authored and shown in the dashboard editor — "form" for the visual parameter builder, "json" for a raw JSON Schema. Both produce the same `parameters` schema; this does not change how the request body is encoded (see `args_at_root`). enable_typing_sound: type: boolean description: >- If true, play a typing sound on the agent audio track while this tool is executing. Useful when the tool takes a noticeable amount of time to prevent silence on the call. required: - type - name - url CodeTool: type: object properties: type: type: string enum: - code name: type: string description: >- Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed). description: type: string description: Describes what this tool does and when to call this tool. code: type: string maxLength: 20000 description: JavaScript code to execute in the sandbox. timeout_ms: type: integer minimum: 5000 maximum: 60000 description: >- The maximum time in milliseconds the code can run before it's considered timeout. Defaults to 30,000 ms (30 s). response_variables: type: object additionalProperties: type: string example: order_id: data.order.id description: >- A mapping of variable names to JSON paths in the code execution result. These mapped values will be extracted and added as dynamic variables. speak_during_execution: type: boolean description: >- Determines whether the agent would say sentence like "One moment, let me check that." when executing the tool. speak_after_execution: type: boolean default: true description: >- Determines whether the agent would call LLM another time and speak when the result of function is obtained. execution_message_description: type: string description: >- The description for the sentence agent say during execution. Only applicable when speak_during_execution is true. execution_message_type: type: string enum: - prompt - static_text description: >- Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt". enable_typing_sound: type: boolean description: >- If true, play a typing sound on the agent audio track while this tool is executing. required: - type - name - code SendSMSTool: type: object properties: name: type: string description: >- Name of the tool. Must be unique within all tools available to LLM at any given time (general tools + state tools + state edges). type: type: string enum: - send_sms description: type: string description: >- Describes what the tool does, sometimes can also include information about when to call the tool. speak_during_execution: type: boolean description: >- If true, the agent will speak a short line before sending the SMS. If omitted, defaults to true (same as end_call / transfer_call tools). execution_message_description: type: string description: >- Describes what to say before sending the SMS. Only applicable when speak_during_execution is true. execution_message_type: type: string enum: - prompt - static_text description: >- Type of execution message. "prompt" means the agent will use execution_message_description as a prompt to generate the message. "static_text" means the agent will speak the execution_message_description directly. Defaults to "prompt". sms_content: $ref: '#/components/schemas/SmsContent' required: - type - name - sms_content EquationCondition: type: object required: - type - equations - operator properties: type: type: string enum: - equation equations: type: array maxItems: 50 items: $ref: '#/components/schemas/Equation' operator: type: string enum: - '||' - '&&' StringAnalysisData: type: object required: - type - name - description properties: type: type: string enum: - string description: Type of the variable to extract. example: string name: type: string description: Name of the variable. example: customer_name minLength: 1 description: type: string description: Description of the variable. example: The name of the customer. examples: type: array items: type: string description: Examples of the variable value to teach model the style and syntax. example: - John Doe - Jane Smith required: type: boolean description: >- Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful. conditional_prompt: type: string description: >- Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored. EnumAnalysisData: type: object required: - type - name - description - choices properties: type: type: string enum: - enum description: Type of the variable to extract. example: enum name: type: string description: Name of the variable. example: product_rating minLength: 1 description: type: string description: Description of the variable. example: Rating of the product. choices: type: array items: type: string description: The possible values of the variable, must be non empty array. example: - good required: type: boolean description: >- Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful. conditional_prompt: type: string description: >- Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored. BooleanAnalysisData: type: object required: - type - name - description properties: type: type: string enum: - boolean description: Type of the variable to extract. example: boolean name: type: string description: Name of the variable. example: is_converted minLength: 1 description: type: string description: Description of the variable. example: Whether the customer converted. required: type: boolean description: >- Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful. conditional_prompt: type: string description: >- Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored. NumberAnalysisData: type: object required: - type - name - description properties: type: type: string enum: - number description: Type of the variable to extract. example: number name: type: string description: Name of the variable. example: order_count minLength: 1 description: type: string description: Description of the variable. example: How many the customer intend to order. required: type: boolean description: >- Whether this data is required. If true and the data is not extracted, the call will be marked as unsuccessful. conditional_prompt: type: string description: >- Optional instruction to help decide whether this field needs to be populated in the analysis. If not set, the field is always included. If required is true, this is ignored. ToolParameter: type: object description: >- The parameters the functions accepts, described as a JSON Schema object. See [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. Omitting parameters defines a function with an empty parameter list. required: - type - properties properties: type: type: string enum: - object description: Type must be "object" for a JSON Schema object. properties: type: object description: >- The value of properties is an object, where each key is the name of a property and each value is a schema used to validate that property. required: type: array items: type: string description: >- List of names of required property when generating this parameter. LLM will do its best to generate the required properties in its function arguments. Property must exist in properties. OutputSelection: description: >- What the agent and the transcript see of the tool's response. Omit to send the full response. Does not affect response_variables, which are always extracted from the raw response. oneOf: - type: object required: - mode properties: mode: type: string enum: - all fields: type: array items: type: string description: Not used at runtime; stored and returned as-is for the UI. - type: object required: - mode - fields properties: mode: type: string enum: - subset fields: type: array items: type: string example: - id - properties.email description: >- The only response fields the agent and the transcript see, as dot-paths into the response schema returned by get-app-tool-schema. Everything else is dropped. Selecting a parent keeps its whole subtree. A plain segment traverses arrays element-wise (deals.properties.amount keeps that field on every deal), while key[n] selects one element (deals[0].id keeps only the first deal's id); paths that match nothing contribute nothing. SmsContent: oneOf: - $ref: '#/components/schemas/SmsContentPredefined' - $ref: '#/components/schemas/SmsContentInferred' - $ref: '#/components/schemas/SmsContentTemplate' Equation: type: object required: - left - operator properties: left: type: string description: Left side of the equation operator: type: string enum: - '==' - '!=' - '>' - '>=' - < - <= - contains - not_contains - exists - not_exist right: type: string description: >- Right side of the equation. The right side of the equation not required when "exists" or "not_exist" are selected. SmsContentPredefined: type: object properties: type: type: string enum: - predefined text: type: string description: >- The static message to be sent in the SMS. Can contain dynamic variables. SmsContentInferred: type: object properties: type: type: string enum: - inferred prompt: type: string description: >- The prompt to be used to help infer the SMS content. The model will take the global prompt, the call transcript, and this prompt together to deduce the right message to send. Can contain dynamic variables. SmsContentTemplate: type: object required: - type - template properties: type: type: string enum: - template template: type: string enum: - info_collection description: >- The template to use for the SMS content. "info_collection" sends a predefined message requesting information from the user. responses: BadRequest: description: Bad Request content: application/json: schema: type: object properties: status: type: string enum: - error message: type: string example: Invalid request format, please check API reference. Unauthorized: description: Unauthorized content: application/json: schema: type: object properties: status: type: string enum: - error message: type: string example: API key is missing or invalid. PaymentRequired: description: Payment Required content: application/json: schema: type: object properties: status: type: string enum: - error message: type: string example: Trial has ended, please add payment method. InternalServerError: description: Internal Server Error content: application/json: schema: type: object properties: status: type: string enum: - error message: type: string example: An unexpected server error occurred. securitySchemes: api_key: type: http scheme: bearer bearerFormat: string description: >- Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY" ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.