Complete AI Outbound Call System for Construction

AI Outbound Caller for Construction Contractor — Complete, Integrate, Test & Deploy We have an existing Node.js / TypeScript AI outbound caller project that needs to be proof-checked, completed, connected to live services, debugged, tested, and prepared for deployment. This is for a construction contractor. The system will call prequalified commercial construction leads from HubSpot, speak with builders / estimators / PMs / CAs, identify the correct project contact, request project documents, update HubSpot, create follow-up tasks, and notify the business owner/director when documents are received. This is not a prototype job. We need someone who can complete the full working system. Current Project Includes The existing ZIP already contains: Node.js / TypeScript / Express backend PostgreSQL schema and migrations Project/contact/call-session logic Call eligibility logic Suppression / do-not-call logic 7-day contact cooldown rule 72-hour project cooldown rule Twilio outbound call initiation Twilio Voice webhook Twilio status webhook Twilio Media Streams WebSocket endpoint OpenAI Realtime bridge concept Construction contractor AI sales-agent prompt Structured outcome extraction logic HubSpot workflow service Follow-up action service SMS STOP / opt-out handling concept API authentication, rate limiting, Helmet, logging Dockerfile, docker-compose, .env.example, README notes However, it is not production-ready. It needs full audit, bug fixing, integration, real testing, and deployment preparation. Final System Must Do The final system must: Pull/read prequalified companies, contacts and projects from HubSpot. Select eligible contacts based on cooldown, suppression and project rules. Call contacts through Twilio. Connect call audio to OpenAI Realtime using Twilio Media Streams. Use the construction contractor sales-agent prompt. Ask whether the person answering is the correct PM / CA / estimator. If not, collect the correct person’s name, role, email and phone. Create the new contact in HubSpot if needed. Link the new contact to the correct company and exact project/deal. Call the correct PM / CA / estimator. Ask about project/package status, documents, specs, deadline and expected start date. Capture transcript and structured outcome. Update PostgreSQL and HubSpot. Create HubSpot notes, tasks and stage updates. Send/queue follow-up email or SMS where required. Detect opt-out / do-not-call and suppress future calls. Notify owner/director when documents are received. Create calendar reminder 2 days before quote/tender deadline. Generate daily/weekly summary reports. Be deployable with clear documentation. Mandatory Call Flow 1. First call The AI calls the contact linked to the project/deal and asks: “Hi [Name], I’m calling regarding [Project Name]. Are you the person handling this package, or would that sit with the PM, CA or estimator?” 2. If correct person The AI asks: Is the package still open? Are you accepting pricing? Can you send project documents/drawings/specs/schedules? What is the quote/tender deadline? When is the expected start date? Who should be copied in? Then the system logs the call and updates HubSpot. 3. If wrong person The AI must ask for the correct PM / CA / estimator details: Name Role Email Phone/mobile Company Project relationship Then the system must: Search HubSpot by email/phone Avoid duplicate contacts Create new contact if needed Link contact to company Link contact to exact project/deal Add HubSpot note explaining how contact was found Schedule or trigger a call to the new contact 4. Second call The AI calls the newly discovered contact using project context: “Hi [Name], I was given your details regarding [Project Name]. I understand you may be handling the package on that project. I’m just checking where that package is sitting at the moment.” Required HubSpot Stages / Filters The system must update the project/deal into the correct stage/filter: Not Contacted Didn’t Answer Contact Mapping Required New Contact Found Contacted – Waiting for Documents Documents Received Quoted Not Interested Already Got Contractor Project Not Ready Completed Do Not Call / Suppressed Developer must document whether these are deal stages, custom properties, lists/views, or a combination. Required Call Outcomes Every call must produce one structured outcome: Didn’t Answer Contact Mapping Required New Contact Found Contacted – Waiting for Documents Documents Received Quoted Not Interested Already Got Contractor Project Not Ready Completed Opt-Out / Do Not Call Each outcome must trigger the correct HubSpot update, follow-up task, suppression rule, or next call. Documents Received Workflow When documents/drawings/specs/schedules are received, the system must: Mark project/deal as Documents Received. Link/attach documents to the project if possible. Notify owner/director by email or task. Include project name, company, contact details, call summary, deadline and expected start date. Create a calendar reminder 2 days before the quote/tender deadline. Include all key notes in the calendar event. Calendar can be Google Calendar, Microsoft Calendar or HubSpot task/calendar workflow. Main Work Required Full Audit & Fixes Review and fix: TypeScript code quality Broken imports / dead code Environment variables Database schema and migrations Internal/external ID consistency API routes and middleware Authentication and rate limiting Twilio webhook validation OpenAI Realtime bridge HubSpot workflow logic Follow-up logic Outcome extraction SMS opt-out handling Deployment setup Security risks Race conditions Duplicate call/contact risks Twilio Integration Fully connect and test: Outbound calls Caller ID / phone number Voice webhook Status callback Media Streams WebSocket Signature validation No-answer / busy / failed / completed handling Call SID, duration and recording URL storage OpenAI Realtime Integration Fully connect and test: Twilio audio → OpenAI OpenAI audio → Twilio Prompt injection with project/contact context Transcript capture Fallback responses Escalation for technical/warranty/capacity/contract questions Timeout/silence/error handling HubSpot Integration Fully connect and test: Contact/company/deal mapping New contact creation Contact-to-company association Contact-to-project/deal association Call notes Tasks Deal stage updates Duplicate prevention Idempotency protection Required HubSpot fields/stages documentation Eligibility Rules Implement and verify: No calls to do-not-call contacts No calls to suppressed/completed/lost projects Same contact max once every 7 days Same project max once every 72 hours unless override Respect SMS STOP / opt-out Max failed attempts Batch multiple projects for same contact where possible Prevent duplicate calls Outcome Extraction Extract and validate: Call outcome Correct contact found New contact details Package/project status Documents/specs/schedules status Quote/tender deadline Expected start date Objection/rejection reason Sentiment Follow-up required/date Escalation required/reason Opt-out detected Suggested HubSpot stage Summary note Invalid AI JSON must retry or fail safely. Testing Required Developer must provide proof of: npm install npm run build npm test Database migration test API route tests Eligibility tests Contact discovery tests HubSpot contact creation test HubSpot association test Twilio test call AI voice response test Transcript capture test Outcome extraction test HubSpot note/task/deal update test No-answer test Opt-out test Suppression/cooldown test Documents received workflow test Director notification test Calendar reminder test Do not claim completion unless the full flow has been tested. Final Deliverables Freelancer must provide: Updated full source code ZIP GitHub repo/branch with clean commits Working deployed backend PostgreSQL schema/migrations .env.example Full README Twilio setup guide HubSpot setup guide OpenAI setup guide Calendar setup guide Deployment guide Testing report Required environment variables Required HubSpot fields/stages Proof of successful build Proof of successful test call Proof of HubSpot contact creation/association Proof of HubSpot note/task/stage update Proof of director notification and calendar event Short Loom/video walkthrough Final handover document Required Experience Please only apply if you have experience with: Node.js / TypeScript / Express PostgreSQL REST APIs and WebSockets Twilio Programmable Voice / Media Streams OpenAI Realtime or AI voice agents HubSpot CRM API and associations Webhook validation CRM workflow automation Calendar API integration Docker / deployment Security best practices Bonus: experience with outbound sales automation, construction/B2B CRM workflows, Twilio + OpenAI voice agents. Acceptance Criteria The project is complete only when the system can: Select eligible HubSpot contacts Call through Twilio Speak with AI voice Identify whether the person is the correct PM / CA / estimator Collect and create/link new contacts if needed Call the correct contact Classify the outcome Update HubSpot correctly Create follow-up tasks Notify owner/director when documents are received Create calendar reminder 2 days before quote deadline Respect do-not-call and cooldown rules Run safely in a controlled pilot with real contacts