telnyx-missions

# Telnyx AI Missions Track multi-step agent activities using the Telnyx AI Missions API. Create voice/SMS assistants, schedule calls, and retrieve conversation insights. --- # 🛑 GUARDRAILS — Actions Requiring Explicit User Permission **The following actions are NEVER allowed without explicit user approval.** Do not proceed with any of these — even if the mission plan implies them — until the user has reviewed and confirmed. These guardrails apply to **all contexts**: interactive sessions, cron-triggered runs, sub-agent executions, and any automated workflow that uses this skill. ## Prohibited Without Permission 1. **Remove a connection from a phone number** — Never unassign or change the connection profile on a phone number without user review. This can break live call routing. 2. **Create, edit, or delete an AI assistant** — Assistants are shared resources. Creating new ones, modifying instructions/tools/voice on existing ones, or deleting them requires explicit approval. (Reusing an existing assistant as-is is fine.) 3. **Create or edit TeXML apps or other connections** — Missions should never need to create or modify TeXML applications, SIP connections, FQDN connections, or any other connection type. If a mission plan seems to require this, stop and ask the user — the approach is wrong. 4. **Schedule a cron job** — Never create, modify, or enable a cron job (OpenClaw cron, system cron, or any scheduled automation) without user review. This includes cron jobs for polling, retries, or follow-up actions. ## Enforcement - **Before executing any of the above:** pause, describe what you intend to do and why, and wait for explicit approval. - **If running via cron or automation:** the cron-triggered agent must also follow these guardrails. Automation does not grant implicit permission. If a guardrailed action is needed, notify the user and wait — do not proceed unattended. - **If in doubt:** ask. It is always better to pause and confirm than to take an irreversible action. --- ## Setup The Python script `telnyx_api.py` handles all API calls: ```bash # Set your API key export TELNYX_API_KEY="your_key_here" # Run commands using the script python3 {baseDir}/scripts/telnyx_api.py <command> [args...] # Or create an alias for convenience alias missions="python3 {baseDir}/scripts/telnyx_api.py" ``` **Note:** All command examples in this document use `python telnyx_api.py` for brevity. Replace with the full path `python3 {baseDir}/scripts/telnyx_api.py` or use the alias above. --- This skill enables you to track your work using the Telnyx AI Missions API, including making phone calls and sending SMS messages through AI assistants. --- # ⚠️ CRITICAL: SAVE STATE FREQUENTLY ⚠️ **You MUST save your progress after EVERY significant action.** If the session crashes or restarts, unsaved work is LOST. ## Two-Layer Persistence: Memory + Events Always save to BOTH: 1. **Local Memory** (`.missions_state.json`) - Fast, survives restarts 2. **Events API** (cloud) - Permanent audit trail, survives local file loss ## When to Save (After EVERY action!) | Action | Save Memory | Log Event | |--------|-------------|-----------| | Web search returns results | ✅ append-memory | ✅ log-event (tool_call) | | Found a contractor/lead | ✅ append-memory | ✅ log-event (custom) | | Created assistant | ✅ save-memory | ✅ log-event (custom) | | Assigned phone number | ✅ save-memory | ✅ log-event (custom) | | Scheduled a call/SMS | ✅ append-memory | ✅ log-event (custom) | | Call completed | ✅ save-memory | ✅ log-event (custom) | | Got quote/insight | ✅ save-memory | ✅ log-event (custom) | | Made a decision | ✅ save-memory | ✅ log-event (message) | | Step started | ✅ save-memory | ✅ update-step (in_progress) + log-event (step_started) | | Step completed | ✅ save-memory | ✅ update-step (completed) + log-event (step_completed) | | Step failed | ✅ save-memory | ✅ update-step (failed) + log-event (error) | | Error occurred | ✅ save-memory | ✅ log-event (error) | ## Memory Commands (Local Backup) ```bash # Save a single value python telnyx_api.py save-memory "<slug>" "key" '{"data": "value"}' # Append to a list (great for collecting multiple items) python telnyx_api.py append-memory "<slug>" "contractors" '{"name": "ABC Co", "phone": "+1234567890"}' # Retrieve memory python telnyx_api.py get-memory "<slug>" # Get all memory python telnyx_api.py get-memory "<slug>" "key" # Get specific key ``` ## Event Commands (Cloud Backup) ```bash # Log an event (step_id is REQUIRED - links event to a plan step) python telnyx_api.py log-event <mission_id> <run_id> <type> "<summary>" <step_id> '[payload_json]' # Event types: tool_call, custom, message, error, step_started, step_completed # step_id: Use the step_id from your plan (e.g., "research", "setup", "calls") # Use "-" if event doesn't belong to a specific step ``` ## Example: Complete Save Pattern After finding a contractor via web search, do BOTH: ```bash # 1. Save to local memory (fast recovery) python telnyx_api.py append-memory "find-window-washers" "contractors_found" '{"name": "ABC Cleaning", "phone": "+13125551234", "source": "google search"}' # 2. Log to events API with step_id (permanent cloud record linked to plan step) python telnyx_api.py log-event "$MISSION_ID" "$RUN_ID" custom "Found contractor: ABC Cleaning +13125551234" "research" '{"contractor": "ABC Cleaning", "phone": "+13125551234", "source": "google search"}' ``` After scheduling a call: ```bash # 1. Local memory python telnyx_api.py append-memory "find-window-washers" "calls_scheduled" '{"event_id": "evt_123", "contractor": "ABC Cleaning", "time": "2024-12-01T15:00:00Z"}' # 2. Cloud event with step_id python telnyx_api.py log-event "$MISSION_ID" "$RUN_ID" custom "Scheduled call to ABC Cleaning for 3:00 PM" "calls" '{"scheduled_event_id": "evt_123", "contractor": "ABC Cleaning", "scheduled_for": "2024-12-01T15:00:00Z"}' ``` After getting a quote from a call: ```bash # 1. Local memory python telnyx_api.py save-memory "find-window-washers" "quotes" '{"ABC Cleaning": {"amount": 350, "available": "next week"}}' # 2. Cloud event with step_id python telnyx_api.py log-event "$MISSION_ID" "$RUN_ID" custom "Call completed: ABC Cleaning quoted $350" "calls" '{"contractor": "ABC Cleaning", "quote": 350, "availability": "next week", "conversation_id": "conv_xyz"}' ``` ## Best Practices 1. **Save IMMEDIATELY** - Don't wait, don't batch 2. **Save to BOTH** - Memory (local) AND Events (cloud) 3. **Be verbose** - More data saved = easier recovery 4. **Include context** - Timestamps, sources, IDs 5. **Save partial results** - Something is better than nothing 6. **Save before risky operations** - Before long API calls or waits --- ## When to Use This Skill This skill has two modes: **full missions** (tracked, multi-step) and **simple calls** (one-off, no mission overhead). Pick the right one. ### Use a Full Mission When: - The task involves **multiple calls or SMS** (batch outreach, surveys, sweeps) - You need a **complete audit trail** with events, plans, and state tracking - The task is **multi-step** and takes significant effort across phases - **Retries and failure tracking** matter - You need to **compare results** across multiple calls Examples: - "Find me window washing contractors in Chicago, call them and negotiate rates" - "Contact all leads in this list and schedule demos" - "Call 10 weather stations and find the hottest one" ### Do NOT Use a Mission When: - The task is a **single outbound call** — just create an assistant (or reuse one) and schedule the call directly - It's a **one-off SMS** — schedule it and done - The task doesn't need tracking, plans, or state recovery - You'd be creating a mission with one step and one call — that's overengineering **For simple calls, just:** ```bash # Reuse or create an assistant python telnyx_api.py list-assistants --name=<relevant> # Schedule the call python telnyx_api.py schedule-call <assistant_id> <to> <from> <datetime> <mission_id> <run_id> <step_id> # Poll for completion python telnyx_api.py get-event <assistant_id> <event_id> # Get insights python telnyx_api.py get-insights <conversation_id> ``` No mission, no run, no plan. Keep it simple. ## Required Setup The Python script `telnyx_api.py` handles all API calls. Check that `TELNYX_API_KEY` environment variable is set: ```bash python telnyx_api.py check-key ``` # State Persistence The script automatically manages state in `.missions_state.json`. This survives restarts and supports multiple concurrent missions. ## State Commands ```bash # List all active missions python telnyx_api.py list-state # Get state for a specific mission python telnyx_api.py get-state "find-window-washing-contractors" # Remove a mission from state python telnyx_api.py remove-state "find-window-washing-contractors" ``` --- # Core Workflow ## Phase 1: Initialize Tracking ### Step 1.1: Create a Mission ```bash python telnyx_api.py create-mission "Brief descriptive name" "Full description of the task" ``` **Save the returned `mission_id`** - you'll need it for all subsequent calls. ### Step 1.2: Start a Run ```bash python telnyx_api.py create-run <mission_id> '{"original_request": "The exact user request", "context": "Any relevant context"}' ``` **Save the returned `run_id`**. ### Step 1.3: Create a Plan Before executing, outline your plan: ```bash python telnyx_api.py create-plan <mission_id> <run_id> '[ {"step_id": "step_1", "description": "Research contractors online", "sequence": 1}, {"step_id": "step_2", "description": "Create voice agent for calls", "sequence": 2}, {"step_id": "step_3", "description": "Schedule calls to each contractor", "sequence": 3}, {"step_id": "step_4", "description": "Monitor call completions", "sequence": 4}, {"step_id": "step_5", "description": "Analyze results and select best options", "sequence": 5} ]' ``` ### Step 1.4: Set Run to Running ```bash python telnyx_api.py update-run <mission_id> <run_id> running ``` ### High-Level Alternative: Initialize Everything at Once Use the `init` command to create mission, run, plan, and set status in one step: ```bash python telnyx_api.py init "Find window washing contractors" "Find contractors in Chicago, call them, negotiate rates" "User wants window washing quotes" '[ {"step_id": "research", "description": "Find contractors online", "sequence": 1}, {"step_id": "setup", "description": "Create voice agent", "sequence": 2}, {"step_id": "calls", "description": "Schedule and make calls", "sequence": 3}, {"step_id": "analyze", "description": "Analyze results", "sequence": 4} ]' ``` This also automatically resumes if a mission with the same name already exists. --- ## Phase 2: Voice/SMS Agent Setup When your task requires making calls or sending SMS, create an AI assistant first. ### Step 2.1: Create a Voice/SMS Assistant **For phone calls:** ```bash python telnyx_api.py create-assistant "Contractor Outreach Agent" "You are calling on behalf of [COMPANY]. Your goal is to [SPECIFIC GOAL]. Be professional and concise. Collect: [WHAT TO COLLECT]. If they cannot talk now, ask for a good callback time." "Hi, this is an AI assistant calling on behalf of [COMPANY]. Is this [BUSINESS NAME]? I am calling to inquire about your services. Do you have a moment?" '["telephony"]' ``` **For SMS:** ```bash python telnyx_api.py create-assistant "SMS Outreach Agent" "You send SMS messages to collect information. Keep messages brief and professional." "Hi! I am reaching out on behalf of [COMPANY] regarding [PURPOSE]. Could you please reply with [REQUESTED INFO]?" '["messaging"]' ``` **Save the returned `assistant_id`**. ### Step 2.2: Find and Assign a Phone Number #### 2.2.1: List Available Phone Numbers ```bash python telnyx_api.py list-phones --available ``` Or get the first available one directly: ```bash python telnyx_api.py get-available-phone ``` **If no phone numbers are available, STOP and inform the user:** > "No available phone numbers found. You need to purchase phone numbers from Telnyx at https://portal.telnyx.com before I can make calls." #### 2.2.2: Get Assistant's Connection ID ```bash # For voice calls python telnyx_api.py get-connection-id <assistant_id> telephony # For SMS python telnyx_api.py get-connection-id <assistant_id> messaging ``` #### 2.2.3: Assign Phone Number to Assistant ```bash # For voice calls python telnyx_api.py assign-phone <phone_number_id> <connection_id> voice # For SMS python telnyx_api.py assign-phone <phone_number_id> <connection_id> sms ``` ### High-Level Alternative: Setup Agent in One Step Use the `setup-agent` command to create assistant and assign phone number: ```bash python telnyx_api.py setup-agent "find-window-washing-contractors" "Contractor Caller" "You are calling to get quotes for commercial window washing. Ask about: rates per floor, availability, insurance. Be professional." "Hi, I am calling to inquire about your commercial window washing services. Do you have a moment to discuss rates?" ``` This automatically: - Creates the assistant with telephony features - **Links the agent to the mission run** (if mission_id and run_id are in state)