whatsapp-lead-qualifier

WhatsApp lead qualifier

This is the canonical example of a multi-turn WhatsApp skill that doesn't need an external state store. State lives on the TimelinesAI chat — as labels for discrete stages, notes for structured answers — and the skill reads it from the chat on every invocation.

State model

What	Where	Example
Current stage	Chat label	discovery/q1, discovery/q2, discovery/q3, qualified, disqualified
Collected answers	Chat notes	[LEAD] use_case=onboarding, [LEAD] team_size=8, [LEAD] timeline=2_weeks
Stop-reply	Chat label	escalate, needs-human, pause-bot

The labels are the state machine. The notes are the data. Together they replace any external database for this flow.

Question sequence

q1: "What are you trying to solve?"           → answer stored as [LEAD] use_case=...
q2: "How big is your team?"                   → answer stored as [LEAD] team_size=...
q3: "When do you want to start?"              → answer stored as [LEAD] timeline=...

At the end of q3, the skill applies a qualification rule — default is team_size >= 5. Customize this in step 5 below.

Loop

You receive a webhook payload with the incoming customer message. Run these steps in order:

Step 1 — Verify chat ownership

Same as every other send-capable skill. Skip if the chat's whatsapp_account_id doesn't match $ALLOWED_SENDER_JID.

CHAT_JID=$(curl -sS -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
  "https://app.timelines.ai/integrations/api/chats/$CHAT_ID" \
  | jq -r '.data.whatsapp_account_id')

[ "$CHAT_JID" != "$ALLOWED_SENDER_JID" ] && exit 0

Step 2 — Read the current stage

LABELS=$(curl -sS -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
  "https://app.timelines.ai/integrations/api/chats/$CHAT_ID/labels" \
  | jq -r '.data.labels[]? // empty')

# Stop entirely if already finished or handed off to a human
case "$LABELS" in
  *qualified*|*disqualified*|*escalate*|*needs-human*|*pause-bot*)
    echo "lead already resolved or paused — exiting"
    exit 0
    ;;
esac

# Find the current discovery stage label
STAGE=$(echo "$LABELS" | grep -oE 'discovery/q[123]' | head -1)