Access Telnyx LLM inference APIs, embeddings, and AI analytics for call insights and summaries. This skill provides Python SDK examples.
The English summary is being prepared. Showing the original description.
See how to installReview the instructions the agent will receive before you install.
pip install telnyx
import os
from telnyx import Telnyx
client = Telnyx(
api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted
public_key=os.environ.get("TELNYX_PUBLIC_KEY"), # Required for client.webhooks.unwrap() (webhook verification)
)
All examples below assume client is already initialized as shown above.
All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code:
import telnyx
try:
result = client.messages.send(to="+13125550001", from_="+13125550002", text="Hello")
except telnyx.APIConnectionError:
print("Network error — check connectivity and retry")
raise
except telnyx.RateLimitError:
# 429: rate limited — wait, then retry the request (bounded exponential backoff)
import time
time.sleep(1) # Check Retry-After header for actual delay
# ...retry the call here (give up after a few attempts); otherwise re-raise:
raise
except telnyx.APIStatusError as e:
print(f"API error {e.status_code}: {e.message}")
if e.status_code == 422:
print("Validation error — check required fields and formats")
raise # A failed request must never look like success to the caller
Common error codes: 401 invalid API key, 403 insufficient permissions,
404 resource not found, 422 validation error (check field formats),
429 rate limited (retry with exponential backoff).
for item in page_result: to iterate through all pages automatically.Transcribe speech to text. This endpoint is consistent with the OpenAI Transcription API and may be used with the OpenAI JS or Python SDK.
POST /ai/audio/transcriptions
response = client.ai.audio.transcribe(
model="distil-whisper/distil-large-v2",
)
print(response.text)
Returns: duration (number), segments (array[object]), text (string), words (array[object])
Retrieve a list of all AI conversations configured by the user. Supports PostgREST-style query parameters for filtering. Examples are included for the standard metadata fields, but you can filter on any field in the metadata JSON object.
GET /ai/conversations
conversations = client.ai.conversations.list()
print(conversations.data)
Returns: created_at (date-time), id (uuid), last_message_at (date-time), metadata (object), name (string)
Creates a new AI conversation, the container for messages exchanged with an assistant, and returns the created conversation.
POST /ai/conversations
Optional: metadata (object), name (string)
conversation = client.ai.conversations.create()
print(conversation.id)
Returns: created_at (date-time), id (uuid), last_message_at (date-time), metadata (object), name (string)
Aggregate conversation insights by specified fields
GET /ai/conversations/conversation-insights/aggregates
response = client.ai.conversations.conversation_insights.retrieve_aggregates()
print(response.data)
Returns: record_count (integer)
Returns a paginated list of your insight template groups. Groups organize related insight templates that are applied together when analyzing conversations.
GET /ai/conversations/insight-groups
page = client.ai.conversations.insight_groups.retrieve_insight_groups()
page = page.data[0]
print(page.id)
Returns: created_at (date-time), description (string), id (uuid), insights (array[object]), name (string), webhook (string)
Creates a new insight template group for organizing related insight templates, and returns the created group.
POST /ai/conversations/insight-groups — Required: name
Optional: description (string), webhook (string)
insight_template_group_detail = client.ai.conversations.insight_groups.insight_groups(
name="my-resource",
)
print(insight_template_group_detail.data)
Returns: created_at (date-time), description (string), id (uuid), insights (array[object]), name (string), webhook (string)
Returns the details of a single insight template group, including the insight templates assigned to it.
GET /ai/conversations/insight-groups/{group_id}
insight_template_group_detail = client.ai.conversations.insight_groups.retrieve(
"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(insight_template_group_detail.data)
Returns: created_at (date-time), description (string), id (uuid), insights (array[object]), name (string), webhook (string)
Updates the specified insight template group and returns the updated group.
PUT /ai/conversations/insight-groups/{group_id}
Optional: description (string), name (string), webhook (string)
insight_template_group_detail = client.ai.conversations.insight_groups.update(
group_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(insight_template_group_detail.data)
Returns: created_at (date-time), description (string), id (uuid), insights (array[object]), name (string), webhook (string)
Permanently deletes the specified insight template group by its ID.
DELETE /ai/conversations/insight-groups/{group_id}
client.ai.conversations.insight_groups.delete(
"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
Assigns the specified insight template to the specified insight template group.
POST /ai/conversations/insight-groups/{group_id}/insights/{insight_id}/assign
client.ai.conversations.insight_groups.insights.assign(
insight_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
group_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
Removes the specified insight template from the specified group. The insight template itself is not deleted.
DELETE /ai/conversations/insight-groups/{group_id}/insights/{insight_id}/unassign
client.ai.conversations.insight_groups.insights.delete_unassign(
insight_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
group_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
Returns a paginated list of your insight templates. Insight templates define analyses that run over AI conversations to extract structured findings.
GET /ai/conversations/insights
page = client.ai.conversations.insights.list()
page = page.data[0]
print(page.id)
Returns: created_at (date-time), id (uuid), insight_type (enum: custom, default), instructions (string), json_schema (object), name (string), webhook (string)
Creates a new insight template defining an analysis to run over conversations, and returns the created template.
POST /ai/conversations/insights — Required: instructions, name
Optional: json_schema (object), webhook (string)
insight_template_detail = client.ai.conversations.insights.create(
instructions="You are a helpful assistant.",
name="my-resource",
)
print(insight_template_detail.data)
Returns: created_at (date-time), id (uuid), insight_type (enum: custom, default), instructions (string), json_schema (object), name (string), webhook (string)
Returns the details of a single insight template by its ID, including its configuration.
GET /ai/conversations/insights/{insight_id}
insight_template_detail = client.ai.conversations.insights.retrieve(
"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(insight_template_detail.data)
Returns: created_at (date-time), id (uuid), insight_type (enum: custom, default), instructions (string), json_schema (object), name (string), webhook (string)
Updates the specified insight template and returns the updated template.
PUT /ai/conversations/insights/{insight_id}
Optional: instructions (string), json_schema (object), name (string), webhook (string)
insight_template_detail = client.ai.conversations.insights.update(
insight_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(insight_template_detail.data)
Returns: created_at (date-time), id (uuid), insight_type (enum: custom, default), instructions (string), json_schema (object), name (string), webhook (string)
Permanently deletes the specified insight template by its ID.
DELETE /ai/conversations/insights/{insight_id}
client.ai.conversations.insights.delete(
"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
Retrieve a specific AI conversation by its ID.
GET /ai/conversations/{conversation_id}
conversation = client.ai.conversations.retrieve("550e8400-e29b-41d4-a716-446655440000",
)
print(conversation.data)
Returns: created_at (date-time), id (uuid), last_message_at (date-time), metadata (object), name (string)
Update metadata for a specific conversation.
PUT /ai/conversations/{conversation_id}
Optional: metadata (object)
conversation = client.ai.conversations.update(
conversation_id="550e8400-e29b-41d4-a716-446655440000",
)
print(conversation.data)
Returns: created_at (date-time), id (uuid), last_message_at (date-time), metadata (object), name (string)
Delete a specific conversation by its ID.
DELETE /ai/conversations/{conversation_id}
client.ai.conversations.delete("550e8400-e29b-41d4-a716-446655440000",
)
Retrieve insights for a specific conversation
GET /ai/conversations/{conversation_id}/conversations-insights
response = client.ai.conversations.retrieve_conversations_insights("550e8400-e29b-41d4-a716-446655440000",
)
print(response.data)
Returns: conversation_insights (array[object]), created_at (date-time), id (string), status (enum: pending, in_progress, completed, failed)
Add a new message to the conversation. Used to insert a new messages to a conversation manually ( without using chat endpoint )
POST /ai/conversations/{conversation_id}/message — Required: role
Optional: content (string), metadata (object), name (string), sent_at (date-time), tool_call_id (string), tool_calls (array[object]), tool_choice (object)
client.ai.conversations.add_message(
conversation_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
role="user",
)
Retrieve messages for a specific conversation, including tool calls made by the assistant.
GET /ai/conversations/{conversation_id}/messages
page = client.ai.conversations.messages.list(
conversation_id="550e8400-e29b-41d4-a716-446655440000",
)
page = page.data[0]
print(page.role)
Returns: created_at (date-time), metadata (object), role (enum: user, assistant, tool), sent_at (date-time), text (string), tool_calls (array[object])
Retrieve tasks for the user that are either queued, processing, failed, success or partial_success based on the query string. Defaults to queued and processing.
GET /ai/embeddings
embeddings = client.ai.embeddings.list()
print(embeddings.data)
Returns: bucket (string), created_at (date-time), finished_at (date-time), status (enum: queued, processing, success, failure, partial_success), task_id (string), task_name (string), user_id (string)
Perform embedding on a Telnyx Storage Bucket using an embedding model. The current supported file types are:
POST /ai/embeddings — Required: bucket_name
Optional: document_chunk_overlap_size (integer), document_chunk_size (integer), embedding_model (object), loader (object)
embedding_response = client.ai.embeddings.create(
bucket_name="my-bucket",
)
print(embedding_response.data)
Returns: created_at (string), finished_at (string | null), status (string), task_id (uuid), task_name (string), user_id (uuid)
Returns the list of storage buckets that have been embedded for your account, for use with similarity search.
GET /ai/embeddings/buckets
buckets = client.ai.embeddings.buckets.list()
print(buckets.data)
Returns: buckets (array[string])
Get all embedded files for a given user bucket, including their processing status.
GET /ai/embeddings/buckets/{bucket_name}
bucket = client.ai.embeddings.buckets.retrieve(
"bucket_name",
)
print(bucket.data)
Returns: created_at (date-time), error_reason (string), filename (string), last_embedded_at (date-time), status (string), updated_at (date-time)
Deletes an entire bucket's embeddings and disables the bucket for AI-use, returning it to normal storage pricing.
DELETE /ai/embeddings/buckets/{bucket_name}
client.ai.embeddings.buckets.delete(
"bucket_name",
)
Perform a similarity search on a Telnyx Storage Bucket, returning the most similar num_docs document chunks to the query. Currently the only available distance metric is cosine similarity which will return a distance between 0 and 1. The lower the distance, the more similar the returned document chunks are to the query.
POST /ai/embeddings/similarity-search — Required: bucket_name, query
Optional: num_of_docs (integer)
response = client.ai.embeddings.similarity_search(
bucket_name="my-bucket",
query="What is Telnyx?",
)
print(response.data)
Returns: distance (number), document_chunk (string), metadata (object)
Embed website content from a specified URL, including child pages up to 5 levels deep within the same domain. The process crawls and loads content from the main URL and its linked pages into a Telnyx Cloud Storage bucket.
POST /ai/embeddings/url — Required: url, bucket_name
embedding_response = client.ai.embeddings.url(
bucket_name="my-bucket",
url="https://example.com/resource",
)
print(embedding_response.data)
Returns: created_at (string), finished_at (string | null), status (string), task_id (uuid), task_name (string), user_id (uuid)
Check the status of a current embedding task. Will be one of the following:
queued - Task is waiting to be picked up by a workerprocessing - The embedding task is runningsuccess - Task completed successfully and the bucket is embeddedfailure - Task failed and no files were embedded successfullypartial_success - Some files were embedded successfully, but at least one failedGET /ai/embeddings/{task_id}
embedding = client.ai.embeddings.retrieve(
"task_id",
)
print(embedding.data)
Returns: created_at (string), finished_at (string), status (enum: queued, processing, success, failure, partial_success), task_id (uuid), task_name (string)
Retrieve a list of all fine tuning jobs created by the user.
GET /ai/fine_tuning/jobs
jobs = client.ai.fine_tuning.jobs.list()
print(jobs.data)
Returns: created_at (integer), finished_at (integer | null), hyperparameters (object), id (string), model (string), organization_id (string), status (enum: queued, running, succeeded, failed, cancelled), trained_tokens (integer | null), training_file (string)
Creates a new fine-tuning job that trains a model on the provided dataset, and returns the created job.
POST /ai/fine_tuning/jobs — Required: model, training_file
Optional: hyperparameters (object), suffix (string)
fine_tuning_job = client.ai.fine_tuning.jobs.create(
model="openai/gpt-4o",
training_file="training-data.jsonl",
)
print(fine_tuning_job.id)
Returns: created_at (integer), finished_at (integer | null), hyperparameters (object), id (string), model (string), organization_id (string), status (enum: queued, running, succeeded, failed, cancelled), trained_tokens (integer | null), training_file (string)
Returns the details of a single fine-tuning job by its job_id, including its current status.
GET /ai/fine_tuning/jobs/{job_id}
fine_tuning_job = client.ai.fine_tuning.jobs.retrieve(
"job_id",
)
print(fine_tuning_job.id)
Returns: created_at (integer), finished_at (integer | null), hyperparameters (object), id (string), model (string), organization_id (string), status (enum: queued, running, succeeded, failed, cancelled), trained_tokens (integer | null), training_file (string)
Cancels the specified in-progress fine-tuning job and returns the updated job.
POST /ai/fine_tuning/jobs/{job_id}/cancel
fine_tuning_job = client.ai.fine_tuning.jobs.cancel(
"job_id",
)
print(fine_tuning_job.id)
Returns: created_at (integer), finished_at (integer | null), hyperparameters (object), id (string), model (string), organization_id (string), status (enum: queued, running, succeeded, failed, cancelled), trained_tokens (integer | null), training_file (string)
Creates an embedding vector representing the input text. This endpoint is compatible with the OpenAI Embeddings API and may be used with the OpenAI JS or Python SDK by setting the base URL to https://api.telnyx.com/v2/ai/openai.
POST /ai/openai/embeddings — Required: input, model
Optional: dimensions (integer), encoding_format (enum: float, base64), user (string)
response = client.ai.openai.embeddings.create_embeddings(
input="The quick brown fox jumps over the lazy dog",
model="thenlper/gte-large",
)
print(response.data)
Returns: data (array[object]), model (string), object (string), usage (object)
Returns a list of available embedding models. This endpoint is compatible with the OpenAI Models API format.
GET /ai/openai/embeddings/models
response = client.ai.openai.embeddings.list_embedding_models()
print(response.data)
Returns: created (integer), id (string), object (string), owned_by (string)
Generate a summary of a file's contents. Supports the following text formats:
Supports the following media formats (billed for both the transcription and summary):
POST /ai/summarize — Required: bucket, filename
Optional: system_prompt (string)
response = client.ai.summarize(
bucket="my-bucket",
filename="data.csv",
)
print(response.data)
Returns: summary (string)
Retrieves all Speech to Text batch report requests for the authenticated user
GET /legacy/reporting/batch_detail_records/speech_to_text
speech_to_texts = client.legacy.reporting.batch_detail_records.speech_to_text.list()
print(speech_to_texts.data)
Returns: created_at (date-time), download_link (string), end_date (date-time), id (string), record_type (string), start_date (date-time), status (enum: PENDING, COMPLETE, FAILED, EXPIRED)
Creates a new Speech to Text batch report request with the specified filters
POST /legacy/reporting/batch_detail_records/speech_to_text — Required: start_date, end_date
from datetime import datetime
speech_to_text = client.legacy.reporting.batch_detail_records.speech_to_text.create(
end_date=datetime.fromisoformat("2020-07-01T00:00:00-06:00"),
start_date=datetime.fromisoformat("2020-07-01T00:00:00-06:00"),
)
print(speech_to_text.data)
Returns: created_at (date-time), download_link (string), end_date (date-time), id (string), record_type (string), start_date (date-time), status (enum: PENDING, COMPLETE, FAILED, EXPIRED)
Retrieves a specific Speech to Text batch report request by ID
GET /legacy/reporting/batch_detail_records/speech_to_text/{id}
speech_to_text = client.legacy.reporting.batch_detail_records.speech_to_text.retrieve(
"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(speech_to_text.data)
Returns: created_at (date-time), download_link (string), end_date (date-time), id (string), record_type (string), start_date (date-time), status (enum: PENDING, COMPLETE, FAILED, EXPIRED)
Deletes a specific Speech to Text batch report request by ID
DELETE /legacy/reporting/batch_detail_records/speech_to_text/{id}
speech_to_text = client.legacy.reporting.batch_detail_records.speech_to_text.delete(
"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(speech_to_text.data)
Returns: created_at (date-time), download_link (string), end_date (date-time), id (string), record_type (string), start_date (date-time), status (enum: PENDING, COMPLETE, FAILED, EXPIRED)
Generate and fetch speech to text usage report synchronously. This endpoint will both generate and fetch the speech to text report over a specified time period.
GET /legacy/reporting/usage_reports/speech_to_text
response = client.legacy.reporting.usage_reports.retrieve_speech_to_text()
print(response.data)
Returns: data (object)
Generate synthesized speech audio from text input. Returns audio in the requested format (binary audio stream, base64-encoded JSON, or an audio URL for later retrieval). Authentication is provided via the standard Authorization: Bearer header.
POST /text-to-speech/speech
Optional: aws (object), azure (object), disable_cache (boolean), elevenlabs (object), humain (object), language (string), minimax (object), output_type (enum: binary_output, base64_output), provider (enum: aws, telnyx, azure, elevenlabs, minimax, resemble, xai, humain, soniox), resemble (object), soniox (object), telnyx (object), text (string), text_type (enum: text, ssml), voice (string), voice_settings (object), xai (object)
response = client.text_to_speech.generate()
print(response.base64_audio)
Returns: base64_audio (string)
Retrieve a list of available voices from one or all TTS providers. When provider is specified, returns voices for that provider only. Otherwise, returns voices from all providers.
GET /text-to-speech/voices
response = client.text_to_speech.list_voices()
print(response.voices)
Returns: voices (array[object])
No reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
Test VoIP push notifications for Telnyx WebRTC iOS (APNs) and Android (FCM) apps. Use when debugging push notification delivery, validating certificate/credential setup, or testing that a device receives VoIP pushes correctly.
The English summary is being prepared. Showing the original description.
10DLC brand and campaign registration for US A2P messaging compliance. Assign phone numbers to campaigns.
The English summary is being prepared. Showing the original description.
10DLC brand and campaign registration for US A2P messaging compliance. Assign phone numbers to campaigns.
The English summary is being prepared. Showing the original description.
10DLC brand and campaign registration for US A2P messaging compliance. Assign phone numbers to campaigns.
The English summary is being prepared. Showing the original description.
10DLC brand and campaign registration for US A2P messaging compliance. Assign phone numbers to campaigns.
The English summary is being prepared. Showing the original description.
10DLC brand and campaign registration for US A2P messaging compliance. Assign phone numbers to campaigns.
The English summary is being prepared. Showing the original description.