Telnyx Ai Assistants Python

---
name: telnyx-ai-assistants-python
description: >-
  Create and manage AI voice assistants with custom personalities, knowledge
  bases, and tool integrations. This skill provides Python SDK examples.
metadata:
  author: telnyx
  product: ai-assistants
  language: python
---

# Telnyx Ai Assistants - Python

## Installation

```bash
pip install telnyx
```

## Setup

```python
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`

```python
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`

```python
inference_embedding = client.ai.assistants.create(
    instructions="instructions",
    model="model",
    name="name",
)
print(inference_embedding.id)
```

## Get an assistant

Retrieve an AI Assistant configuration by `assistant_id`.

`GET /ai/assistants/{assistant_id}`

```python
inference_embedding = client.ai.assistants.retrieve(
    assistant_id="assistant_id",
)
print(inference_embedding.id)
```

## Update an assistant

Update an AI Assistant's attributes.

`POST /ai/assistants/{assistant_id}`

```python
inference_embedding = client.ai.assistants.update(
    assistant_id="assistant_id",
)
print(inference_embedding.id)
```

## Delete an assistant

Delete an AI Assistant by `assistant_id`.

`DELETE /ai/assistants/{assistant_id}`

```python
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`

```python
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`

```python
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`

```python
inference_embedding = client.ai.assistants.clone(
    "assistant_id",
)
print(inference_embedding.id)
```

## Import assistants from external provider

Import assistants from external providers.

`POST /ai/assistants/import` — Required: `provider`, `api_key_ref`

```python
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`

```python
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`

```python
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}`

```python
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}`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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}`

```python
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}`

```python
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}`

```python
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`

```python
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`

```python
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}`

```python
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`

```python
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}`

```python
inference_embedding = client.ai.assistants.versions.retrieve(
    version_id="version_id",
    assistant_id="assistant_id",
)
print(inference_embedding.id)
```

## Update a specific assistant version

Updates the configuration of a specific assistant version.

`POST /ai/assistants/{assistant_id}/versions/{version_id}`

```python
inference_embedding = client.ai.assistants.versions.update(
    version_id="version_id",
    assistant_id="assistant_id",
)
print(inference_embedding.id)
```

## Delete a specific assistant version

Permanently removes a specific version of an assistant.

`DELETE /ai/assistants/{assistant_id}/versions/{version_id}`

```python
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`

```python
inference_embedding = client.ai.assistants.versions.promote(
    version_id="version_id",
    assistant_id="assistant_id",
)
print(inference_embedding.id)
```

## Get Canary Deploy

Endpoint to get a canary deploy configuration for an assistant.

`GET /ai/assistants/{assistant_id}/canary-deploys`

```python
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`

```python
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`

```python
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`

```python
client.ai.assistants.canary_deploys.delete(
    "assistant_id",
)
```

## Get assistant texml

Get an assistant texml by `assistant_id`.

`GET /ai/assistants/{assistant_id}/texml`

```python
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`

```python
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`

```python
integrations = client.ai.integrations.list()
print(integrations.data)
```

## List User Integrations

List user setup integrations

`GET /ai/integrations/connections`

```python
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}`

```python
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}`

```python
client.ai.integrations.connections.delete(
    "user_connection_id",
)
```

## List Integration By Id

Retrieve integration details

`GET /ai/integrations/{integration_id}`

```python
integration = client.ai.integrations.retrieve(
    "integration_id",
)
print(integration.id)
```

## List MCP Servers

Retrieve a list of MCP servers.

`GET /ai/mcp_servers`

```python
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`

```python
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}`

```python
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}`

```python
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}`

```python
client.ai.mcp_servers.delete(
    "mcp_server_id",
)
```