> ## Documentation Index > Fetch the complete documentation index at: https://docs.threetone.in/llms.txt > Use this file to discover all available pages before exploring further. # Handle An Outbound Call Via Sip Trunk > Handle an outbound call via SIP trunk ## OpenAPI ````yaml /api-reference/openapi.json post /v1/convai/sip-trunk/outbound-call openapi: 3.1.0 info: title: Threetone API Documentation description: >- This is the documentation for the Threetone API. You can use this API to use our service programmatically with API keys sent in the x-api-key header. You can create and manage API keys in the dashboard at https://threetone.in/app/developers/api-keys. version: '1.0' servers: - url: https://api.threetone.in description: Production security: [] paths: /v1/convai/sip-trunk/outbound-call: post: tags: - Agents Platform summary: Handle An Outbound Call Via Sip Trunk description: Handle an outbound call via SIP trunk operationId: handle_sip_trunk_outbound_call parameters: - name: x-api-key in: header required: false schema: anyOf: - type: string - type: 'null' description: >- Your API key for programmatic access. Send it in the x-api-key header; you can create and manage keys from the Developers page. title: X-Api-Key description: >- Your API key for programmatic access. Send it in the x-api-key header; you can create and manage keys from the Developers page. requestBody: required: true content: application/json: schema: $ref: >- #/components/schemas/Body_Handle_an_outbound_call_via_SIP_trunk_v1_convai_sip_trunk_outbound_call_post responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SIPTrunkOutboundCallResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: Body_Handle_an_outbound_call_via_SIP_trunk_v1_convai_sip_trunk_outbound_call_post: properties: agent_id: type: string title: Agent Id agent_phone_number_id: type: string title: Agent Phone Number Id to_number: type: string title: To Number conversation_initiation_client_data: anyOf: - $ref: '#/components/schemas/ConversationInitiationClientDataRequest' - type: 'null' telephony_call_config: $ref: '#/components/schemas/TelephonyCallConfig' default: ringing_timeout_secs: 60 twilio_call_recording_enabled: false type: object required: - agent_id - agent_phone_number_id - to_number title: >- Body_Handle_an_outbound_call_via_SIP_trunk_v1_convai_sip_trunk_outbound_call_post SIPTrunkOutboundCallResponse: properties: success: type: boolean title: Success message: type: string title: Message conversation_id: anyOf: - type: string - type: 'null' title: Conversation Id sip_call_id: anyOf: - type: string - type: 'null' title: Sip Call Id type: object required: - success - message - conversation_id - sip_call_id title: SIPTrunkOutboundCallResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ConversationInitiationClientDataRequest: properties: conversation_config_override: $ref: '#/components/schemas/ConversationConfigClientOverride' custom_llm_extra_body: additionalProperties: true type: object title: Custom Llm Extra Body user_id: anyOf: - type: string - type: 'null' title: User Id description: >- ID of the end user participating in this conversation (for agent owner's user identification) source_info: $ref: '#/components/schemas/ConversationInitiationSourceInfo' branch_id: anyOf: - type: string - type: 'null' title: Branch Id description: ID of the agent branch to use for this conversation environment: anyOf: - type: string - type: 'null' title: Environment description: Environment to use for resolving environment variables starting_workflow_node_id: anyOf: - type: string - type: 'null' title: Starting Workflow Node Id description: >- If set, start the workflow at this node id instead of the default entry procedure_ids: anyOf: - items: type: string type: array - type: 'null' title: Procedure Ids description: >- If set, only these procedures are available to the starting agent. Each ID must be attached to that agent; unknown IDs fail conversation start. An empty list disables all of that agent's procedures. Not applied after an agent transfer. Requires enable_procedure_ids_from_client. dynamic_variables: additionalProperties: true type: object title: Dynamic Variables type: object title: ConversationInitiationClientDataRequest TelephonyCallConfig: properties: ringing_timeout_secs: type: integer maximum: 999 minimum: 1 title: Ringing Timeout Secs description: >- How long to ring the recipient before giving up, in seconds. Note that this will also be limited by the provider's own constraints. default: 60 twilio_call_recording_enabled: type: boolean title: Twilio Call Recording Enabled description: >- Whether to record the call using Twilio call recording. Ignored for non-Twilio providers. Recordings are stored in your Twilio account. default: false twilio_machine_detection: anyOf: - $ref: '#/components/schemas/TwilioMachineDetectionConfig' - type: 'null' description: >- Configuration for Twilio's carrier-level answering machine detection (AMD). Omit or set to null to disable it. Ignored for non-Twilio providers and for inbound calls. The resulting verdict is delivered as its own `answering_machine_detection` webhook event, which requires that event to be enabled on the workspace or agent webhook settings; it is not part of the conversation or the post-call webhook. Detection runs asynchronously so it never delays the start of the conversation, and the verdict can arrive at any point during the call -- with `detect_message_end`, even after it has ended. Twilio bills separately for AMD. type: object title: TelephonyCallConfig ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError ConversationConfigClientOverride: properties: turn: anyOf: - $ref: '#/components/schemas/TurnConfigOverride' - type: 'null' description: Configuration for turn detection tts: anyOf: - $ref: '#/components/schemas/TTSConversationalConfigOverride' - type: 'null' description: Configuration for conversational text to speech conversation: anyOf: - $ref: '#/components/schemas/ConversationConfigOverride' - type: 'null' description: Configuration for conversational events agent: anyOf: - $ref: '#/components/schemas/AgentConfigOverride' - type: 'null' description: Agent specific configuration type: object title: ConversationConfigClientOverride example: agent: first_message: Hello, how can I help you today? language: en prompt: knowledge_base: [] llm: gemini-2.0-flash-001 prompt: >- You are a helpful assistant that can answer questions about the topic of the conversation. tool_ids: [] tts: performance: latency voice_id: ME9RtCnWp5vX2LhJdF3k ConversationInitiationSourceInfo: properties: source: anyOf: - $ref: '#/components/schemas/ConversationInitiationSource' - type: 'null' description: Source of the conversation initiation version: anyOf: - type: string maxLength: 50 - type: 'null' title: Version description: The SDK version number type: object title: ConversationInitiationSourceInfo description: Information about the source of conversation initiation TwilioMachineDetectionConfig: properties: mode: $ref: '#/components/schemas/TwilioMachineDetectionMode' description: >- How thorough the detection should be. `enable` returns a verdict as soon as Twilio can tell a human from a machine. `detect_message_end` also waits for the voicemail greeting to finish, which is what produces the `machine_end_*` verdicts, but returns a result later. default: enable type: object title: TwilioMachineDetectionConfig description: >- How to run Twilio's carrier-level answering machine detection (AMD) on a call. TurnConfigOverride: properties: soft_timeout_config: anyOf: - $ref: '#/components/schemas/SoftTimeoutConfigOverride' - type: 'null' description: >- Configuration for soft timeout functionality. Provides immediate feedback during longer LLM responses. type: object title: TurnConfigOverride example: soft_timeout_config: message: Hhmmmm...yeah. TTSConversationalConfigOverride: properties: voice_id: type: string title: Voice Id description: The voice ID to use for TTS performance: $ref: '#/components/schemas/TTSPerformance' description: >- User-facing TTS performance tier (latency or quality). The concrete provider/model is selected by the voice-server based on this value. pronunciation_dictionary_locators: anyOf: - items: $ref: >- #/components/schemas/PydanticPronunciationDictionaryVersionLocator type: array - type: 'null' title: Pronunciation Dictionary Locators description: The pronunciation dictionary locators x-convai-client-override: true type: object title: TTSConversationalConfigOverride ConversationConfigOverride: properties: text_only: anyOf: - type: boolean - type: 'null' title: Text Only description: >- If enabled audio will not be processed and only text will be used, use to avoid audio pricing. x-convai-client-override: true max_duration_seconds: anyOf: - type: integer - type: 'null' title: Max Duration Seconds description: The maximum duration of a conversation in seconds x-convai-client-override: true type: object title: ConversationConfigOverride example: max_duration_seconds: 600 AgentConfigOverride: properties: first_message: anyOf: - type: string - type: 'null' title: First Message description: >- If non-empty, the first message the agent will say. If empty, the agent waits for the user to start the discussion. x-convai-client-override: true x-convai-language-override: true language: anyOf: - type: string - type: 'null' title: Language description: Language of the agent - used for ASR and TTS x-convai-client-override: true max_conversation_duration_message: anyOf: - type: string - type: 'null' title: Max Conversation Duration Message description: >- If non-empty, the message the agent will send when max conversation duration is reached. x-convai-client-override: true x-convai-language-override: true prompt: anyOf: - $ref: '#/components/schemas/PromptAgentAPIModelOverride' - type: 'null' description: The prompt for the agent type: object title: AgentConfigOverride example: first_message: Hello, how can I help you today? language: en prompt: knowledge_base: [] llm: gemini-2.0-flash-001 prompt: >- You are a helpful assistant that can answer questions about the topic of the conversation. tool_ids: [] ConversationInitiationSource: type: string enum: - unknown - android_sdk - node_js_sdk - react_native_sdk - react_sdk - js_sdk - python_sdk - widget - sip_trunk - twilio - exotel - genesys - avaya - audiocodes - swift_sdk - whatsapp - twilio_sms - flutter_sdk - zendesk_integration - slack_integration - telegram_integration - intercom_integration - freshdesk_integration - salesforce_integration - template_preview - genesys_bot_connector - subagent_tool title: ConversationInitiationSource description: Enum representing the possible sources for conversation initiation. default: unknown TwilioMachineDetectionMode: type: string enum: - enable - detect_message_end title: TwilioMachineDetectionMode description: >- Which Twilio answering-machine-detection (AMD) mode to request for a call. `enable` returns a verdict as soon as Twilio can tell a human from a machine. `detect_message_end` additionally waits for the greeting to finish, which is what distinguishes the `machine_end_*` verdicts, at the cost of a later result. SoftTimeoutConfigOverride: properties: message: anyOf: - type: string - type: 'null' title: Message description: >- Message to show when the first soft timeout is reached while waiting for LLM response. Supports dynamic variables (e.g., {{system__time}}, {{custom_variable}}). x-convai-client-override: true x-convai-language-override: true additional_soft_timeout_messages: anyOf: - items: type: string type: array - type: 'null' title: Additional Soft Timeout Messages description: >- Extra static filler messages for subsequent soft timeouts in the same LLM generation. The first timeout uses `message`. If fewer messages are configured than `max_soft_timeouts_per_generation`, the last configured message is repeated; otherwise a built-in filler is used. x-convai-client-override: true x-convai-language-override: true type: object title: SoftTimeoutConfigOverride example: message: Hhmmmm...yeah. TTSPerformance: type: string enum: - latency - quality title: TTSPerformance description: |- User-facing TTS performance tier. Decouples the UI from vendor names. latency -> optimized for response speed (currently Cartesia Sonic). quality -> optimized for expressiveness (currently ElevenLabs v3). PydanticPronunciationDictionaryVersionLocator: properties: pronunciation_dictionary_id: type: string title: Pronunciation Dictionary Id description: The ID of the pronunciation dictionary version_id: anyOf: - type: string - type: 'null' title: Version Id description: The ID of the version of the pronunciation dictionary type: object required: - pronunciation_dictionary_id - version_id title: PydanticPronunciationDictionaryVersionLocator description: >- A locator for other documents to be able to reference a specific dictionary and it's version. This is a pydantic version of PronunciationDictionaryVersionLocatorDBModel. Required to ensure compat with the rest of the agent data models. PromptAgentAPIModelOverride: properties: prompt: anyOf: - type: string - type: 'null' title: Prompt description: The prompt for the agent x-convai-client-override: true llm: anyOf: - $ref: '#/components/schemas/LLM' - type: 'null' description: >- The LLM to query with the prompt and the chat history. If using data residency, the LLM must be supported in the data residency environment x-convai-client-override: true tool_ids: anyOf: - items: type: string type: array - type: 'null' title: Tool Ids description: A list of IDs of tools used by the agent x-convai-client-override: true native_mcp_server_ids: anyOf: - items: type: string type: array - type: 'null' title: Native Mcp Server Ids description: A list of Native MCP server ids to be used by the agent x-convai-client-override: true knowledge_base: anyOf: - items: $ref: '#/components/schemas/KnowledgeBaseLocator' type: array - type: 'null' title: Knowledge Base description: A list of knowledge bases to be used by the agent x-convai-client-override: true type: object title: PromptAgentAPIModelOverride example: knowledge_base: [] llm: gemini-2.0-flash-001 prompt: >- You are a helpful assistant that can answer questions about the topic of the conversation. tool_ids: [] LLM: type: string enum: - gpt-4o-mini - gpt-4o - gpt-4 - gpt-4-turbo - gpt-4.1 - gpt-4.1-mini - gpt-4.1-nano - gpt-5 - gpt-5.1 - gpt-5.2 - gpt-5.2-chat-latest - gpt-5.4 - gpt-5.5 - gpt-5.6-sol - gpt-5.6-terra - gpt-5.6-luna - gpt-5-mini - gpt-5-nano - gpt-3.5-turbo - gemini-1.5-pro - gemini-1.5-flash - gemini-2.0-flash - gemini-2.0-flash-lite - gemini-2.5-flash-lite - gemini-2.5-flash - gemini-3-pro-preview - gemini-3-flash-preview - gemini-3.1-pro-preview - gemini-3.1-flash-lite-preview - gemini-3.6-flash - gemini-3.7-flash - claude-sonnet-4-5 - claude-opus-4-7 - claude-sonnet-4-6 - claude-sonnet-4 - claude-haiku-4-5 - claude-3-7-sonnet - claude-3-5-sonnet - claude-3-5-sonnet-v1 - claude-3-haiku - grok-beta - custom-llm - qwen3-4b - qwen3-30b-a3b - qwen36-35b-a3b - gpt-oss-20b - gpt-oss-120b - glm-45-air-fp8 - gemini-2.5-flash-preview-09-2025 - gemini-2.5-flash-lite-preview-09-2025 - gemini-2.5-flash-preview-05-20 - gemini-2.5-flash-preview-04-17 - gemini-2.5-flash-lite-preview-06-17 - gemini-2.0-flash-lite-001 - gemini-2.0-flash-001 - gemini-1.5-flash-002 - gemini-1.5-flash-001 - gemini-1.5-pro-002 - gemini-1.5-pro-001 - claude-sonnet-4@20250514 - claude-sonnet-4-5@20250929 - claude-haiku-4-5@20251001 - claude-3-7-sonnet@20250219 - claude-3-5-sonnet@20240620 - claude-3-5-sonnet-v2@20241022 - claude-3-haiku@20240307 - gpt-5-2025-08-07 - gpt-5.1-2025-11-13 - gpt-5.2-2025-12-11 - gpt-5.4-2026-03-05 - gpt-5.5-2026-04-23 - gpt-5-mini-2025-08-07 - gpt-5-nano-2025-08-07 - gpt-4.1-2025-04-14 - gpt-4.1-mini-2025-04-14 - gpt-4.1-nano-2025-04-14 - gpt-4o-mini-2024-07-18 - gpt-4o-2024-11-20 - gpt-4o-2024-08-06 - gpt-4o-2024-05-13 - gpt-4-0613 - gpt-4-0314 - gpt-4-turbo-2024-04-09 - gpt-3.5-turbo-0125 - gpt-3.5-turbo-1106 - watt-tool-8b - watt-tool-70b title: LLM KnowledgeBaseLocator: properties: type: $ref: '#/components/schemas/KnowledgeBaseDocumentType' description: The type of the knowledge base name: type: string title: Name description: The name of the knowledge base id: type: string title: Id description: The ID of the knowledge base usage_mode: $ref: '#/components/schemas/DocumentUsageModeEnum' description: The usage mode of the knowledge base default: auto type: object required: - type - name - id title: KnowledgeBaseLocator example: id: '123' name: My Knowledge Base type: file usage_mode: auto KnowledgeBaseDocumentType: type: string enum: - file - url - text - folder title: KnowledgeBaseDocumentType DocumentUsageModeEnum: type: string enum: - prompt - auto title: DocumentUsageModeEnum default: auto ````