From telnyx
Create and manage Telnyx Missions for AI-driven telecom workflows using Python SDK. Covers listing/creating missions/events, error handling, and pagination.
npx claudepluginhub team-telnyx/ai --plugin telnyxThis skill uses the workspace's default tool permissions.
<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->
Create and manage Telnyx Missions for AI-driven telecom workflows using Python SDK. Covers listing/creating missions/events, error handling, and pagination.
Provides curl examples to create, list, and manage Telnyx Missions—automated workflows and tasks for AI-driven telecom operations.
Automates Telnyx operations via Composio toolkit and Rube MCP. Discovers tools dynamically with RUBE_SEARCH_TOOLS, manages connections, and executes workflows reliably.
Share bugs, ideas, or general feedback.
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
)
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")
except telnyx.RateLimitError:
# 429: rate limited — wait and retry with exponential backoff
import time
time.sleep(1) # Check Retry-After header for actual delay
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")
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.List all missions for the organization
GET /ai/missions
page = client.ai.missions.list()
page = page.data[0]
print(page.mission_id)
Returns: created_at (date-time), description (string), execution_mode (enum: external, managed), instructions (string), metadata (object), mission_id (uuid), model (string), name (string), updated_at (date-time)
Create a new mission definition
POST /ai/missions — Required: name
Optional: description (string), execution_mode (enum: external, managed), instructions (string), metadata (object), model (string)
mission = client.ai.missions.create(
name="my-resource",
)
print(mission.data)
Returns: created_at (date-time), description (string), execution_mode (enum: external, managed), instructions (string), metadata (object), mission_id (uuid), model (string), name (string), updated_at (date-time)
List recent events across all missions
GET /ai/missions/events
page = client.ai.missions.list_events()
page = page.data[0]
print(page.event_id)
Returns: agent_id (string), event_id (string), idempotency_key (string), payload (object), run_id (string), step_id (string), summary (string), timestamp (date-time), type (enum: status_change, step_started, step_completed, step_failed, tool_call, tool_result, message, error, custom)
List recent runs across all missions
GET /ai/missions/runs
page = client.ai.missions.runs.list_runs()
page = page.data[0]
print(page.mission_id)
Returns: error (string), finished_at (date-time), input (object), metadata (object), mission_id (uuid), result_payload (object), result_summary (string), run_id (uuid), started_at (date-time), status (enum: pending, running, paused, succeeded, failed, cancelled), updated_at (date-time)
Get a mission by ID (includes tools, knowledge_bases, mcp_servers)
GET /ai/missions/{mission_id}
mission = client.ai.missions.retrieve(
"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(mission.data)
Returns: created_at (date-time), description (string), execution_mode (enum: external, managed), instructions (string), metadata (object), mission_id (uuid), model (string), name (string), updated_at (date-time)
Update a mission definition
PUT /ai/missions/{mission_id}
Optional: description (string), execution_mode (enum: external, managed), instructions (string), metadata (object), model (string), name (string)
response = client.ai.missions.update_mission(
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(response.data)
Returns: created_at (date-time), description (string), execution_mode (enum: external, managed), instructions (string), metadata (object), mission_id (uuid), model (string), name (string), updated_at (date-time)
Delete a mission
DELETE /ai/missions/{mission_id}
client.ai.missions.delete_mission(
"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
Clone an existing mission
POST /ai/missions/{mission_id}/clone
response = client.ai.missions.clone_mission(
"mission_id",
)
print(response)
List all knowledge bases for a mission
GET /ai/missions/{mission_id}/knowledge-bases
response = client.ai.missions.knowledge_bases.list_knowledge_bases(
"mission_id",
)
print(response)
Create a new knowledge base for a mission
POST /ai/missions/{mission_id}/knowledge-bases
response = client.ai.missions.knowledge_bases.create_knowledge_base(
"mission_id",
)
print(response)
Get a specific knowledge base by ID
GET /ai/missions/{mission_id}/knowledge-bases/{knowledge_base_id}
response = client.ai.missions.knowledge_bases.get_knowledge_base(
knowledge_base_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response)
Update a knowledge base definition
PUT /ai/missions/{mission_id}/knowledge-bases/{knowledge_base_id}
response = client.ai.missions.knowledge_bases.update_knowledge_base(
knowledge_base_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response)
Delete a knowledge base from a mission
DELETE /ai/missions/{mission_id}/knowledge-bases/{knowledge_base_id}
client.ai.missions.knowledge_bases.delete_knowledge_base(
knowledge_base_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="550e8400-e29b-41d4-a716-446655440000",
)
List all MCP servers for a mission
GET /ai/missions/{mission_id}/mcp-servers
response = client.ai.missions.mcp_servers.list_mcp_servers(
"mission_id",
)
print(response)
Create a new MCP server for a mission
POST /ai/missions/{mission_id}/mcp-servers
response = client.ai.missions.mcp_servers.create_mcp_server(
"mission_id",
)
print(response)
Get a specific MCP server by ID
GET /ai/missions/{mission_id}/mcp-servers/{mcp_server_id}
response = client.ai.missions.mcp_servers.get_mcp_server(
mcp_server_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response)
Update an MCP server definition
PUT /ai/missions/{mission_id}/mcp-servers/{mcp_server_id}
response = client.ai.missions.mcp_servers.update_mcp_server(
mcp_server_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response)
Delete an MCP server from a mission
DELETE /ai/missions/{mission_id}/mcp-servers/{mcp_server_id}
client.ai.missions.mcp_servers.delete_mcp_server(
mcp_server_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="550e8400-e29b-41d4-a716-446655440000",
)
List all runs for a specific mission
GET /ai/missions/{mission_id}/runs
page = client.ai.missions.runs.list(
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
page = page.data[0]
print(page.mission_id)
Returns: error (string), finished_at (date-time), input (object), metadata (object), mission_id (uuid), result_payload (object), result_summary (string), run_id (uuid), started_at (date-time), status (enum: pending, running, paused, succeeded, failed, cancelled), updated_at (date-time)
Start a new run for a mission
POST /ai/missions/{mission_id}/runs
Optional: input (object), metadata (object)
run = client.ai.missions.runs.create(
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(run.data)
Returns: error (string), finished_at (date-time), input (object), metadata (object), mission_id (uuid), result_payload (object), result_summary (string), run_id (uuid), started_at (date-time), status (enum: pending, running, paused, succeeded, failed, cancelled), updated_at (date-time)
Get details of a specific run
GET /ai/missions/{mission_id}/runs/{run_id}
run = client.ai.missions.runs.retrieve(
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(run.data)
Returns: error (string), finished_at (date-time), input (object), metadata (object), mission_id (uuid), result_payload (object), result_summary (string), run_id (uuid), started_at (date-time), status (enum: pending, running, paused, succeeded, failed, cancelled), updated_at (date-time)
Update run status and/or result
PATCH /ai/missions/{mission_id}/runs/{run_id}
Optional: error (string), metadata (object), result_payload (object), result_summary (string), status (enum: pending, running, paused, succeeded, failed, cancelled)
run = client.ai.missions.runs.update(
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(run.data)
Returns: error (string), finished_at (date-time), input (object), metadata (object), mission_id (uuid), result_payload (object), result_summary (string), run_id (uuid), started_at (date-time), status (enum: pending, running, paused, succeeded, failed, cancelled), updated_at (date-time)
Cancel a running or paused run
POST /ai/missions/{mission_id}/runs/{run_id}/cancel
response = client.ai.missions.runs.cancel_run(
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(response.data)
Returns: error (string), finished_at (date-time), input (object), metadata (object), mission_id (uuid), result_payload (object), result_summary (string), run_id (uuid), started_at (date-time), status (enum: pending, running, paused, succeeded, failed, cancelled), updated_at (date-time)
List events for a run (paginated)
GET /ai/missions/{mission_id}/runs/{run_id}/events
page = client.ai.missions.runs.events.list(
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
page = page.data[0]
print(page.event_id)
Returns: agent_id (string), event_id (string), idempotency_key (string), payload (object), run_id (string), step_id (string), summary (string), timestamp (date-time), type (enum: status_change, step_started, step_completed, step_failed, tool_call, tool_result, message, error, custom)
Log an event for a run
POST /ai/missions/{mission_id}/runs/{run_id}/events — Required: type, summary
Optional: agent_id (string), idempotency_key (string), payload (object), step_id (string)
response = client.ai.missions.runs.events.log(
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
summary="Brief task summary",
type="status_change",
)
print(response.data)
Returns: agent_id (string), event_id (string), idempotency_key (string), payload (object), run_id (string), step_id (string), summary (string), timestamp (date-time), type (enum: status_change, step_started, step_completed, step_failed, tool_call, tool_result, message, error, custom)
Get details of a specific event
GET /ai/missions/{mission_id}/runs/{run_id}/events/{event_id}
response = client.ai.missions.runs.events.get_event_details(
event_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(response.data)
Returns: agent_id (string), event_id (string), idempotency_key (string), payload (object), run_id (string), step_id (string), summary (string), timestamp (date-time), type (enum: status_change, step_started, step_completed, step_failed, tool_call, tool_result, message, error, custom)
Pause a running run
POST /ai/missions/{mission_id}/runs/{run_id}/pause
response = client.ai.missions.runs.pause_run(
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(response.data)
Returns: error (string), finished_at (date-time), input (object), metadata (object), mission_id (uuid), result_payload (object), result_summary (string), run_id (uuid), started_at (date-time), status (enum: pending, running, paused, succeeded, failed, cancelled), updated_at (date-time)
Get the plan (all steps) for a run
GET /ai/missions/{mission_id}/runs/{run_id}/plan
plan = client.ai.missions.runs.plan.retrieve(
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(plan.data)
Returns: completed_at (date-time), description (string), metadata (object), parent_step_id (string), run_id (uuid), sequence (integer), started_at (date-time), status (enum: pending, in_progress, completed, skipped, failed), step_id (string)
Create the initial plan for a run
POST /ai/missions/{mission_id}/runs/{run_id}/plan — Required: steps
plan = client.ai.missions.runs.plan.create(
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
steps=[{
"description": "description",
"sequence": 0,
"step_id": "step_id",
}],
)
print(plan.data)
Returns: completed_at (date-time), description (string), metadata (object), parent_step_id (string), run_id (uuid), sequence (integer), started_at (date-time), status (enum: pending, in_progress, completed, skipped, failed), step_id (string)
Add one or more steps to an existing plan
POST /ai/missions/{mission_id}/runs/{run_id}/plan/steps — Required: steps
response = client.ai.missions.runs.plan.add_steps_to_plan(
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
steps=[{
"description": "description",
"sequence": 0,
"step_id": "step_id",
}],
)
print(response.data)
Returns: completed_at (date-time), description (string), metadata (object), parent_step_id (string), run_id (uuid), sequence (integer), started_at (date-time), status (enum: pending, in_progress, completed, skipped, failed), step_id (string)
Get details of a specific plan step
GET /ai/missions/{mission_id}/runs/{run_id}/plan/steps/{step_id}
response = client.ai.missions.runs.plan.get_step_details(
step_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(response.data)
Returns: completed_at (date-time), description (string), metadata (object), parent_step_id (string), run_id (uuid), sequence (integer), started_at (date-time), status (enum: pending, in_progress, completed, skipped, failed), step_id (string)
Update the status of a plan step
PATCH /ai/missions/{mission_id}/runs/{run_id}/plan/steps/{step_id}
Optional: metadata (object), status (enum: pending, in_progress, completed, skipped, failed)
response = client.ai.missions.runs.plan.update_step(
step_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(response.data)
Returns: completed_at (date-time), description (string), metadata (object), parent_step_id (string), run_id (uuid), sequence (integer), started_at (date-time), status (enum: pending, in_progress, completed, skipped, failed), step_id (string)
Resume a paused run
POST /ai/missions/{mission_id}/runs/{run_id}/resume
response = client.ai.missions.runs.resume_run(
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(response.data)
Returns: error (string), finished_at (date-time), input (object), metadata (object), mission_id (uuid), result_payload (object), result_summary (string), run_id (uuid), started_at (date-time), status (enum: pending, running, paused, succeeded, failed, cancelled), updated_at (date-time)
List all Telnyx agents linked to a run
GET /ai/missions/{mission_id}/runs/{run_id}/telnyx-agents
telnyx_agents = client.ai.missions.runs.telnyx_agents.list(
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(telnyx_agents.data)
Returns: created_at (date-time), run_id (string), telnyx_agent_id (string)
Link a Telnyx AI agent (voice/messaging) to a run
POST /ai/missions/{mission_id}/runs/{run_id}/telnyx-agents — Required: telnyx_agent_id
response = client.ai.missions.runs.telnyx_agents.link(
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
telnyx_agent_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response.data)
Returns: created_at (date-time), run_id (string), telnyx_agent_id (string)
Unlink a Telnyx agent from a run
DELETE /ai/missions/{mission_id}/runs/{run_id}/telnyx-agents/{telnyx_agent_id}
client.ai.missions.runs.telnyx_agents.unlink(
telnyx_agent_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
List all tools for a mission
GET /ai/missions/{mission_id}/tools
response = client.ai.missions.tools.list_tools(
"mission_id",
)
print(response)
Create a new tool for a mission
POST /ai/missions/{mission_id}/tools
response = client.ai.missions.tools.create_tool(
"mission_id",
)
print(response)
Get a specific tool by ID
GET /ai/missions/{mission_id}/tools/{tool_id}
response = client.ai.missions.tools.get_tool(
tool_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response)
Update a tool definition
PUT /ai/missions/{mission_id}/tools/{tool_id}
response = client.ai.missions.tools.update_tool(
tool_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response)
Delete a tool from a mission
DELETE /ai/missions/{mission_id}/tools/{tool_id}
client.ai.missions.tools.delete_tool(
tool_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="550e8400-e29b-41d4-a716-446655440000",
)