Get the most recent webhook events received by the handler.

Args: limit: Maximum number of events to return (default: 10) event_type: Filter events by type (default: all types)

Returns: Dict containing webhook events and metadata

Create a new AI Assistant. The user will provide some details (sometimes detailed, sometimes vague) about the agent they want to create.

Args: name: Required. Name of the assistant. If not provided, will be generated based on context. model: Required. Model to use for the assistant. Defaults to meta-llama/Meta-Llama-3.1-70B-Instruct. instructions: Required. Core instructions or behaviors for the agent. description: Optional. A summary of the agent's purpose. tools: Optional. List of tools for the assistant, each containing: - type: Required. Type of tool ("function", "retrieval", "webhook", "hangup", "send_dtmf", "transfer"). - function: Optional. For function tools, contains: - name: Required. Name of the function. - description: Optional. Description of the function. - parameters: Required. Parameters schema for the function. - retrieval: Optional. For retrieval tools, contains: - bucket_ids: Required. List of bucket IDs for retrieval. - max_num_results: Optional. Maximum number of results to retrieve. - webhook: Optional. For webhook tools, contains: - name: Required. The name of the tool. - description: Required. The description of the tool. - url: Required. The URL of the external tool to be called. This 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. - method: Optional. The HTTP method to be used. Possible values: [GET, POST, PUT, DELETE, PATCH]. Default value: POST. - headers: Optional. Array of header objects with: - name: String name of the header. - value: String value of the header. Supports mustache templating. e.g., Bearer {{#integration_secret}}test-secret{{/integration_secret}}. Secrets can be found in list_integration_secrets - body_parameters: Optional. JSON Schema object describing the body parameters: - properties: Object defining the properties of the body parameters. - required: Array of strings listing required properties. - type: String. Possible value: "object". - path_parameters: Optional. JSON Schema object describing the path parameters: - properties: Object defining the properties of the path parameters. - required: Array of strings listing required properties. - type: String. Possible value: "object". - query_parameters: Optional. JSON Schema object describing the query parameters: - properties: Object defining the properties of the query parameters. - required: Array of strings listing required properties. - type: String. Possible value: "object". - hangup: Optional. For hangup tools, contains: - description: Optional. Description of the hangup function. Defaults to "This tool is used to hang up the call." - send_dtmf: Optional. For DTMF tools, contains an empty object. This tool allows sending DTMF tones during a call. - transfer: Optional. For transfer tools, contains: - targets: Required. Array of transfer targets, each with: - name: Optional. Name of the target. - to: Required. Destination number or SIP URI. - from: Required. Number or SIP URI placing the call. - custom_headers: Optional. Array of custom SIP headers, each with: - name: Required. Name of the header. - value: Required. Value of the header. Supports mustache templating. greeting: Optional. A short welcoming message. Will be generated if not provided. llm_api_key_ref: Optional. LLM API key reference. transcription: Optional. Transcription settings with: - model: Optional. Model to use for transcription. messaging_settings: Optional. Messaging settings with: - default_messaging_profile_id: Optional. Default messaging profile ID. - delivery_status_webhook_url: Optional. Webhook URL for delivery status updates. insight_settings: Optional. Insight settings with: - insight_group_id: Optional. Insight group ID. dynamic_variables_webhook_url: Optional. Dynamic variables webhook URL. dynamic_variables: Optional. Dynamic variables dictionary.

Returns: Dict[str, Any]: Response data

List all AI Assistants.

Returns: Dict[str, Any]: List of assistants

Get an AI Assistant by ID.

Args: assistant_id: Required. Assistant ID. fetch_dynamic_variables_from_webhook: Optional boolean. Whether to fetch dynamic variables from webhook. from_: Optional. From parameter for dynamic variables. to: Optional. To parameter for dynamic variables. call_control_id: Optional. Call control ID for dynamic variables.

Returns: Dict[str, Any]: Response data

Update an AI Assistant. Once there is an agent created, you can talk the user about what can be updated in an easy manner, rather than asking for a long list of fields to update.

Args: assistant_id: Required. ID of the assistant to update. name: Optional. Name of the assistant. model: Optional. Model to use for the assistant. instructions: Optional. Core instructions or behaviors for the agent. description: Optional. A summary of the agent's purpose. tools: Optional. List of tools for the assistant, each containing: - type: Required. Type of tool (ANY of "hangup", "retrieval", "send_dtmf", "transfer", "webhook"). - retrieval: Optional. For retrieval tools, contains: - bucket_ids: Required. List of bucket IDs for retrieval. - max_num_results: Optional. Maximum number of results to retrieve. - webhook: Optional. For webhook tools, contains: - name: Required. The name of the tool. - description: Required. The description of the tool. - url: Required. The URL of the external tool to be called. This 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. - method: Optional. The HTTP method to be used. Possible values: [GET, POST, PUT, DELETE, PATCH]. Default value: POST. - headers: Optional. Array of header objects with: - name: String name of the header. - value: String value of the header. Supports mustache templating, e.g., Bearer {{#integration_secret}}test-secret{{/integration_secret}}. Secrets can be found in list_integration_secrets - body_parameters: Optional. JSON Schema object describing the body parameters: - properties: Object defining the properties of the body parameters. - required: Array of strings listing required properties. - type: String. Possible value: "object". - path_parameters: Optional. JSON Schema object describing the path parameters: - properties: Object defining the properties of the path parameters. - required: Array of strings listing required properties. - type: String. Possible value: "object". - query_parameters: Optional. JSON Schema object describing the query parameters: - properties: Object defining the properties of the query parameters. - required: Array of strings listing required properties. - type: String. Possible value: "object". - hangup: Optional. For hangup tools, contains: - description: Optional. Description of the hangup function. - send_dtmf: Optional. For DTMF tools, contains an empty object. This tool allows sending DTMF tones during a call. - transfer: Optional. For transfer tools, contains: - targets: Required. Array of transfer targets, each with: - name: Optional. Name of the target. - to: Required. Destination number or SIP URI. - from: Required. Number or SIP URI placing the call. - custom_headers: Optional. Array of custom SIP headers, each with: - name: Required. Name of the header. - value: Required. Value of the header. Supports mustache templating. eg: {{#integration_secret}}test-secret{{/integration_secret}} to be used with integration secrets (Available secrets can be found in list_integration_secrets) greeting: Optional. A short welcoming message used by the agent. llm_api_key_ref: Optional. LLM API key reference. This is meant to be used for models provided by external vendors. eg: openai, anthropic, Groq, xai-org. Available secrets can be found in list_integration_secrets transcription: Optional. Transcription settings with: - model: Optional. Model to use for transcription. telephony_settings: Optional. Telephony settings with: - default_texml_app_id: Optional. Default TeXML application ID. messaging_settings: Optional. Messaging settings with: - default_messaging_profile_id: Optional. Default messaging profile ID. - delivery_status_webhook_url: Optional. Webhook URL for delivery status updates. insight_settings: Optional. Insight settings with: - insight_group_id: Optional. Insight group ID. dynamic_variables_webhook_url: Optional. Dynamic variables webhook URL. dynamic_variables: Optional. Dynamic variables dictionary.

Returns: Dict[str, Any]: Response data

Delete an AI Assistant.

Args: id: Assistant ID as string

Returns: Dict[str, Any]: Response data containing deletion status

Get an assistant's TEXML by ID.

Args: assistant_id: Assistant ID

Returns: str: Assistant TEXML content

Start a call using an AI Assistant with a phone number.

Args: assistant_id: Required. ID of the assistant to use for the call. to: Required. Destination phone number to call. from_: Required. Source phone number to call from (must be a number on your Telnyx account).

Returns: Dict[str, Any]: Response data from the call initiation

List call control applications.

Args: page: Optional integer. Page number. Defaults to 1. page_size: Optional integer. Page size. Defaults to 20. filter_application_name_contains: Optional. Filter by application name (case-insensitive, min 3 characters). filter_outbound_voice_profile_id: Optional. Filter by associated outbound voice profile ID. sort: Optional. Sort order for results (created_at, connection_name, active). Defaults to created_at.

Returns: Dict[str, Any]: Response data

Retrieve a specific call control application.

Args: id: Required. Identifies the call control application.

Returns: Dict[str, Any]: Response data

Create a call control application.

Args: application_name: Required. A user-assigned name to help manage the application. webhook_event_url: Required. The URL where webhooks related to this connection will be sent. Must include a scheme, such as 'https'. active: Optional boolean. Specifies whether the connection can be used. Defaults to True. anchorsite_override: Optional. Directs Telnyx to route media through the site with the lowest round-trip time. Defaults to "Latency". dtmf_type: Optional. Sets the type of DTMF digits sent from Telnyx to this Connection. Defaults to "RFC 2833". first_command_timeout: Optional boolean. Specifies whether calls should hangup after timing out. first_command_timeout_secs: Optional integer. Seconds to wait before timing out a dial command. Defaults to 30. inbound: Optional dictionary. Inbound call settings with these possible keys: - channel_limit: Optional integer. Maximum number of concurrent inbound calls. - shaken_stir_enabled: Optional boolean. Enable SHAKEN/STIR verification for inbound calls. - sip_subdomain: Optional string. SIP subdomain for the application. - sip_subdomain_receive_settings: Optional string. Settings for SIP subdomain receiving. outbound: Optional dictionary. Outbound call settings with these possible keys: - channel_limit: Optional integer. Maximum number of concurrent outbound calls. - outbound_voice_profile_id: Optional string. ID of the outbound voice profile to use. webhook_api_version: Optional. Determines which webhook format will be used. Defaults to "1". webhook_event_failover_url: Optional. The failover URL for webhooks if the primary URL fails. webhook_timeout_secs: Optional integer. Seconds to wait before timing out a webhook. Returns: Dict[str, Any]: Response data

Make a call.

Args: to: Required. Destination number or SIP URI. from_: Required. Source number. connection_id: Optional. Connection ID of a call control application to use for the call (same as call_control_application_id).

Returns: Dict[str, Any]: Response data

Hang up a call.

Args: call_control_id: Required. Call control ID.

Returns: Dict[str, Any]: Response data

Start audio playback on a call.

Args: call_control_id: Required. Call control ID. audio_url: Required. URL of audio file to play. loop: Optional. Number of times to loop the audio. Valid values: infinity, 1, 2, 3, 4, 5. overlay: Optional boolean. Whether to overlay the audio on existing audio. Defaults to False. stop: Optional. Which audio to stop. Valid values: current, all. target_legs: Optional. Which leg(s) to play the audio on. Valid values: self, peer, both.

Returns: Dict[str, Any]: Response data

Stop audio playback on a call.

Args: call_control_id: Required. Call control ID. overlay: Optional boolean. Whether to stop overlay audio. Defaults to False. stop: Optional. Which audio to stop. Valid values: current, all.

Returns: Dict[str, Any]: Response data

Send DTMF tones on a call.

Args: call_control_id: Required. Call control ID. digits: Required. DTMF digits to send (0-9, *, #, w, W). duration_millis: Optional integer. Duration of each digit in milliseconds. Defaults to 500.

Returns: Dict[str, Any]: Response data

Speak text on a call using text-to-speech.

Args: call_control_id: Required. Call control ID. payload: Required. Text to speak. voice: Required. Voice to use. Defaults to female payload_type: Optional. Type of payload. Valid values: text, ssml. Defaults to "text". service_level: Optional. Service level for TTS. Valid values: basic, premium. Defaults to "basic". stop: Optional. Which audio to stop. Valid values: current, all. language: Optional. Language code (e.g., 'en-US', 'arb').

Returns: Dict[str, Any]: Response data

Transfer a call to a new destination.

Args: call_control_id: Required. Call control ID. to: Required. Destination number or SIP URI. from_: Required. Source number.

Returns: Dict[str, Any]: Response data

Create a new bucket.

Args: bucket_name: Required. Name of the bucket to create region: Required. Region to create the bucket in (us-east-1, us-west-1, us-central-1) Returns: str: Success!! if it uploaded, otherwise returns an exception message

List all buckets across all regions.

Returns: List[Dict[str, str]]: List of dictionaries containing bucket information: - name: Name of the bucket - region: Region where the bucket is located

Upload a file to cloud storage.

Args: absolute_file_path: Required. Absolute File Path to the file to upload object_name: Optional. Name to give the object in storage (defaults to file name) bucket_name: Optional. Bucket to upload to (defaults to instance default) Returns: str: Success!! if it uploaded, otherwise returns an exception message

Download a file from cloud storage.

Args: object_name: Required. Name of the object to download file_path: Required. Path where to save the downloaded file bucket_name: Optional. Bucket to download from (defaults to instance default) Returns: str: 'Success' if the file was downloaded successfully

List objects in a bucket with optional prefix filtering.

Args: prefix: Optional. Only list objects beginning with this prefix. Defaults to "". bucket_name: Optional. Bucket to list from (defaults to instance default)

Returns: List[str]: List of object names

Delete an object from cloud storage.

Args: object_name: Required. Name of the object to delete bucket_name: Optional. Bucket to delete from (defaults to instance default) Returns: str: 'Success' if the object was deleted successfully

Get the region where a bucket is located.

Args: bucket_name: Optional. Name of the bucket. If None, uses default bucket.

Returns: str: The region where the bucket is located

List connections.

Args: page: Optional integer. Page number. Defaults to 1. page_size: Optional integer. Page size. Defaults to 20. filter_connection_name_contains: Optional. Filter by connection name. filter_outbound_voice_profile_id: Optional. Filter by outbound voice profile ID. sort: Optional. Sort order (created_at, connection_name, active).

Returns: Dict[str, Any]: Response data

Get a connection by ID.

Args: id: Required. Connection ID.

Returns: Dict[str, Any]: Response data

Update a connection.

Note: The Telnyx API does not support updating connections directly. Only GET, HEAD, and OPTIONS methods are allowed. Please create a new connection with the desired settings instead.

Args: id: Required. Connection ID. data: Required. Update data.

Returns: Dict[str, Any]: Response data

Raises: Exception: The Telnyx API does not support updating connections directly.

List user embedded buckets.

Returns: Dict[str, Any]: Response data eg: { "data": { "buckets": [ "string" ] } }

Scrape and embed a given URL. For a given website, this tool will scrape the content of the pages and save the content in a new bucket. That bucket will be automatically embedded.

Args: url: Required. URL to be scraped and embedded.

Returns: Dict[str, Any]: Response data containing bucket information

Embed a bucket that containe files.

Args: bucket_name: Required. Bucket Name. The bucket must exist (string) document_chunk_size: Optional. Document Chunk Size (integer) document_chunk_overlap_size: Optional. Document Chunk Overlap Size (integer) embedding_model: Optional. Supported models (thenlper/gte-large, intfloat/multilingual-e5-large, sentence-transformers/all-mpnet-base-v2) to vectorize and embed documents. loader: Optional. (default, intercom) (string)

Agent should prefer only rely on required fields unless user explicitly provides values for optional fields.

Returns: Dict[str, Any]: Response data containing the embeddings

Send a message.

Args: from_: Required. Sending address (phone number, alphanumeric sender ID, or short code). to: Required. Receiving address(es). text: Required. Message text. messaging_profile_id: Optional. Messaging profile ID. subject: Optional. Message subject. media_urls: Optional. List of media URLs. webhook_url: Optional. Webhook URL. webhook_failover_url: Optional. Webhook failover URL. use_profile_webhooks: Optional boolean. Whether to use profile webhooks. Defaults to True. type: Optional. The protocol for sending the message, either "SMS" or "MMS". auto_detect: Optional boolean. Automatically detect if an SMS message is unusually long.

Returns: Dict[str, Any]: Response data

Retrieve a message by ID.

Args: message_id: The ID of the message to retrieve

Returns: Dict[str, Any]: Response data containing message details

List messaging profiles.

Args: page: Optional integer. Page number. Defaults to 1. page_size: Optional integer. Page size. Defaults to 20. filter_name: Optional. Filter by profile name.

Returns: Dict[str, Any]: Response data

Create a messaging profile.

Args: name: Required. A user friendly name for the messaging profile. whitelisted_destinations: Required. List of destinations to which messages are allowed to be sent (ISO 3166-1 alpha-2 country codes). Use ["*"] to allow all destinations. enabled: Optional boolean. Specifies whether the messaging profile is enabled. Defaults to True. webhook_url: Optional. The URL where webhooks related to this messaging profile will be sent. webhook_failover_url: Optional. The failover URL for webhooks if the primary URL fails. webhook_api_version: Optional. Webhook format version ("1", "2", or "2010-04-01"). Defaults to "2". number_pool_settings: Optional dictionary. Number pool configuration with possible settings: - use_pool: Boolean indicating whether to use number pool. - sticky_sender: Boolean indicating whether to use sticky sender. - pool_weights: Dictionary mapping phone number types to weights. url_shortener_settings: Optional dictionary. URL shortener configuration with possible settings: - enabled: Boolean indicating whether URL shortening is enabled. - domains: List of domains to be shortened. alpha_sender: Optional. The alphanumeric sender ID for destinations requiring it. daily_spend_limit: Optional. Maximum daily spend in USD before midnight UTC. daily_spend_limit_enabled: Optional boolean. Whether to enforce the daily spend limit. mms_fall_back_to_sms: Optional boolean. Enables SMS fallback for MMS messages. mms_transcoding: Optional boolean. Enables automated resizing of MMS media.

Returns: Dict[str, Any]: Response data

Retrieve a messaging profile by ID.

Args: profile_id: The ID of the messaging profile to retrieve

Returns: Dict[str, Any]: Response data containing messaging profile details

Update a messaging profile.

Args: profile_id: Required. The ID of the messaging profile to update. name: Optional. A user friendly name for the messaging profile. enabled: Optional boolean. Specifies whether the messaging profile is enabled. webhook_url: Optional. The URL where webhooks related to this messaging profile will be sent. webhook_failover_url: Optional. The failover URL for webhooks if the primary URL fails. webhook_api_version: Optional. Webhook format version ("1", "2", or "2010-04-01"). whitelisted_destinations: Optional list. Destinations to which messages are allowed (ISO 3166-1 alpha-2 country codes). Use ["*"] to allow all destinations. v1_secret: Optional. Secret used to authenticate with v1 endpoints. number_pool_settings: Optional dictionary. Number pool configuration with possible settings: - use_pool: Boolean indicating whether to use number pool. - sticky_sender: Boolean indicating whether to use sticky sender. - pool_weights: Dictionary mapping phone number types to weights. url_shortener_settings: Optional dictionary. URL shortener configuration with possible settings: - enabled: Boolean indicating whether URL shortening is enabled. - domains: List of domains to be shortened. alpha_sender: Optional. The alphanumeric sender ID for destinations requiring it. daily_spend_limit: Optional. Maximum daily spend in USD before midnight UTC. daily_spend_limit_enabled: Optional boolean. Whether to enforce the daily spend limit. mms_fall_back_to_sms: Optional boolean. Enables SMS fallback for MMS messages. mms_transcoding: Optional boolean. Enables automated resizing of MMS media.

Returns: Dict[str, Any]: Response data

List phone numbers.

Args: page: Optional integer. Page number. Defaults to 1. page_size: Optional integer. Page size. Defaults to 20. filter_tag: Optional. Filter by phone number tag. filter_phone_number: Optional. Filter by phone number. filter_status: Optional. Filter by phone number status. filter_country_iso_alpha2: Optional. Filter by country ISO alpha-2 code.

Returns: Dict[str, Any]: Response data

Get a phone number by ID.

Args: id: Phone number ID as string

Returns: Dict[str, Any]: Response data containing Number Object(s) (record_type: "phone_number")

Update a phone number.

Args: id: Required. Phone number ID. connection_id: Optional. Connection ID to associate with the number. tags: Optional. List of tags to associate with the number.

Returns: Dict[str, Any]: Response data

List available phone numbers.

Args: page: Optional integer. Page number. Defaults to 1. page_size: Optional integer. Page size. Defaults to 20. filter_phone_number_starts_with: Optional. Filter numbers starting with pattern. filter_phone_number_ends_with: Optional. Filter numbers ending with pattern. filter_phone_number_contains: Optional. Filter numbers containing pattern. filter_locality: Optional. Filter by locality (city). filter_administrative_area: Optional. Filter by administrative area (state). filter_country_code: Optional. Filter by country code. filter_features: Optional. List of features to filter by.

Returns: Dict[str, Any]: Response data

Initiate a phone number order.

Args: phone_number: Required. Phone number to buy. connection_id: Optional. Connection ID to associate with the number.

Returns: Dict[str, Any]: Response data

Update the messaging profile and/or messaging product of a phone number.

Args: id: Required. The phone number ID to update. messaging_profile_id: Optional. Configure the messaging profile this phone number is assigned to. Set to null to keep the current value, set to empty string to unassign, or set to a UUID to assign to that messaging profile. messaging_product: Optional. Configure the messaging product for this number. Set to null to keep the current value, or set to a product ID to change.

Returns: Dict[str, Any]: Response data

List integration secrets.

Args: page: Optional integer. Page number. Defaults to 1. page_size: Optional integer. Page size. Defaults to 25. filter_type: Optional. Filter by secret type (bearer, basic).

Returns: Dict[str, Any]: Response data containing Integration Secret Object(s) (record_type: "integration_secret")

Create an integration secret.

Args: identifier: Required. The unique identifier of the secret. type: Required. The type of secret (bearer, basic). token: Optional. The token for the secret (required for bearer type). username: Optional. The username for the secret (required for basic type). password: Optional. The password for the secret (required for basic type).

Returns: Dict[str, Any]: Response data containing the created Integration Secret Object (record_type: "integration_secret")

Delete an integration secret.

Args: id: Required. Secret ID.

Returns: Dict[str, Any]: Empty response on success