From telnyx-javascript
Create and manage Telnyx Missions—AI-driven telecom workflows and tasks—using JavaScript SDK examples for listing, creating, error handling, and pagination.
npx claudepluginhub team-telnyx/skillsThis skill uses the workspace's default tool permissions.
<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->
Create and manage Telnyx Missions—AI-driven telecom workflows and tasks—using JavaScript SDK examples for listing, creating, error handling, and pagination.
Automates Telnyx operations via Composio toolkit and Rube MCP. Discovers tools dynamically with RUBE_SEARCH_TOOLS, manages connections, and executes workflows reliably.
Automates OpenHands Cloud REST API V1 for starting conversations, monitoring status, and delegating to fresh-context cloud sessions. Use for OpenHands Cloud workflows.
Share bugs, ideas, or general feedback.
npm install telnyx
import Telnyx from 'telnyx';
const client = new Telnyx({
apiKey: process.env['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:
try {
const result = await client.messages.send({ to: '+13125550001', from: '+13125550002', text: 'Hello' });
} catch (err) {
if (err instanceof Telnyx.APIConnectionError) {
console.error('Network error — check connectivity and retry');
} else if (err instanceof Telnyx.RateLimitError) {
// 429: rate limited — wait and retry with exponential backoff
const retryAfter = err.headers?.['retry-after'] || 1;
await new Promise(r => setTimeout(r, retryAfter * 1000));
} else if (err instanceof Telnyx.APIError) {
console.error(`API error ${err.status}: ${err.message}`);
if (err.status === 422) {
console.error('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 await (const item of result) { ... } to iterate through all pages automatically.List all missions for the organization
GET /ai/missions
// Automatically fetches more pages as needed.
for await (const missionData of client.ai.missions.list()) {
console.log(missionData.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)
const mission = await client.ai.missions.create({ name: 'my-resource' });
console.log(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
// Automatically fetches more pages as needed.
for await (const eventData of client.ai.missions.listEvents()) {
console.log(eventData.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
// Automatically fetches more pages as needed.
for await (const missionRunData of client.ai.missions.runs.listRuns()) {
console.log(missionRunData.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}
const mission = await client.ai.missions.retrieve('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');
console.log(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)
const response = await client.ai.missions.updateMission('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');
console.log(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}
await client.ai.missions.deleteMission('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');
Clone an existing mission
POST /ai/missions/{mission_id}/clone
const response = await client.ai.missions.cloneMission('mission_id');
console.log(response);
List all knowledge bases for a mission
GET /ai/missions/{mission_id}/knowledge-bases
const response = await client.ai.missions.knowledgeBases.listKnowledgeBases('mission_id');
console.log(response);
Create a new knowledge base for a mission
POST /ai/missions/{mission_id}/knowledge-bases
const response = await client.ai.missions.knowledgeBases.createKnowledgeBase('mission_id');
console.log(response);
Get a specific knowledge base by ID
GET /ai/missions/{mission_id}/knowledge-bases/{knowledge_base_id}
const response = await client.ai.missions.knowledgeBases.getKnowledgeBase('knowledge_base_id', {
mission_id: '550e8400-e29b-41d4-a716-446655440000',
});
console.log(response);
Update a knowledge base definition
PUT /ai/missions/{mission_id}/knowledge-bases/{knowledge_base_id}
const response = await client.ai.missions.knowledgeBases.updateKnowledgeBase('knowledge_base_id', {
mission_id: '550e8400-e29b-41d4-a716-446655440000',
});
console.log(response);
Delete a knowledge base from a mission
DELETE /ai/missions/{mission_id}/knowledge-bases/{knowledge_base_id}
await client.ai.missions.knowledgeBases.deleteKnowledgeBase('knowledge_base_id', {
mission_id: '550e8400-e29b-41d4-a716-446655440000',
});
List all MCP servers for a mission
GET /ai/missions/{mission_id}/mcp-servers
const response = await client.ai.missions.mcpServers.listMcpServers('mission_id');
console.log(response);
Create a new MCP server for a mission
POST /ai/missions/{mission_id}/mcp-servers
const response = await client.ai.missions.mcpServers.createMcpServer('mission_id');
console.log(response);
Get a specific MCP server by ID
GET /ai/missions/{mission_id}/mcp-servers/{mcp_server_id}
const response = await client.ai.missions.mcpServers.getMcpServer('mcp_server_id', {
mission_id: '550e8400-e29b-41d4-a716-446655440000',
});
console.log(response);
Update an MCP server definition
PUT /ai/missions/{mission_id}/mcp-servers/{mcp_server_id}
const response = await client.ai.missions.mcpServers.updateMcpServer('mcp_server_id', {
mission_id: '550e8400-e29b-41d4-a716-446655440000',
});
console.log(response);
Delete an MCP server from a mission
DELETE /ai/missions/{mission_id}/mcp-servers/{mcp_server_id}
await client.ai.missions.mcpServers.deleteMcpServer('mcp_server_id', { mission_id: '550e8400-e29b-41d4-a716-446655440000' });
List all runs for a specific mission
GET /ai/missions/{mission_id}/runs
// Automatically fetches more pages as needed.
for await (const missionRunData of client.ai.missions.runs.list(
'182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
)) {
console.log(missionRunData.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)
const run = await client.ai.missions.runs.create('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');
console.log(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}
const run = await client.ai.missions.runs.retrieve('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {
mission_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
});
console.log(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)
const run = await client.ai.missions.runs.update('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {
mission_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
});
console.log(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
const response = await client.ai.missions.runs.cancelRun('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {
mission_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
});
console.log(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
// Automatically fetches more pages as needed.
for await (const eventData of client.ai.missions.runs.events.list(
'182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
{ mission_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' },
)) {
console.log(eventData.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)
const response = await client.ai.missions.runs.events.log('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {
mission_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
summary: 'Brief task summary',
type: 'status_change',
});
console.log(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}
const response = await client.ai.missions.runs.events.getEventDetails('event_id', {
mission_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
run_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
});
console.log(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
const response = await client.ai.missions.runs.pauseRun('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {
mission_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
});
console.log(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
const plan = await client.ai.missions.runs.plan.retrieve('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {
mission_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
});
console.log(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
const plan = await client.ai.missions.runs.plan.create('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {
mission_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
steps: [
{
description: 'description',
sequence: 0,
step_id: '550e8400-e29b-41d4-a716-446655440000',
},
],
});
console.log(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
const response = await client.ai.missions.runs.plan.addStepsToPlan(
'182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
{
mission_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
steps: [
{
description: 'description',
sequence: 0,
step_id: '550e8400-e29b-41d4-a716-446655440000',
},
],
},
);
console.log(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}
const response = await client.ai.missions.runs.plan.getStepDetails('step_id', {
mission_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
run_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
});
console.log(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)
const response = await client.ai.missions.runs.plan.updateStep('step_id', {
mission_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
run_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
});
console.log(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
const response = await client.ai.missions.runs.resumeRun('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {
mission_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
});
console.log(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
const telnyxAgents = await client.ai.missions.runs.telnyxAgents.list(
'182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
{ mission_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' },
);
console.log(telnyxAgents.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
const response = await client.ai.missions.runs.telnyxAgents.link(
'182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
{ mission_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', telnyx_agent_id: '550e8400-e29b-41d4-a716-446655440000' },
);
console.log(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}
await client.ai.missions.runs.telnyxAgents.unlink('telnyx_agent_id', {
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
const response = await client.ai.missions.tools.listTools('mission_id');
console.log(response);
Create a new tool for a mission
POST /ai/missions/{mission_id}/tools
const response = await client.ai.missions.tools.createTool('mission_id');
console.log(response);
Get a specific tool by ID
GET /ai/missions/{mission_id}/tools/{tool_id}
const response = await client.ai.missions.tools.getTool('tool_id', { mission_id: '550e8400-e29b-41d4-a716-446655440000' });
console.log(response);
Update a tool definition
PUT /ai/missions/{mission_id}/tools/{tool_id}
const response = await client.ai.missions.tools.updateTool('tool_id', { mission_id: '550e8400-e29b-41d4-a716-446655440000' });
console.log(response);
Delete a tool from a mission
DELETE /ai/missions/{mission_id}/tools/{tool_id}
await client.ai.missions.tools.deleteTool('tool_id', { mission_id: '550e8400-e29b-41d4-a716-446655440000' });