# SMS to Voice Agent (HVAC Technician) > **Use case**: High-volume blue-collar hiring where you need to quickly screen candidates via SMS before scheduling a voice interview. Perfect for trades like HVAC, plumbing, electrical, and warehouse roles where candidates are often on the go and respond better to text messages first. ## What You'll Build A two-stage hiring pipeline: 1. **SMS Screening** — An AI agent texts candidates to verify basic qualifications (license, availability, transportation) using yes/no and numeric questions. Candidates who fail dealbreaker criteria are automatically disqualified. 2. **Voice Interview** — Qualified candidates are invited to a voice interview where the AI asks role-specific questions and scores responses on a 1–5 scale. *** ## Step 1: Create the Agent Create a posting with a two-step `workflow`: SMS screening first, then a voice interview. ```bash curl -X POST "https://api.heymilo.network/api/v4/postings" \ -H "X-API-KEY: your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "title": "HVAC Technician", "description": "We are hiring experienced HVAC technicians for residential and commercial installations. Must hold a valid EPA 608 certification. 3+ years of experience with split systems, heat pumps, and ductwork required. CDL or reliable transportation needed. Competitive pay $28-42/hr depending on experience.", "interviewer_name": "Tyler", "language": "en", "company_overview": "CoolAir Solutions is a leading HVAC contractor serving the greater metro area since 2005.", "job_overview": "Install, maintain, and repair HVAC systems for residential and commercial clients.", "workflow": [ { "type": "conversational_sms", "config": { "knockout_enabled": true }, "questions": [ { "modality": "sms", "text": "Do you hold a valid EPA 608 certification?", "question_type": "YES_NO", "expected_answer": "YES", "is_dealbreaker": true }, { "modality": "sms", "text": "Do you have reliable transportation to job sites?", "question_type": "YES_NO", "expected_answer": "YES", "is_dealbreaker": true }, { "modality": "sms", "text": "How many years of HVAC experience do you have?", "question_type": "NUMERIC", "expected_value": 3, "is_dealbreaker": true }, { "modality": "sms", "text": "Are you available to start within 2 weeks?", "question_type": "YES_NO", "expected_answer": "YES", "is_dealbreaker": false } ] }, { "type": "web_interview", "config": { "video": false, "num_questions": 5 }, "questions": [ { "modality": "voice", "text": "Walk me through a typical residential HVAC installation from start to finish.", "evaluation_criteria": "Assess depth of hands-on experience with split systems and ductwork. Look for knowledge of load calculations, refrigerant handling, and code compliance.", "score_of_1": "Cannot describe basic installation steps or confuses key concepts.", "score_of_5": "Provides detailed, confident walkthrough covering equipment selection, ductwork, charging, and testing.", "question_type": "open-ended", "score_weight": 3.0, "max_follow_ups": 2 }, { "modality": "voice", "text": "Describe a challenging repair you diagnosed. How did you troubleshoot it?", "evaluation_criteria": "Evaluate systematic troubleshooting approach and diagnostic skill.", "score_of_1": "Vague answer with no specific example.", "score_of_5": "Describes methodical diagnosis using gauges, electrical testing, and logical elimination.", "question_type": "open-ended", "score_weight": 3.0, "max_follow_ups": 2 }, { "modality": "voice", "text": "How do you handle safety on the job, especially when working with refrigerants and electrical?", "evaluation_criteria": "Check awareness of OSHA standards, EPA regulations, and safe work practices.", "score_of_1": "Shows no awareness of safety protocols.", "score_of_5": "Demonstrates strong safety culture including PPE, lockout/tagout, and proper refrigerant handling.", "question_type": "open-ended", "score_weight": 2.0, "max_follow_ups": 1 }, { "modality": "voice", "text": "Tell me about a time you dealt with a difficult customer on a service call.", "evaluation_criteria": "Assess customer service skills and professionalism under pressure.", "score_of_1": "No example or shows poor attitude toward customers.", "score_of_5": "Shows empathy, clear communication, and a resolution-focused approach.", "question_type": "open-ended", "score_weight": 1.0, "max_follow_ups": 1 }, { "modality": "voice", "text": "What types of HVAC systems are you most experienced with?", "evaluation_criteria": "Gauge breadth of experience across system types (split, packaged, mini-split, commercial rooftop, heat pumps).", "score_of_1": "Only familiar with one system type.", "score_of_5": "Experienced with multiple residential and commercial system types.", "question_type": "open-ended", "score_weight": 2.0, "max_follow_ups": 1 } ] } ] }' ``` **Response:** ```json { "object": "posting", "data": { "object": "posting", "id": "A1B2C3D4", "status": "active", "urls": { "candidate_url": "https://candidates.heymilo.io/coolair/hvac-technician", "ingestion_url_key": "ibURejyPMSlw6de0OZUdoxyoXTgWO78ey2NUo96EOG1gY", "review_url": "https://admin.heymilo.ai/w/WORKSPACE_ID/lab2/A1B2C3D4/1-details" }, "created_at": 1739612400.0, "posting": { ... } } } ``` Save the `id` (posting ID) from the response — you'll need it for the next steps. {% hint style="info" %} **Tip**: The SMS agent (`Tyler`) will automatically text candidates in a conversational style. The `is_dealbreaker: true` questions will immediately disqualify candidates who answer incorrectly. Only candidates who pass all dealbreakers will advance to the voice interview. {% endhint %} *** ## Step 2: Manage Questions After Creation Once the agent is created, you can list, edit, reorder, or add new questions at any time using the Questions API. ### List current questions ```bash curl -X GET "https://api.heymilo.network/api/v4/postings/A1B2C3D4/questions" \ -H "X-API-KEY: your_api_key_here" ``` ### Filter by modality View only the SMS screening questions: ```bash curl -X GET "https://api.heymilo.network/api/v4/postings/A1B2C3D4/questions?modality=sms" \ -H "X-API-KEY: your_api_key_here" ``` ### Add a new SMS question Maybe you realize you also want to ask about overtime availability: ```bash curl -X POST "https://api.heymilo.network/api/v4/postings/A1B2C3D4/questions" \ -H "X-API-KEY: your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "modality": "sms", "text": "Are you willing to work overtime and weekends when needed?", "question_type": "YES_NO", "expected_answer": "YES", "is_dealbreaker": false }' ``` ### Update an existing question Change the wording or make a question a dealbreaker: ```bash curl -X PATCH "https://api.heymilo.network/api/v4/postings/A1B2C3D4/questions/{question_id}" \ -H "X-API-KEY: your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "text": "Do you have at least 3 years of hands-on HVAC experience?", "is_dealbreaker": true }' ``` ### Delete a question ```bash curl -X DELETE "https://api.heymilo.network/api/v4/postings/A1B2C3D4/questions/{question_id}" \ -H "X-API-KEY: your_api_key_here" ``` *** ## Step 3: Ingest Candidates Now add candidates to the pipeline. The SMS agent will automatically reach out via text. ### Single candidate ```bash curl -X POST "https://api.heymilo.network/api/v4/postings/A1B2C3D4/candidates" \ -H "X-API-KEY: your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "name": "Mike Torres", "email": "mike.torres@email.com", "phone_number": "+15551234567", "metadata": { "source": "indeed", "applied_date": "2026-03-15" } }' ``` **Response:** ```json { "object": "candidate", "data": { "object": "candidate", "interview_id": "D536A69A4090E13F", "interview_url": "https://candidates.heymilo.io/coolair/i/D536A69A4090E13F", "posting_id": "A1B2C3D4" } } ``` Save the `interview_id` — you'll use it to check results later. ### Bulk ingest For high-volume roles, ingest multiple candidates at once: ```bash curl -X POST "https://api.heymilo.network/api/v4/postings/A1B2C3D4/candidates/bulk" \ -H "X-API-KEY: your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "data": [ { "name": "Sarah Johnson", "email": "sarah.j@email.com", "phone_number": "+15559876543", "metadata": {"source": "job_fair"} }, { "name": "Carlos Rivera", "email": "c.rivera@email.com", "phone_number": "+15555551234", "metadata": {"source": "referral"} }, { "name": "James Wilson", "email": "j.wilson@email.com", "phone_number": "+15558884321", "metadata": {"source": "indeed"} } ] }' ``` {% hint style="warning" %} **Phone numbers are required** for SMS workflows. Without a valid phone number, the SMS agent cannot reach the candidate and they will be stuck at the SMS step. Use E.164 format (e.g., `+15551234567`). {% endhint %} *** ## Step 4: See Results ### List all candidates for the posting ```bash curl -X GET "https://api.heymilo.network/api/v4/postings/A1B2C3D4/candidates" \ -H "X-API-KEY: your_api_key_here" ``` This returns a summary for each candidate with their overall score and workflow progress. ### Get full interview data for a candidate ```bash curl -X GET "https://api.heymilo.network/api/v4/interviews/D536A69A4090E13F/data" \ -H "X-API-KEY: your_api_key_here" ``` **Response (after completion):** ```json { "object": "interview_data", "data": { "object": "interview_data", "interview_id": "D536A69A4090E13F", "posting_id": "A1B2C3D4", "name": "Mike Torres", "email": "mike.torres@email.com", "score": 78.5, "status": "completed", "workflow": { "steps": [ { "id": "conversational_sms", "order": 1, "status": "complete", "started": true, "completed": true }, { "id": "web_interview", "order": 2, "status": "complete", "started": true, "completed": true } ], "all_complete": true }, "sms": { "object": "sms_result", "interview_id": "D536A69A4090E13F", "is_eligible": true, "confidence": 0.92, "criteria": [ { "criteria_id": "sms_001", "criteria_text": "Do you hold a valid EPA 608 certification?", "passed": true, "confidence": 0.95, "is_dealbreaker": true, "reasons": ["Candidate confirmed EPA 608 Universal certification"] }, { "criteria_id": "sms_002", "criteria_text": "How many years of HVAC experience do you have?", "passed": true, "confidence": 0.90, "is_dealbreaker": true, "reasons": ["Candidate stated 7 years of experience, meets minimum of 3"] } ], "transcript": [ {"role": "agent", "text": "Hi Mike! This is Tyler from CoolAir Solutions..."}, {"role": "candidate", "text": "Yes I have my EPA 608 Universal cert"} ] }, "web_interview": { "object": "web_interview_result", "interview_id": "D536A69A4090E13F", "match_score": 78, "highlights": [ "Strong hands-on experience with residential systems", "Good troubleshooting methodology" ], "lowlights": [ "Limited commercial experience" ], "scorecard": [ { "question_id": "q1", "question": "Walk me through a typical residential HVAC installation...", "evaluation_score": 4, "evaluation_summary": "Detailed walkthrough of split system installation including proper refrigerant charging procedures.", "score_weight": 3.0 } ], "audio_recording_url": "https://cdn.heymilo.io/recordings/abc123.mp3" } } } ``` ### Set up a webhook for real-time notifications Instead of polling, get notified when interviews complete: ```bash curl -X POST "https://api.heymilo.network/api/v4/webhooks" \ -H "X-API-KEY: your_api_key_here" \ -H "Content-Type: application/json" \ -d '{ "posting_id": "A1B2C3D4", "url": "https://your-ats.com/heymilo-webhook", "event_type": "interview_completed" }' ``` *** ## Summary | Step | Endpoint | What Happens | | ------------------------- | --------------------------------------------------- | ------------------------------------------------------------ | | Create agent | `POST /v4/postings` | Two-stage pipeline created (SMS + Voice) with your questions | | Manage questions | `GET/POST/PATCH/DELETE /v4/postings/{id}/questions` | Edit, add, remove, or reorder questions at any time | | Ingest candidate | `POST /v4/postings/{id}/candidates` | Tyler texts the candidate immediately | | SMS screen completes | *(automatic)* | Candidates who pass all dealbreakers advance to voice | | Voice interview completes | *(automatic)* | AI scores each answer 1–5 and generates a scorecard | | Get results | `GET /v4/interviews/{id}/data` | Full SMS transcript, voice scorecard, and recordings | | Webhook | `POST /v4/webhooks` | Get notified in real-time when stages complete | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.admin.heymilo.ai/api-next-gen/guides/sms-to-voice-agent.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.