Every AI phone call your system places is a claim. "We reached the patient." "The appointment was confirmed." "The assistant handled it." Claims are easy to make and, without a durable record, painfully hard to prove — and in regulated industries, an undocumented call is a compliance problem the moment a payer asks for the record.
Most teams reconstruct that record after the fact, from application logs, webhook handlers, and whatever the worker script printed before it crashed. This post walks through a different pattern: missions-audit, a Python sample where the audit trail is a first-class API resource rather than something you bolt on afterwards. It drives one Telnyx AI mission end-to-end — create the mission, start a run, submit a plan, advance steps, log typed events, link the AI assistant, schedule a real outbound call — then renders a timestamped audit report of the whole ledger.
By the end, you'll be able to apply the same pattern to any agent workflow where "it happened" needs receipts.
What the App Does
The demo scenario is a regional clinic network running a daily outreach campaign: care coordinators call patients to confirm upcoming appointment slots, and every one of those calls has to be defensible. If a coordinator says a patient was reached, the network needs to show when the call was placed, which assistant handled it, what the outcome was, and who signed off on the plan. A missed confirmation is a no-show, a no-show is lost revenue, and an undocumented call is a compliance problem.
The sample compresses that world into five scripts, run in order:
create_mission.py— creates the durable mission: "verify 3 clinic contacts can be reached."start_run.py— starts one execution of that mission.plan_steps.py— submits the initial plan: provision an assistant, schedule the outreach call, verify the outcome.execute.py— the worker. It does the real work and mirrors every state change it observes into the ledger.audit.py— the renderer. It pulls mission, run, plan, events, and agent linkage into one chronological, timestamped report.
The mission is the durable actor. It is born the moment a coordinator commits to an objective, it evolves as each run plans its steps and the worker advances them one by one, and it completes — or terminates as failed — with a result summary a reviewer can replay months later. The mission and its run persist through the ordinary chaos of the job: the worker crashing mid-campaign, a scheduled call sitting in in_progress longer than expected, an operator pausing a run to re-check a number.
How It Works
What is a Telnyx AI mission?
A mission is a durable, queryable objective. A run is one execution of it. Each run carries a plan whose steps have statuses the executor advances as work happens. Around that core you get two more primitives: typed events (the audit timeline) and agent linkage (which AI assistant handled the run). The full surface:
| Object | Endpoints | Role in the audit |
|---|---|---|
| Mission | POST/GET /ai/missions, GET /ai/missions/{id} | The durable objective |
| Run | POST/GET .../runs, GET/PATCH .../runs/{run_id} | One execution; status + result_summary |
| Plan | POST/GET .../runs/{run_id}/plan | The planned steps |
| Step | PATCH .../plan/steps/{step_id} | Advancing step status |
| Events | POST/GET .../runs/{run_id}/events | The typed audit timeline |
| Agent link | POST/GET .../runs/{run_id}/telnyx-agents | Which assistant did the work |
Everything is raw REST against TELNYX_API_BASE (default https://api.telnyx.com/v2) with Authorization: Bearer $TELNYX_API_KEY. One quirk to know up front: Missions responses arrive wrapped in a {"data": ...} envelope, while the Assistants and scheduled-events endpoints return the object bare. The sample's client helpers handle both:
import os, requests
API_BASE = os.environ.get("TELNYX_API_BASE", "https://api.telnyx.com/v2")
HEADERS = {
"Authorization": f"Bearer {os.environ['TELNYX_API_KEY']}",
"Content-Type": "application/json",
}
def _send(method, path, body=None, bare=False):
r = requests.request(method, f"{API_BASE}{path}", headers=HEADERS, json=body)
r.raise_for_status()
data = r.json()
return data if bare else data["data"]
post = lambda path, body=None, bare=False: _send("POST", path, body or {}, bare)
get = lambda path, bare=False: _send("GET", path, bare=bare)
patch = lambda path, body: _send("PATCH", path, body)
Creating the mission, the run, and the plan
mission = post("/ai/missions", {"name": "clinic-outreach-verify-contacts"})
run = post(f"/ai/missions/{mission['id']}/runs", {})
plan = post(f"/ai/missions/{mission['id']}/runs/{run['id']}/plan", {
"steps": [
{"name": "provision-assistant"},
{"name": "schedule-outreach-call"},
{"name": "verify-call-outcome"},
],
})
step_ids = [s["id"] for s in plan["steps"]]
(Payload fields are abbreviated here; the repo's API.md carries the full typed contract.)
The run starts in pending. The RunStatus enum is pending → running → succeeded | failed, with paused and cancelled available for operator intervention — resume and cancel each have their own endpoints. Steps walk pending → in_progress → completed | failed, with skipped documented for intentional no-ops.
The worker's honesty contract
execute.py is the actor doing real work: it provisions the assistant, schedules the call, and polls the scheduled event to a terminal status. Its contract is honesty — it logs every state change it observes, not only its own actions:
def advance(step_id, status):
patch(f"/ai/missions/{m}/runs/{r}/plan/steps/{step_id}", {"status": status})
def log(event_type, summary):
post(f"/ai/missions/{m}/runs/{r}/events",
{"type": event_type, "summary": summary})
# Step 1: provision the assistant
advance(step_ids[0], "in_progress")
log("step_started", "Provisioning outreach assistant")
assistant = post("/ai/assistants", {...}, bare=True) # bare: no envelope
advance(step_ids[0], "completed")
log("step_completed", f"Assistant {assistant['id']} ready")
# Step 2: schedule the outreach call
event = post(f"/ai/assistants/{assistant['id']}/scheduled_events", {...}, bare=True)
log("call_scheduled", f"Scheduled event {event['id']}")
# Step 3: poll the scheduled event to a terminal status
while (ev := get(f"/ai/assistants/{assistant['id']}/scheduled_events/{event['id']}",
bare=True))["status"] not in TERMINAL:
time.sleep(POLL_SECONDS)
# Close out the run and name the actor
patch(f"/ai/missions/{m}/runs/{r}",
{"status": "succeeded", "result_summary": "3/3 contacts verified"})
post(f"/ai/missions/{m}/runs/{r}/telnyx-agents", {"assistant_id": assistant["id"]})
Two details carry the whole pattern. First, the assistant that places the call is the same assistant you link back to the run via telnyx-agents — so the audit report can name the actor, not just the action. Second, if the worker crashes mid-campaign, the mission and its run persist, and the ledger shows exactly how far the run got, because every observed state change was mirrored as it happened.
Rendering the audit
audit.py polls the run until it reaches a terminal status (capped at 10 minutes), then does fresh GETs of the run, plan, events, and agent linkage — a cross-check against the server's view of the world, not the worker's self-report — and merges everything into one chronological, timestamped report:
MISSIONS AUDIT REPORT — clinic-outreach-verify-contacts
run: status=succeeded result_summary="3/3 contacts verified"
14:02:11 step_started Provisioning outreach assistant
14:02:14 step_completed Assistant asst_… ready
14:02:15 step_started Scheduling outreach call
14:02:19 call_scheduled Scheduled event se_…
14:03:02 step_completed Call completed; outcome recorded
Setup
git clone https://github.com/team-telnyx/telnyx-code-examples
cd telnyx-code-examples/missions-audit
pip install requests
export TELNYX_API_KEY="YOUR_API_KEY"
python create_mission.py # create the durable mission
python start_run.py # start one execution
python plan_steps.py # submit the plan
python execute.py # run the worker
python audit.py # render the audit report
You'll need a Telnyx API key with AI permissions. The worker schedules a real outbound call, so point it at a number you control.
Conclusion
The interesting thing about this sample isn't any single endpoint — it's the posture. The mission ledger, the AI assistant, and the scheduled call all live on one platform, which is what AI Communications Infrastructure means in practice: no separate observability vendor, no log-scraping glue, and no gap between "the call happened" and "the call is documented." The record reflects the world, not the worker's self-report.
Grab the code, run it against a test number, and adapt the pattern to your own agent workflows: https://github.com/team-telnyx/telnyx-code-examples/tree/main/missions-audit