Telnyx Missions – Ruby

Installation

gem install telnyx

Setup

require "telnyx"

client = Telnyx::Client.new(
  api_key: ENV["TELNYX_API_KEY"], # This is the default and can be omitted
)

All examples below assume client is already initialized as shown above.

List missions

List all missions for the organization

GET /ai/missions

page = client.ai.missions.list

puts(page)

Create mission

Create a new mission definition

POST /ai/missions — Required: name

Optional: description (string), execution_mode (enum), instructions (string), metadata (object), model (string)

mission = client.ai.missions.create(name: "name")

puts(mission)

List recent events

List recent events across all missions

GET /ai/missions/events

page = client.ai.missions.list_events

puts(page)

List recent runs

List recent runs across all missions

GET /ai/missions/runs

page = client.ai.missions.runs.list_runs

puts(page)

Get mission

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")

puts(mission)

Update mission

Update a mission definition

PUT /ai/missions/{mission_id}

Optional: description (string), execution_mode (enum), instructions (string), metadata (object), model (string), name (string)

response = client.ai.missions.update_mission("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")

puts(response)

Delete mission

Delete a mission

DELETE /ai/missions/{mission_id}

result = client.ai.missions.delete_mission("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")

puts(result)

Clone mission

Clone an existing mission

POST /ai/missions/{mission_id}/clone

response = client.ai.missions.clone_mission("mission_id")

puts(response)

List runs for mission

List all runs for a specific mission

GET /ai/missions/{mission_id}/runs

page = client.ai.missions.runs.list("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")

puts(page)

Start a run

Start a new run for a mission

POST /ai/missions/{mission_id}/runs

Optional: input (object), metadata (object)

run = client.ai.missions.runs.create("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")

puts(run)

Get run details

Get details of a specific run

GET /ai/missions/{mission_id}/runs/{run_id}

run = client.ai.missions.runs.retrieve(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)

puts(run)

Update run

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)

run = client.ai.missions.runs.update(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)

puts(run)

Cancel run

Cancel a running or paused run

POST /ai/missions/{mission_id}/runs/{run_id}/cancel

response = client.ai.missions.runs.cancel_run(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)

puts(response)

List events

List events for a run (paginated)

GET /ai/missions/{mission_id}/runs/{run_id}/events

page = client.ai.missions.runs.events.list(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)

puts(page)

Log event

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(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  summary: "summary",
  type: :status_change
)

puts(response)

Get event details

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",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  run_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)

puts(response)

Pause run

Pause a running run

POST /ai/missions/{mission_id}/runs/{run_id}/pause

response = client.ai.missions.runs.pause_run(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)

puts(response)

Get plan

Get the plan (all steps) for a run

GET /ai/missions/{mission_id}/runs/{run_id}/plan

plan = client.ai.missions.runs.plan.retrieve(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)

puts(plan)

Create initial plan

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(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  steps: [{description: "description", sequence: 0, step_id: "step_id"}]
)

puts(plan)

Add step(s) to plan

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(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  steps: [{description: "description", sequence: 0, step_id: "step_id"}]
)

puts(response)

Get step details

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",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  run_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)

puts(response)

Update step status

Update the status of a plan step

PATCH /ai/missions/{mission_id}/runs/{run_id}/plan/steps/{step_id}

Optional: metadata (object), status (enum)

response = client.ai.missions.runs.plan.update_step(
  "step_id",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  run_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)

puts(response)

Resume run

Resume a paused run

POST /ai/missions/{mission_id}/runs/{run_id}/resume

response = client.ai.missions.runs.resume_run(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)

puts(response)

List linked Telnyx agents

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(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)

puts(telnyx_agents)

Link Telnyx agent to run

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(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  telnyx_agent_id: "telnyx_agent_id"
)

puts(response)

Unlink Telnyx agent

Unlink a Telnyx agent from a run

DELETE /ai/missions/{mission_id}/runs/{run_id}/telnyx-agents/{telnyx_agent_id}

result = client.ai.missions.runs.telnyx_agents.unlink(
  "telnyx_agent_id",
  mission_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  run_id: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
)

puts(result)