Inbound Call Center Software Build

# TelesalesOS — Telnyx Telephony/ACD Contact Center Developer

Our stack is Next.js, React, TypeScript, Supabase/Postgres/Auth/Realtime, Vercel and GitHub.

We need an experienced programmable-voice/contact-center developer to build the Telnyx-powered telephony portion. This is not a simple click-to-call integration. We need a production-grade browser softphone, inbound ACD, queues, routing rules, supervisor monitoring, recordings, CRM screen pops, compliance controls and searchable call logs.

## Required experience

Applicants should have real experience with several of the following:

* Telnyx Voice API/Call Control
* Telnyx JavaScript or React WebRTC SDK
* SIP and WebRTC
* Browser softphones
* ACD/contact-center development
* Call queues and routing
* Telnyx conferences
* Monitor, whisper and barge
* Call recording
* Node.js/TypeScript
* PostgreSQL/Supabase
* Realtime agent presence
* Event-driven webhooks
* AWS S3/Object Lock
* Multi-tenant SaaS security

Basic Twilio/Telnyx API experience is insufficient. You must understand call legs, call sessions, SIP/WebRTC registration, webhook retries, duplicate and out-of-order events, atomic agent reservation and production call failures.

## Existing platform

* Next.js/React/TypeScript
* Tailwind and shadcn/ui
* Supabase Postgres
* Supabase Authentication
* Supabase Realtime
* Vercel
* GitHub
* Telnyx
* Stripe
* Planned AWS S3 recording archive

The existing repository must remain the source of truth. Work will be submitted through branches and reviewed pull requests.

# Required functionality

## 1. Multi-tenant telephony

Every number, agent, queue, campaign, call, recording, routing rule and usage record belongs to an organization.

Roles:

* Super Admin
* Agency Admin
* Sales Manager
* Retention Manager
* Agent
* QA/Compliance Reviewer

Supabase Row Level Security and server-side authorization are required. Client-side filtering is not sufficient. No agency may access another agency’s calls, recordings or users.

## 2. Browser softphone

Build an embedded Telnyx WebRTC phone with:

* Secure short-lived authentication tokens
* Inbound and outbound calls
* Answer/reject/hang up
* Mute/unmute
* Hold/resume
* Dial pad/DTMF
* Warm and cold transfers
* Conference participant
* Call timer and connection status
* Audio-device selection
* Incoming-call notification
* Reconnection/error handling
* Notes, dispositions and wrap-up timer
* Automatic CRM association

Never expose Telnyx API keys, permanent SIP credentials or Supabase service-role keys in the browser.

## 3. Agent presence

Track:

* Offline
* Available
* Reserved
* Ringing
* On Call
* On Hold
* After-Call Work
* Break
* Training
* Do Not Disturb

Presence needs heartbeat/expiration behavior when browsers close or internet connections fail. Agent reservation must be atomic so two calls cannot select the same agent.

The developer should recommend whether managed Redis is needed alongside Supabase for presence, locks and low-latency routing.

## 4. Inbound ACD and queues

Initial required queues:

1. Sales
2. Retention

Admins must be able to create more queues without code changes.

Queue settings should include:

* Assigned numbers, teams and agents
* Agent skills and priorities
* Product and language
* State-license requirements
* Ring and maximum wait times
* Wrap-up time
* Business hours and holidays
* Overflow queue/number
* Voicemail
* Callback option
* Recording settings
* Service-level targets

Routing strategies:

* Longest idle
* Round robin
* Weighted
* Priority based
* Skill based
* State-license based
* Language based
* Product based
* Assigned agent/lead owner
* Last agent
* Campaign based
* Overflow and fallback

The routing decision and reason must be stored for auditing.

## 5. Campaigns and outbound calls

Campaigns require:

* Name and organization
* Inbound/outbound type
* Queue
* Agents
* Caller ID/number pool
* Product and lead source
* State restrictions
* Business hours
* Routing rules
* Consent requirements
* Script
* Dispositions
* Active/paused status

Initial outbound modes:

* Manual dialing
* CRM click-to-call
* Preview dialing
* Agent-requested next lead
* Manager-assigned lists

Do not build an unattended predictive/autodialing system without separate written approval.

## 6. CRM screen pops

An inbound call must automatically open the matching CRM lead/contact using the caller number, dialed number, campaign, lead owner, source and recent activity.

Display:

* Prospect information
* Product interest
* Lead source/vendor
* Assigned agent
* Notes and prior calls
* Appointments
* DNC status
* TrustedForm evidence
* Jornaya evidence
* Dynamic script

If no match exists, the agent can create a lead while remaining on the call. Outbound calls must automatically link to the correct lead, agent and campaign.

## 7. Configurable routing rules

Admins must configure routing without code changes using:

* Queue/campaign
* Called number
* Lead source/vendor
* State and agent licensing
* Product/language
* Time zone/business hours
* Agent skills/priority
* Lead ownership
* Previous agent
* Contact-attempt count
* Consent and DNC status
* Sales versus retention purpose

Support rule priority, conditions, actions, fallbacks, effective dates, versions, test mode and audit logs.

## 8. Live-call supervisor dashboard

Authorized Super Admins, Admins and Managers need a Live Calls screen showing:

* Agent and prospect
* Queue and campaign
* Call direction/status
* Start time/duration
* Hold and recording status
* CRM record
* Connection health

Controls:

* Monitor: supervisor hears the call but neither party hears the supervisor
* Whisper: agent hears the supervisor but prospect does not
* Barge: both parties hear the supervisor
* Change modes or leave

Use Telnyx conference supervisor functionality where appropriate. Every supervisor action must be authorized and logged with supervisor, agent, call, mode, timestamp and result.

## 9. Recording and seven-year retention

Support automatic inbound/outbound recording, dual-channel audio where practical, recording announcements, jurisdiction settings, recording status and failure alerts.

Telnyx is the recording origin, not the permanent archive.

After the Telnyx recording-saved webhook, recordings must be archived in TelesalesOS-controlled AWS storage using:

* S3 Object Lock
* Versioning
* Encryption
* Restricted IAM
* Seven-year retention
* Legal holds
* Integrity hashes
* Audit logs
* Secure expiring playback URLs
* Lifecycle and disaster-recovery procedures

Ordinary agents and managers cannot delete recordings.

## 10. Searchable call logs

Search by:

* Date/time range
* Agent/team
* Prospect/telephone number
* Direction
* Queue/campaign
* Lead source/vendor
* Disposition/status
* Recording availability
* TrustedForm/Jornaya status
* Supervisor participation

Store internal and Telnyx identifiers, call legs/session, organization, lead, numbers, timestamps, ring/talk/hold/wrap-up duration, hang-up cause, disposition, notes, recording references, routing decision, consent evidence and usage cost.

Store timestamps in UTC and display them in the user’s selected time zone.

## 11. TrustedForm, Jornaya and consent evidence

CRM leads must store:

* TrustedForm certificate URL/ID
* Jornaya LeadID
* Consent timestamp
* Consent language/version
* Source URL
* Vendor
* Lead timestamp
* Consent scope
* Covered telephone number
* Validation status/history

TelesalesOS must receive these fields through API lead ingestion, display them in the CRM/calling screen, preserve their relationship to each call and pass permitted tokens to approved systems.

Configurable rules may flag or block dialing when required evidence is missing. Do not claim that a token automatically makes a call compliant.

## 12. DNC controls

Before calling, check:

* Contact DNC
* Organization DNC
* Platform suppression
* Campaign suppression
* Calling hours
* Consent requirements

DNC status must prevent future automated contact. Store the source, reason and timestamp. Ordinary users cannot bypass it. Unauthorized overrides must be rejected and logged.

The architecture should support future SMS STOP handling.

## 13. Usage and billing ledger

Track each call’s organization, agent, duration, Telnyx cost, TelesalesOS charge, recording/transcription costs and billing classification.

Business rules:

* Agents receiving free company leads do not personally pay telco charges.
* Other agents may pay their own usage.

Create an auditable ledger that can later connect to Stripe. Use integer minor units or precise decimal fields, never floating-point money calculations.

## 14. Webhooks and reliability

Telnyx webhooks must be:

* Signature verified
* Idempotent
* Quickly acknowledged
* Processed asynchronously where appropriate
* Safe against duplicates/out-of-order delivery
* Retried with backoff
* Sent to a failure/dead-letter process
* Correlated to call sessions/legs
* Reconciled when local and Telnyx states disagree

Implement structured logs, correlation IDs, health checks, error monitoring and alerts for webhook delays, dropped calls, WebRTC failures and recording failures.

## 15. Backend infrastructure

Vercel can host the Next.js interface and ordinary APIs.

Persistent WebSockets, realtime media streams and long-running call processes require an appropriate persistent service. Propose AWS ECS/Fargate, App Runner, Fly.io, Render, Cloud Run or another justified option.

Preferred backend language: TypeScript/Node.js.

Future AI call coaching will use live Telnyx media streaming, transcription and OpenAI. It is not part of the initial milestone, but the architecture must support it later.