Widget leads were invisible to agents for up to 90s (60s auto-assign
poll + 30s worklist poll). Now triggers immediate auto-assign after
lead creation and emits SSE worklistUpdate so agents see new widget
leads and appointments instantly.
Also excluded packages/ from tsconfig build to prevent widget source
compilation errors.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Widget and WhatsApp flows send scheduledAt without timezone offset,
causing platform to interpret as UTC (10:00 shows as 3:30 PM IST).
Server now appends +05:30 if no timezone indicator present. Also fixed
in WhatsApp slot ID generation and widget source.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Comprehensive docs: embed snippet, key management, API endpoints,
chat/booking/contact flows, lead dedup, reCAPTCHA, branding, deploy
checklist, troubleshooting
- Widget Preact source archived in packages/widget-src/ (was only on
local machine, not tracked in any repo)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The rebuild from packages/helix-engage-widget/ produced an older version
without chat-start/leadId support. Restored the working version from
commit aa41a2a which has the complete chat flow.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Added COPY public ./public to Dockerfile so the Preact embed widget
is served via NestJS static assets at /widget.js.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Skill documents the full flow schema (Groups, Blocks, Edges, Variables),
all available tools, WhatsApp constraints, system variables, and
deployment steps. Enables generating new flows from natural language
descriptions — e.g., "create a prescription refill flow".
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Two messages arriving close together could start two parallel flow
executions for the same phone. The second would create a new session
while the first was mid-AI-block, causing duplicate greetings and
race conditions. Per-phone async lock ensures sequential execution.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- QrService: generates QR PNG from appointment data, cached in-memory
- GET /api/messaging/qr/:appointmentId serves the image (Gupshup needs URL)
- sendImage added to MessagingProvider + GupshupProvider
- send_appointment_qr tool registered in ToolRegistry
- Flow JSON updated: QR sent after booking confirmation
- Variable interpolation now supports dot notation ({{result.field}})
- SIDECAR_PUBLIC_URL env var for the QR image URL
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Added g4t (tomorrow), g4c (custom date) groups. Custom date asks
patient to type a date, AI block parses it to YYYY-MM-DD. Three
condition branches now: tomorrow, day_after, other.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
scheduledAt was passed as raw "slot:{id}:{datetime}" — platform rejected
it. Added extract_datetime expression to pull the ISO datetime from the
third segment. Updated flow JSON with SetVariableBlock after slot input.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Appointments created via WhatsApp had null patientId — lookup_appointments
couldn't find them. Now resolves patient before booking and includes
patientId in the createAppointment mutation. Fixed in both flow tool
registry and legacy messaging service.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
nest build only compiles TS — JSON files need explicit asset copy
in nest-cli.json compilerOptions.assets.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Groups + Blocks execution model adapted from Typebot:
- FlowExecutionService: walks through groups/blocks, pauses at InputBlocks
- FlowSessionService: Redis-backed session state (24h TTL)
- FlowStoreService: loads flow definitions from data/flows/ JSON files
- FlowVariableService: {{variable}} interpolation + expressions
- ToolRegistry: registered tool handlers (departments, doctors, slots, booking)
- Default appointment-booking.json flow seeded on first run
MessagingService delegates to flow engine when published flows exist,
falls back to hardcoded AI chat otherwise (backward compatible).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Groups + Blocks model adapted from Typebot. Execution loop pauses at
InputBlocks, resumes on next message. Tool registry bridges existing
tools. Session state in Redis with 24h TTL.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Check for duplicate patient+doctor+date and max 3 slots per time before
creating the appointment. Returns actionable message if conflict found.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Matched the working agent tool mutation — platform expects 'status'
for AppointmentCreateInput, not 'appointmentStatus'.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
WhatsApp list messages have strict limits: section title max 24 chars,
row title max 24 chars. Long doctor names + dates in section titles
caused Gupshup to silently drop the list options.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
AI wasn't calling send_slot_list after doctor selection because it didn't
know how to extract doctorId from "doc:{uuid}:{name}" format. Updated
system prompt with explicit selection_id parsing instructions for each
step of the booking flow.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Gupshup list_reply has empty id field — postbackText carries our ID.
Fixed ?? to || fallback. Also inject selection_id into user message so
AI can extract doctorId from "doc:{uuid}:{name}" format.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Was reading non-existent availableSlots field. Now reads raw visitSlots,
matches target date's day-of-week, and generates hourly time slots from
startTime to endTime. Doctors with 08:00-20:00 get 10 hourly options.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
AI was asking "which department?" in text instead of sending the
interactive list. Updated system prompt to be prescriptive: IMMEDIATELY
call send_department_list, never ask in text. Also injects hospital name
from theme config.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Provider-agnostic WhatsApp integration for AI-driven appointment booking:
- MessagingProvider interface (sendText, sendButtons, sendList, parseInbound)
- GupshupProvider implementation (Gupshup WhatsApp API)
- MessagingService — AI orchestration with tools (department/doctor/slot
lists via interactive WhatsApp messages, appointment booking, caller
resolution + context injection)
- Redis conversation history (24h TTL, matches WhatsApp session window)
- Webhook controller at POST /api/messaging/webhook
Swappable to Ozonetel or Meta Cloud API by implementing MessagingProvider
and switching MESSAGING_PROVIDER env var.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
History event persistence was gated behind if(mapped), but login returns
null for state (UI waits for release). LOGIN events were never written
to AgentEvent table → rollup computed 0 for loginDuration → idle/pause/
wrap all zero. Moved history persistence outside the state mapping gate.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
History event persistence was gated behind if(mapped), but login returns
null for state (UI waits for release). LOGIN events were never written
to AgentEvent table → rollup computed 0 for loginDuration → idle/pause/
wrap all zero. Moved history persistence outside the state mapping gate.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
When zero active packages exist, the KB silently omitted the section.
AI then responded "I couldn't find that" for package queries. Now always
includes the section header with explicit "not configured" guidance.
Also removed contradicting rule 8 (bullet points) — conflicts with the
structured output format that requires plain text sentences.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Root cause: CDR webhook fires 5s after dispose, stores monitorUCID.
Frontend has agent-side UCID from SIP. They never matched → disposition
not persisted, agent call history empty.
Fix:
- Dispose endpoint now creates Call records for ALL answered calls
(inbound + outbound), not just outbound. Record gets agent-side UCID
+ correct disposition immediately.
- Webhook checks if Call record already exists (by agent UCID via
monitorUCID→agentUCID mapping). If found, enriches with recording
URL, agent chain name, CDR timing. If not found, creates as fallback.
- SupervisorService stores UCID mapping from real-time events (which
carry both UCIDs). Auto-expires after 10 minutes.
Verified: UCID-MAP logged, dispose creates record, webhook enriches
without duplicating. DB shows correct agent UCID + disposition + recording.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- CallerContextService: added invalidateCache(leadId) method
- CallerResolutionController: POST /api/caller/invalidate-context
endpoint — frontend calls after appointment mutations to bust
stale AI context cache
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The build() method previously fetched Lead and Appointments in parallel.
When the input patientId was empty (outbound dial, first-time linkage),
the appointments query was skipped even though the Lead record in the DB
had a valid patientId. Now fetches Lead first, reads its patientId, then
fetches appointments/calls/activities in parallel with the correct ID.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Schema description reinforced: brief 2-3 sentence natural language only.
Prompt template updated with example output and explicit ban on markdown
headers, bold, bullet lists, and raw field labels in the message field.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- ai-response-schema.ts: Zod schema for { message, suggestions[] }
- ai-chat.controller.ts: Output.object({ schema }) on streamText
forces the LLM to return valid JSON matching the schema instead
of free-form prose. Supervisor mode excluded (uses tools, not schema).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- CallerContextService: fetches lead profile, appointments, call history,
activities in parallel. Caches in Redis (5 min TTL). Renders as
human-readable KB section — no UUIDs exposed to the LLM.
- Caller resolution controller: prewarms context cache on resolve
(fire-and-forget) so the AI stream has a cache hit.
- AI chat stream: injects caller context into system prompt KB instead
of raw Lead ID. LLM answers patient questions from context, no tool
calls needed for current caller data.
- Eliminates UUID hallucination: LLM never sees leadId or patientId,
can't pass wrong ID to wrong tool parameter.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- LogStreamService: ring buffer (500 entries) + getRecentLogs() method
- SupervisorController: GET /api/supervisor/logs/recent returns buffered
log entries so the desktop log panel shows history on tab open, not
just live stream
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- LogStreamService: singleton that extends ConsoleLogger, captures all
NestJS log output into an RxJS Subject while preserving stdout
- main.ts: uses LogStreamService.instance as app logger
- supervisor.controller.ts: new @Sse('logs/stream') endpoint pipes
log entries (timestamp, level, context, message) to connected clients
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
New worklist SSE stream replaces the 30s frontend poll. When the
missed-call webhook creates a Call record, it emits a worklist-updated
event via the supervisor's worklistSubject. All connected agents
receive the event immediately.
- supervisor.service.ts: worklistSubject + emitWorklistUpdate()
- supervisor.controller.ts: @Sse('worklist/stream') broadcast endpoint
- missed-call-webhook.controller.ts: emits after createCall() with
callerPhone + callerName for toast notification
- worklist.module.ts: imports SupervisorModule (forwardRef)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Three related fixes:
1. Disposition for answered inbound calls
Previously the dispose endpoint sent the agent's choice to Ozonetel
but never wrote it back to the platform Call record. The webhook's
pre-disposition value ("General Enquiry" → INFO_PROVIDED) persisted.
Now: dispose endpoint finds the Call by UCID and updates disposition
to the agent's actual selection.
2. SLA timing wiring (assignedAt / answeredAt / responseTimeS)
patchCallTiming() existed but was never called. Now wired into
handleCallEvent:
- "Calling" event → writes assignedAt (ring start)
- "Answered" event → writes answeredAt + computes responseTimeS
(answeredAt - startedAt = caller wait time)
Uses patchCallTimingByUcid helper that looks up Call by UCID.
3. Backfill maint endpoint: POST /api/maint/backfill-call-disposition-timing
Walks calls for a given date, joins to CDR by UCID (both legs),
patches disposition (from CDR's mapped value, always overwrites),
timing fields (answeredAt, assignedAt, responseTimeS from CDR),
and CDR-specific durations (handlingTimeS, acwDurationS, holdDurationS).
Idempotent — safe to run multiple times.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The default campaign name was hardcoded to 'Inbound_918041763265'.
After the Ozonetel campaigns were renamed (Inbound_918041763265 →
Global, Inbound_918041763400 → Ramaiah), agent login/dial would
break because the old name doesn't exist on Ozonetel anymore.
Campaign name now comes exclusively from the Agent entity's
campaignName field (per-agent) or the OZONETEL_CAMPAIGN_NAME env
var (per-workspace). No hardcoded fallback.
Three changes:
1. Await Ozonetel logout in /auth/logout — prevents race condition when
agent re-logs in quickly via "Remember me". The fire-and-forget
logoutAgent() left a window where the next loginAgent() arrived
while Ozonetel was still processing the previous logout, leaving
the agent stuck in "Telephony Unavailable". (#559)
2. Use agentConfig.sipPassword (from Agent entity) instead of
OZONETEL_AGENT_PASSWORD env var for login/logout/force-ready.
The env var was a single shared credential that ignored per-agent
passwords. Removed hardcoded "Test123$" fallback. Force-ready
now looks up the Agent entity by ozonetelAgentId to get the
correct sipPassword + sipExtension.
3. Missed-calls worklist query now fetches campaign { id campaignName }
so the frontend Branch column can show the campaign name instead
of the raw DID phone number.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Bug 553 (partial) — AI Panel 'Patient History' returned 'not in system'
even though the caller had 7 calls + an appointment. The model was
hallucinating instead of chaining lookup tools.
UUID safety: LLMs drop hyphens / swap chars on 36-char ids once the
context wears thin. To keep the model off the UUID path for 'this
caller' questions:
- lookup_appointments, lookup_call_history, lookup_lead_activities
now accept their id arguments OPTIONALLY
- when omitted, the sidecar resolves leadId from ctx and patientId
from the lead record (cached per-request)
- new lookup_lead_activities tool rounds out the patient-history
trio (call history + activity log + appointments)
System prompt (ccAgentHelper) tightened:
- chain call history + activities + appointments for history questions
- call lookup tools with NO arguments when using the current caller
- don't re-type UUIDs seen in CURRENT CONTEXT
- say 'feature not set up yet' when KB section is empty (packages,
etc.) instead of 'I couldn't find that'
All agent tools now emit structured [AI-TOOL] trace lines with full
UUIDs printed — tail sidecar logs to see which tool the model chose,
whether the model passed an id or used the context fallback, and how
many records came back. If the model ever hallucinates a UUID, the
resolved= field on the log line will echo it and count=0 will flag
the miss immediately.
Bug 560: Live Call Monitor showed ghost calls with runaway timers when
the agent wasn't on a call. Cause — activeCalls Map only added on
'Answered' and deleted on 'Disconnect'; a missed Disconnect (sidecar
restart, Ozonetel subscription hiccup, network blip) left the entry
lingering forever.
getActiveCalls() now sweeps stale entries before returning:
- drop if startTime is older than 30 minutes
- drop if the mapped agent is currently ready / offline / paused
(agent can't be on a call in any of those states)
Each sweep logs the reason so we can track how often this fires.
Per-tenant flag that hides self-serve setup surfaces when the product team owns onboarding for a workspace. Set HELIX_SETUP_MANAGED=true on the sidecar env for that tenant; the frontend reads this endpoint at boot, hides the Settings nav + Setup banner, and blocks /settings/* routes. Setup-state APIs stay live so ops can still drive the wizard remotely.
Unlock Agent / Force Ready shortcuts used to read the target agentId from localStorage helix_agent_config — supervisors don't have that set and got 400 'agentId required'.
- SessionService.listLockedSessions() — SCAN over agent:session:*
- POST /api/maint/session-status returns { locked, free } by joining
the platform Agent entities against Redis session locks
- orphan locks (Redis key with no matching Agent record) surface in
the Locked bucket so the operator can still clear stale lock state
Scenario: unknown caller books appointment (creates Patient), calls again, caller resolver links Lead↔Patient. On the second call the frontend found the lead in the worklist cache but it lacked patientId — so Book Appt pills couldn't find the prior appointment. The resolver had the right patientId; the worklist didn't.
Adding patientId to the GraphQL selection so the cached row carries it end-to-end.
Inbound transferred calls arrive with AgentName like 'RamaiahAdmin -> GlobalHealthX'. The webhook was persisting the raw chain string and leaving agentId null; the CDR enrichment cron then silently skipped 100% of rows because the bulk CDR keys on caller-leg UCID while the webhook stores monitorUCID — the join never matched.
- missed-call-webhook: split chain on ' -> ', take final handler,
resolve via AgentLookupService (ozonetelAgentId + display name)
- cdr-enrichment: index CDR rows by both UCID and monitorUCID so
the cron actually patches historical rows
- enrichment also parses chain in CDR AgentName as a second fallback
- spec: add CallerResolutionService + AgentLookupService mocks
Ozonetel's summaryReport only tallies CLOSED login→logout pairs — an
agent who's still logged in reports 00:00:00, so the KPI card on My
Performance always showed 0s for the current session.
Our AgentSession rollup already caps open sessions at "now" when it
runs. Endpoint now:
1. Triggers an on-demand rollupSessions(targetDate) to refresh the
AgentSession row (no 15-min wait after login)
2. Reads AgentSession and renders in the HH:MM:SS shape the frontend
expects
3. Falls back to Ozonetel's summaryReport when AgentSession is
empty (brand-new agent, workspace missing AgentEvent entity)
Works transparently — same timeUtilization shape as before, frontend
unchanged.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Populates clinicId on historical Appointments that predate clinicId
persistence. Infers from DoctorVisitSlot records:
1. Pull all appointments with clinicId=NULL
2. Pre-load visit slots per unique doctorId (batched)
3. For each appointment: match slots by weekday + time-window
4. Single clinic → use it
5. Multiple candidates → pick lex-order first (deterministic; logged)
6. Last resort → any slot's clinic
No CDR or rate-limited calls — pure platform queries. Safe to re-run;
idempotent (only patches rows still missing clinicId).
POST /api/maint/backfill-appointment-clinics
Header: x-maint-otp: <OTP>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
