| get_webhook_events | 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_assistant | 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_assistants | List all AI Assistants. Returns:
Dict[str, Any]: List of assistants
|
| get_assistant | 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_assistant | 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
|
| mcp_telnyx_delete_assistant | Delete an AI Assistant. Args:
id: Assistant ID as string
Returns:
Dict[str, Any]: Response data containing deletion status
|
| get_assistant_texml | Get an assistant's TEXML by ID. Args:
assistant_id: Assistant ID
Returns:
str: Assistant TEXML content
|
| start_assistant_call | 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 | 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
|
| get_call_control_application | Retrieve a specific call control application. Args:
id: Required. Identifies the call control application.
Returns:
Dict[str, Any]: Response data
|
| create_call_control_application | 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_call | 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
|
| hangup | Hang up a call. Args:
call_control_id: Required. Call control ID.
Returns:
Dict[str, Any]: Response data
|
| playback_start | 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
|
| playback_stop | 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 | 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 | 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 | 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
|
| cloud_storage_create_bucket | 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
|
| cloud_storage_list_buckets | 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
|
| cloud_storage_upload_file | 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
|
| cloud_storage_download_file | 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
|
| cloud_storage_list_objects | 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
|
| cloud_storage_delete_object | 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
|
| cloud_storage_get_bucket_location | 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 | 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_connection | Get a connection by ID. Args:
id: Required. Connection ID.
Returns:
Dict[str, Any]: Response data
|
| update_connection | 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_embedded_buckets | List user embedded buckets. Returns:
Dict[str, Any]: Response data eg:
{
"data": {
"buckets": [
"string"
]
}
}
|
| embed_url | 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
|
| create_embeddings | 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_message | 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
|
| get_message | 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 | 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_messaging_profile | 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
|
| get_messaging_profile | 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_messaging_profile | 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 | 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_phone_number | 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_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 | 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_phone_number_order | 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_phone_number_messaging_settings | 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 | 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_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_integration_secret | Delete an integration secret. Args:
id: Required. Secret ID.
Returns:
Dict[str, Any]: Empty response on success
|
