Front Desk Journeys

Vocabulary

The holistic map

Read it top to bottom. A touchpoint hands the customer to an agent or to the website booking flow. The agent's turn ends in a classifier, and the classifier writes the disposition. From there a conversation ends three ways: booked, handed to a human, or sitting in a state with no rule. Every other state has a rule, and the rule schedules a follow-up by SMS or by outbound call. Both return to the same row, so the map is a loop, not a funnel. The pills travelling each edge are the states themselves.

Remark. The disposition row is shared by every journey. An inbound call, a website drop-off, and a follow-up SMS all write to the same conversation_states.state, and the follow-up engine cannot tell which one wrote it. The attribution section handles that.

Touchpoints

Two more entry points exist and are not on the map. Web chat (BookingAgentService.streamVisitorTurn) runs the same agent in the browser. An outbound call is an entry point in the customer's eyes; here it is the tail of journey J4.

Dispositions

The Postgres enum holds 48 states. A classifier may only return the states in its reachable set: 14 universal states plus a channel-specific group.

Three definitions matter for the booking metric. APPOINTMENT_BOOKED means the last successful book tool call returned confirmed: true or pendingApproval: true. CHECKOUT_LINK_SENT means a payment link went out and the deposit is pending. BOOKING_REQUESTED means the caller wanted to book and book did not succeed. The third is the one to watch: it is booking intent that the agent did not convert.

How a state changes

ConversationStateRepository.upsertState is the only writer. When the new state differs from the old one it does three things in order: deactivates every active, unprocessed follow-up for the client with reason Superseded by state transition from → to; removes the matching Bull jobs (win_followup_${id}); and writes an audit row state_transition / state_changed with changes: {from, to} and trace_id = the trigger id. Writing the same state again is a no-op. Nothing cancels a follow-up except a state change, a handover, or a DND flag.

Default follow-up rules

Rules resolve entity → cohort → defaults. The defaults are in ONBOARDING_DEFAULT_STATE_RULES; every rule has maxFollowUps: 1.

No post-call state has a default rule. BOOKING_REQUESTED, NEEDS_CALL_BACK, and GENERAL_INQUIRY after an inbound call get no follow-up unless the entity or its cohort has written one. After the last rule in a sequence fires, a no-response-transition job moves the state on.

Remark. There is one post-call SMS that does not go through rules. PostCallFallbackSmsService.dispatchIfNeeded fires when a transfer was attempted or when bucketState(state) is NEEDS_ACTION, and only if the entity has a transferNumber. It is tagged triggerSource: 'post_call_fallback', and it is the only SMS an inbound call sends on its own.

Journeys

Each journey is cut at a disposition write. A journey that ends in a state with a rule hands off to J3 or J4; one that ends in HUMAN_HANDOVER hands off to J6.

J1 · Inbound call

After the exit, two things happen that belong to other journeys. scheduleFollowUpsForCall runs getNextFollowUps and, if a rule exists, opens J3 or J4. ProcessCallTranscriptService.processCallTranscript writes a summary into the conversation so the SMS agent knows about the call.

-- J1 headline: inbound calls with booking intent, and how many booked
with post_call as (
  select a.trace_id as call_id,
         a.actor_id as entity_id,
         a.changes ->> 'to' as state
  from l2b.frontdesk_audit a
  where a.action = 'state_changed'
    and a.metadata ->> 'writer' = 'post_call_analysis'
)
select c.entity_id,
       count(*) filter (where p.state in ('APPOINTMENT_BOOKED', 'CHECKOUT_LINK_SENT', 'BOOKING_REQUESTED')) as intent,
       count(*) filter (where p.state = 'APPOINTMENT_BOOKED') as booked
from post_call p
join comms.call_comms c on c.retell_call_id = p.call_id
where c.direction = 'INBOUND'
group by 1;

J2 · Website self-serve

A customer who stops at any DROP_* state leaves J2 with a rule attached: PHONE @ 10 min, SMS @ 15 min, SMS @ 2 h. That is the hand-off to J4, then J3.

J3 · Win-back by SMS

J4 · Win-back by call

-- J3 + J4: every follow-up row and the state it produced next
select f.id as followup_id,
       f.conversation_state as from_state,
       f.mode_of_communication as channel,
       f.trigger,
       s.state as next_state
from chatbot.followups f
left join lateral (
  select l.state
  from chatbot.conversation_states_logs l
  where l.client_id = f.client_id
    and l.created_at > f.processed_at
  order by l.created_at
  limit 1
) s on true
where f.processed = true;

Remark. Last-touch credit. When a client runs J4 and then J3 before booking, the booking belongs to the journey whose disposition write is APPOINTMENT_BOOKED. The other run is scored as a non-conversion. This is a rule, not a fact about the customer, and it should be stated wherever the numbers are shown.

J5 · Inbound SMS

An SMS thread is not cut off, so it never produces CALL_DISCONNECTED or ABANDONED_CALL. It can produce ACTIVE_CONVERSATION and BOOKING_INTENT, which carry rules, so J5 hands off to J4 or J3 more often than J1 does.

J6 · Handover

Loops and repetition

States repeat. A client who books, cancels, and books again has been through APPOINTMENT_BOOKED twice, and the journeys are counted twice. The unit of measurement is the segment instance, not the client.

A worked sequence:

1. Website lead → DROP_LEAD_SP_GENERATED (J2 opens and stops).
2. PHONE rule @ 10 min → outbound call, no answer → state preserved (J4 run 1, non-conversion).
3. SMS rule @ 15 min → SMS sent, no reply (J3 run 1, no write).
4. Customer calls in the next day → BOOKING_REQUESTED (J1 run 1, intent, not converted).
5. Customer texts "can I do 3pm" → SMS agent books → APPOINTMENT_BOOKED (J5 run 1, converted).

Five instances across four journeys, one booking, credited to J5. Step 4 is the J1 metric's denominator and not its numerator, which is the correct reading: the call agent had the intent and did not close it.

Segment instances are delimited by writes, not by time. The boundary between step 2 and step 3 is the follow-up row, not the 5 minutes between them. If two writes happen in the same second, the conversation_states_logs.log_id sequence orders them.

Metrics

Each owner gets its own table. Do not average across owners; a good SMS agent and a bad call agent average to a meaningless number.

Sources. State writes come from l2b.frontdesk_audit rows with action = 'state_changed' (or chatbot.conversation_states_logs for history before the audit table). Calls come from comms.call_comms (direction, status) and chatbot.transcript_mapping (tool calls, transfer status, post-call analysis). Follow-ups come from chatbot.followups. Tool outcomes come from l2b.frontdesk_audit rows with action_category = 'platform_tool'.

Attributing tool failures

The same 19 tools are served by one MCP server, frontdesk-agent on apps/servers/scp-server, to the inbound voice agent, the outbound voice agent, and the SMS agent. A tool failure lands in l2b.frontdesk_audit through FrontdeskAuditRepository.initiate() / complete() / fail() with this shape:

trace_id          call_* for voice, a uuid for SMS
actor_id          entity_id
client_id         may be null on a voice call before the caller is identified
conversation_id   null on voice
action_category   platform_tool | state_transition | followup |
                  call_lifecycle | disposition | handover | sms
actor_type        agent | system | scheduler | sp | customer
action            e.g. create_booking, state_changed, followup_skipped
resource_type     appointment | booking | availability | service
status            initiated | completed | failed
changes           {from, to}
metadata          {writer, …}

There is no channel or journey column. To find the journey of a failed platform_tool row:

1. trace_id starts with call_ → join comms.call_comms.retell_call_id; direction = 'INBOUND' is J1, OUTBOUND is J4.
2. Otherwise the row is an SMS turn. If a chatbot.followups row for the client was processed in the minutes before it, the turn is a J3 reply; otherwise it is J5.
3. action_category = 'followup' rows belong to the engine regardless of channel.

Step 2 is a heuristic. The fix is to stamp metadata.journey at the start of every trace: the webhook knows it is inbound, the processor knows it is a follow-up, and the SMS handler can check for an open follow-up before the first tool runs. One field, written once per trace, and the join goes away.

Remark. check-availability is voice-only, so a failure in it can only belong to J1 or J4. request-human-handover is voice-only as a tool; the SMS agent reaches J6 through a system path.

Data model

website.booking_enquiries  be   (client_id, entity_id, source, status, booking_id, attributes)
  └─ clients.clients        c    c.id = be.client_id
      └─ chatbot.conversation_states  cs   cs.client_id = c.id        -- one row per client
          └─ chat.conversations       cv   cv.id = cs.conversation_id
              └─ chat.members / chat.messages
  └─ scheduling.bookings    b    b.id = be.booking_id
  └─ scheduling.carts       ct   ct.enquiry_id = be.id
chatbot.transcript_mapping  tm   (call_id, client_id, entity_id, status, metadata, post_call_analysis)
comms.call_comms            cc   cc.retell_call_id = tm.call_id       -- direction INBOUND | OUTBOUND
chatbot.followups           f    (client_id, entity_id, conversation_state, mode_of_communication, trigger, processed_at, deactivation_reason)
chatbot.human_handovers     hh   (client_id, is_active, deactivate_at)   -- no entity_id
l2b.frontdesk_audit         a    (trace_id, actor_id = entity_id, client_id, action_category, action, status)

Three facts about identity. conversation_states.client_id is unique across the table, so a client who talks to two locations shares one state row. scheduling.bookings has no channel, source, or call id; the link to a journey runs through booking_enquiries.booking_id or through the state write that recorded it. transcript_mapping.metadata.direction holds 'inbound', 'outgoing' at dial time, and 'outbound' from the webhook, so filter on call_comms.direction instead.

Known gaps

• No journey stamp on audit rows. Attribution for SMS relies on a time-window heuristic.
• No default rule for post-call states. BOOKING_REQUESTED from an inbound call gets no follow-up unless the entity has one; this is the largest untouched intent in J1.
• Call context flows to SMS; SMS context does not flow to calls. ConversationsRepository.updateSummary has no callers.
• direction is spelled three ways in transcript_mapping.metadata.
• The legacy libs/chatbot engine still holds one rule (HUMAN_HANDOVER, PHONE, 2 h, ×100). It is not on the win path.

Mapped. Not yet measured.