team-telnyx Telnyx Ai Assistants - Python
Installation
pip install telnyx
Setup
import os
from telnyx import Telnyx
client = Telnyx(
api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted
)
All examples below assume client is already initialized as shown above.
List assistants
Retrieve a list of all AI Assistants configured by the user.
GET /ai/assistants
assistants_list = client.ai.assistants.list()
print(assistants_list.data)
Create an assistant
Create a new AI Assistant.
POST /ai/assistants — Required: name, model, instructions
assistant = client.ai.assistants.create(
instructions="instructions",
model="model",
name="name",
)
print(assistant.id)
Get an assistant
Retrieve an AI Assistant configuration by assistant_id.
GET /ai/assistants/{assistant_id}
assistant = client.ai.assistants.retrieve(
assistant_id="assistant_id",
)
print(assistant.id)
Update an assistant
Update an AI Assistant's attributes.
POST /ai/assistants/{assistant_id}
assistant = client.ai.assistants.update(
assistant_id="assistant_id",
)
print(assistant.id)
Delete an assistant
Delete an AI Assistant by assistant_id.
DELETE /ai/assistants/{assistant_id}
assistant = client.ai.assistants.delete(
"assistant_id",
)
print(assistant.id)
Assistant Chat (BETA)
This endpoint allows a client to send a chat message to a specific AI Assistant.
POST /ai/assistants/{assistant_id}/chat — Required: content, conversation_id
response = client.ai.assistants.chat(
assistant_id="assistant_id",
content="Tell me a joke about cats",
conversation_id="42b20469-1215-4a9a-8964-c36f66b406f4",
)
print(response.content)
Assistant Sms Chat
Send an SMS message for an assistant.
POST /ai/assistants/{assistant_id}/chat/sms — Required: from, to
response = client.ai.assistants.send_sms(
assistant_id="assistant_id",
from_="from",
to="to",
)
print(response.conversation_id)
Clone Assistant
Clone an existing assistant, excluding telephony and messaging settings.
POST /ai/assistants/{assistant_id}/clone
assistant = client.ai.assistants.clone(
"assistant_id",
)
print(assistant.id)
Import assistants from external provider
Import assistants from external providers.
POST /ai/assistants/import — Required: provider, api_key_ref
assistants_list = client.ai.assistants.imports(
api_key_ref="api_key_ref",
provider="elevenlabs",
)
print(assistants_list.data)
List scheduled events
Get scheduled events for an assistant with pagination and filtering
GET /ai/assistants/{assistant_id}/scheduled_events
page = client.ai.assistants.scheduled_events.list(
assistant_id="assistant_id",
)
page = page.data[0]
print(page)
Create a scheduled event
Create a scheduled event for an assistant
POST /ai/assistants/{assistant_id}/scheduled_events — Required: telnyx_conversation_channel, telnyx_end_user_target, telnyx_agent_target, scheduled_at_fixed_datetime
from datetime import datetime
scheduled_event_response = client.ai.assistants.scheduled_events.create(
assistant_id="assistant_id",
scheduled_at_fixed_datetime=datetime.fromisoformat("2025-04-15T13:07:28.764"),
telnyx_agent_target="telnyx_agent_target",
telnyx_conversation_channel="phone_call",
telnyx_end_user_target="telnyx_end_user_target",
)
print(scheduled_event_response)
Get a scheduled event
Retrieve a scheduled event by event ID
GET /ai/assistants/{assistant_id}/scheduled_events/{event_id}
scheduled_event_response = client.ai.assistants.scheduled_events.retrieve(
event_id="event_id",
assistant_id="assistant_id",
)
print(scheduled_event_response)
Delete a scheduled event
If the event is pending, this will cancel the event.
DELETE /ai/assistants/{assistant_id}/scheduled_events/{event_id}
client.ai.assistants.scheduled_events.delete(
event_id="event_id",
assistant_id="assistant_id",
)
List assistant tests with pagination
Retrieves a paginated list of assistant tests with optional filtering capabilities
GET /ai/assistants/tests
page = client.ai.assistants.tests.list()
page = page.data[0]
print(page.test_id)
Create a new assistant test
Creates a comprehensive test configuration for evaluating AI assistant performance
POST /ai/assistants/tests — Required: name, destination, instructions, rubric
assistant_test = client.ai.assistants.tests.create(
destination="+15551234567",
instructions="Act as a frustrated customer who received a damaged product. Ask for a refund and escalate if not satisfied with the initial response.",
name="Customer Support Bot Test",
rubric=[{
"criteria": "Assistant responds within 30 seconds",
"name": "Response Time",
}, {
"criteria": "Provides correct product information",
"name": "Accuracy",
}],
)
print(assistant_test.test_id)
Get all test suite names
Retrieves a list of all distinct test suite names available to the current user
GET /ai/assistants/tests/test-suites
test_suites = client.ai.assistants.tests.test_suites.list()
print(test_suites.data)
Get test suite run history
Retrieves paginated history of test runs for a specific test suite with filtering options
GET /ai/assistants/tests/test-suites/{suite_name}/runs
page = client.ai.assistants.tests.test_suites.runs.list(
suite_name="suite_name",
)
page = page.data[0]
print(page.run_id)
Trigger test suite execution
Executes all tests within a specific test suite as a batch operation
POST /ai/assistants/tests/test-suites/{suite_name}/runs
test_run_responses = client.ai.assistants.tests.test_suites.runs.trigger(
suite_name="suite_name",
)
print(test_run_responses)
Get assistant test by ID
Retrieves detailed information about a specific assistant test
GET /ai/assistants/tests/{test_id}
assistant_test = client.ai.assistants.tests.retrieve(
"test_id",
)
print(assistant_test.test_id)
Update an assistant test
Updates an existing assistant test configuration with new settings
PUT /ai/assistants/tests/{test_id}
assistant_test = client.ai.assistants.tests.update(
test_id="test_id",
)
print(assistant_test.test_id)
Delete an assistant test
Permanently removes an assistant test and all associated data
DELETE /ai/assistants/tests/{test_id}
client.ai.assistants.tests.delete(
"test_id",
)
Get test run history for a specific test
Retrieves paginated execution history for a specific assistant test with filtering options
GET /ai/assistants/tests/{test_id}/runs
page = client.ai.assistants.tests.runs.list(
test_id="test_id",
)
page = page.data[0]
print(page.run_id)
Trigger a manual test run
Initiates immediate execution of a specific assistant test
POST /ai/assistants/tests/{test_id}/runs
test_run_response = client.ai.assistants.tests.runs.trigger(
test_id="test_id",
)
print(test_run_response.run_id)
Get specific test run details
Retrieves detailed information about a specific test run execution
GET /ai/assistants/tests/{test_id}/runs/{run_id}
test_run_response = client.ai.assistants.tests.runs.retrieve(
run_id="run_id",
test_id="test_id",
)
print(test_run_response.run_id)
Get all versions of an assistant
Retrieves all versions of a specific assistant with complete configuration and metadata
GET /ai/assistants/{assistant_id}/versions
assistants_list = client.ai.assistants.versions.list(
"assistant_id",
)
print(assistants_list.data)
Get a specific assistant version
Retrieves a specific version of an assistant by assistant_id and version_id
GET /ai/assistants/{assistant_id}/versions/{version_id}
assistant = client.ai.assistants.versions.retrieve(
version_id="version_id",
assistant_id="assistant_id",
)
print(assistant.id)
Update a specific assistant version
Updates the configuration of a specific assistant version.
POST /ai/assistants/{assistant_id}/versions/{version_id}
assistant = client.ai.assistants.versions.update(
version_id="version_id",
assistant_id="assistant_id",
)
print(assistant.id)
Delete a specific assistant version
Permanently removes a specific version of an assistant.
DELETE /ai/assistants/{assistant_id}/versions/{version_id}
client.ai.assistants.versions.delete(
version_id="version_id",
assistant_id="assistant_id",
)
Promote an assistant version to main
Promotes a specific version to be the main/current version of the assistant.
POST /ai/assistants/{assistant_id}/versions/{version_id}/promote
assistant = client.ai.assistants.versions.promote(
version_id="version_id",
assistant_id="assistant_id",
)
print(assistant.id)
Get Canary Deploy
Endpoint to get a canary deploy configuration for an assistant.
GET /ai/assistants/{assistant_id}/canary-deploys
canary_deploy_response = client.ai.assistants.canary_deploys.retrieve(
"assistant_id",
)
print(canary_deploy_response.assistant_id)
Create Canary Deploy
Endpoint to create a canary deploy configuration for an assistant.
POST /ai/assistants/{assistant_id}/canary-deploys — Required: versions
canary_deploy_response = client.ai.assistants.canary_deploys.create(
assistant_id="assistant_id",
versions=[{
"percentage": 1,
"version_id": "version_id",
}],
)
print(canary_deploy_response.assistant_id)
Update Canary Deploy
Endpoint to update a canary deploy configuration for an assistant.
PUT /ai/assistants/{assistant_id}/canary-deploys — Required: versions
canary_deploy_response = client.ai.assistants.canary_deploys.update(
assistant_id="assistant_id",
versions=[{
"percentage": 1,
"version_id": "version_id",
}],
)
print(canary_deploy_response.assistant_id)
Delete Canary Deploy
Endpoint to delete a canary deploy configuration for an assistant.
DELETE /ai/assistants/{assistant_id}/canary-deploys
client.ai.assistants.canary_deploys.delete(
"assistant_id",
)
Get assistant texml
Get an assistant texml by assistant_id.
GET /ai/assistants/{assistant_id}/texml
response = client.ai.assistants.get_texml(
"assistant_id",
)
print(response)
Test Assistant Tool
Test a webhook tool for an assistant
POST /ai/assistants/{assistant_id}/tools/{tool_id}/test
response = client.ai.assistants.tools.test(
tool_id="tool_id",
assistant_id="assistant_id",
)
print(response.data)
List Integrations
List all available integrations.
GET /ai/integrations
integrations = client.ai.integrations.list()
print(integrations.data)
List User Integrations
List user setup integrations
GET /ai/integrations/connections
connections = client.ai.integrations.connections.list()
print(connections.data)
Get User Integration connection By Id
Get user setup integrations
GET /ai/integrations/connections/{user_connection_id}
connection = client.ai.integrations.connections.retrieve(
"user_connection_id",
)
print(connection.data)
Delete Integration Connection
Delete a specific integration connection.
DELETE /ai/integrations/connections/{user_connection_id}
client.ai.integrations.connections.delete(
"user_connection_id",
)
List Integration By Id
Retrieve integration details
GET /ai/integrations/{integration_id}
integration = client.ai.integrations.retrieve(
"integration_id",
)
print(integration.id)
List MCP Servers
Retrieve a list of MCP servers.
GET /ai/mcp_servers
page = client.ai.mcp_servers.list()
page = page.items[0]
print(page.id)
Create MCP Server
Create a new MCP server.
POST /ai/mcp_servers — Required: name, type, url
mcp_server = client.ai.mcp_servers.create(
name="name",
type="type",
url="url",
)
print(mcp_server.id)
Get MCP Server
Retrieve details for a specific MCP server.
GET /ai/mcp_servers/{mcp_server_id}
mcp_server = client.ai.mcp_servers.retrieve(
"mcp_server_id",
)
print(mcp_server.id)
Update MCP Server
Update an existing MCP server.
PUT /ai/mcp_servers/{mcp_server_id}
mcp_server = client.ai.mcp_servers.update(
mcp_server_id="mcp_server_id",
)
print(mcp_server.id)
Delete MCP Server
Delete a specific MCP server.
DELETE /ai/mcp_servers/{mcp_server_id}
client.ai.mcp_servers.delete(
"mcp_server_id",
)