Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spn.wtf/llms.txt

Use this file to discover all available pages before exploring further.

​
Lead Lifecycle

new
  -> dispatched
  -> new       retry scheduled after failed/unanswered/rejected call
  -> failed    retry limit reached or invalid lead
scheduler.py only selects leads where: 
status = 'new'
AND (retry_after IS NULL OR retry_after <= NOW())
When a SIP call is successfully triggered, the lead is marked dispatched.

​
Call Lifecycle

calling
  -> called    qualification JSON saved
  -> pushed    Talking Shops task created
  -> failed    rejected, unanswered, dispatch failed, stale, startup failure, or no answers
Each dial attempt gets its own calls row. This means one lead can have multiple call attempts over time.

​
Successful Call Flow

  1. Lead starts as new.
  2. Scheduler validates call window and phone number.
  3. Scheduler creates a calls row with status='calling'.
  4. Scheduler calls LiveKit create_sip_participant.
  5. LiveKit uses the configured outbound SIP trunk to call the lead through Vobiz.
  6. Agent joins ignitech-lead-{lead_id}.
  7. Lead answers and speaks with the agent.
  8. Agent extracts structured qualification.
  9. db.save_qualification() stores JSON and marks the call called.
  10. talkingshops_pusher.py pushes the record to Talking Shops.
  11. db.set_call_pushed() marks the call pushed.

​
Failure Reasons

The calls.failure_reason field is machine-readable.
ReasonMeaning
rejectedCaller rejected or disconnected before usable conversation
unansweredCall was not answered
dispatch_failedLiveKit SIP participant creation failed
startup_failedAgent could not start or find the call context
stale_timeoutCall stayed in calling for too long
no_answersCall connected but no useful qualification data was captured

​
Retry Behavior

Retry scheduling is centralized in db.py. Default: 
MAX_CALL_RETRIES=3
When retryable failure occurs, the lead is set back to: 
status='new'
retry_after=now + 24 hours
retry_count=retry_count + 1
If retry_count exceeds MAX_CALL_RETRIES, the lead is marked failed.

​
Phone Validation

Outbound dialing is India-mobile focused. The scheduler accepts:
  • 98765XXXXX
  • 098765XXXXX
  • 9198765XXXXX
  • +9198765XXXXX
It rejects values that cannot safely become: 
+91XXXXXXXXXX
The local 10-digit mobile number must start with 6, 7, 8, or 9.

​
Whitelist Mode

For testing, you can restrict dialing to selected numbers: 
CALL_WHITELIST_NUMBERS=98765XXXXX,+9198765XXXXX
When this is set, any lead outside the whitelist is marked failed instead of called.